🔴 Advanced ⚙️ Type: AI API Proxy / Model Router 💸 Free & Open Source ⭐ 15,000+ GitHub Stars
What is CLIProxyAPI?
CLIProxyAPI is an incredibly powerful, open-source proxy server written in Go that acts as a universal translation layer for AI models. It solves a massive pricing and accessibility problem in the developer world: many AI companies offer generous “free” tiers or unlimited usage through their CLI (Command Line Interface) tools, but charge expensive, per-token fees if you try to use their standard REST APIs.
CLIProxyAPI wraps tools like Claude Code, Google Gemini CLI, OpenAI Codex, Qwen, and Grok Build, securely authenticating via their native OAuth flows. It then exposes those connections locally as standard, fully compatible OpenAI, Anthropic, or Gemini API endpoints.
This means you can plug CLIProxyAPI directly into modern AI IDEs (like Cursor, Windsurf, or Cline) or multi-agent swarms. The IDE thinks it is talking to the expensive official OpenAI API, but CLIProxyAPI intercepts the request, translates it, and routes it through your free or flat-rate CLI subscriptions.
Who is it for?
- Developers using AI IDEs (Cursor, Windsurf, Cline) who want to leverage their flat-rate CLI tool subscriptions to write code, rather than paying massive per-token API bills.
- Power Users with Multiple Accounts who keep hitting rate limits. You can load five different Gemini or Claude accounts into the proxy, and it will load-balance your requests across all of them automatically.
- Enterprise Teams & Homelabbers looking to pool their individual AI subscriptions into one centralized, high-concurrency local API endpoint for their entire internal network.
- AI Tinkers who want to use models that natively speak one format (like Gemini) inside applications that are hardcoded to only accept OpenAI formats.
What makes it special?
- Seamless Format Translation — It doesn’t just route traffic; it translates it. You can send a standard OpenAI-formatted API request to the proxy, and it will automatically convert the message schema to work with Gemini or Claude on the fly.
- Smart Load Balancing — If you have multiple OAuth credential files loaded, CLIProxyAPI uses “round-robin” or “fill-first” strategies to distribute requests, automatically failing over to the next account if one hits a quota limit.
- Automated OAuth Management — You do not need to constantly extract cookies or manual session tokens. It natively handles Device Code flows and token refreshes in the background.
- Model Aliasing — You can rename models on the fly. If an application requires
gpt-4o, you can tell the proxy to intercept that name and silently route the prompt togemini-3.1-proinstead.
Requirements before you start
CLIProxyAPI acts as a background server on your machine. You will need:
- An Operating System — Runs on macOS, Linux, or Windows.
- AI Accounts — You must have active accounts/subscriptions for the services you want to proxy (e.g., a Google account for Gemini CLI, or an Anthropic account for Claude Code).
- Docker (Optional but Recommended) — The easiest way to run the proxy without polluting your host environment.
- A Default Config File — The proxy will not start unless you have a
config.yamlfile defining your routes.
Step-by-step installation
There are several ways to install CLIProxyAPI depending on your system, but Docker is generally the safest and most reliable for long-term background usage.
Step 1 — Create Your Configuration Directory
Open your terminal and create a hidden folder to store your config and OAuth credential files:
mkdir -p ~/.cli-proxy-api
touch ~/.cli-proxy-api/config.yamlOpen the config.yaml file in a text editor and add a basic configuration block (refer to the official docs for advanced multi-account routing):
server:
port: 8317
routing:
strategy: "round-robin"Step 2 — Launch via Docker
Start the proxy server using Docker, mapping your local configuration folder into the container:
docker run -d --name cliproxyapi \
--restart always \
-p 8317:8317 \
-v ~/.cli-proxy-api/config.yaml:/CLIProxyAPI/config.yaml \
-v ~/.cli-proxy-api:/root/.cli-proxy-api \
eceasy/cli-proxy-api:latest(Mac users who prefer Homebrew can simply run: brew install cliproxyapi and brew services start cliproxyapi).
Step 3 — Authenticate Your Accounts
CLIProxyAPI includes a built-in Management Web UI. Open your browser and navigate to:
http://localhost:8317/management.htmlFrom this dashboard, you can click on the specific provider (e.g., Claude Code or Gemini) and follow the on-screen OAuth instructions to log in. The proxy will save the secure tokens into your ~/.cli-proxy-api/ folder automatically.
💡 Pro-Tip: Securing Multiple AI Accounts
If you are loading multiple accounts (like 5 different Gemini or Claude CLI sessions) into CLIProxyAPI for load balancing, providers may flag your accounts for suspicious activity if they all suddenly connect from the same home IP address.
To keep your accounts safe from bans, route your CLIProxyAPI Docker container through a reliable proxy. We highly recommend Proxy-Seller for clean, residential IPs that AI providers trust. Use our community code GLOBALAI15 for 15% off.
Step 4 — Connect Your IDE (Cursor / Windsurf)
Now that the proxy is running and authenticated, open your AI editor (like Cursor).
- Go to Settings > Models.
- Add a Custom OpenAI Endpoint.
- Set the Base URL to:
http://localhost:8317/v1 - Set the API Key to anything (e.g.,
dummy-key) as the proxy handles the real authentication.
You can now chat with your code using your CLI subscriptions!
Common errors and fixes
| Error | What it means | How to fix it |
|---|---|---|
Connection Refused on port 8317 | Your IDE or script cannot reach the proxy. The service is either not running or blocked by a firewall. | Check your Docker logs (docker logs cliproxyapi). If the proxy crashed immediately upon startup, it is usually because the config.yaml file is missing or formatted incorrectly. |
401 Unauthorized / Token Expired | The underlying OAuth credential for the CLI tool (e.g., your Gemini login) has expired or was revoked by the provider. | Open the /management.html dashboard in your browser and click “Re-authenticate” on the failing provider to generate a fresh token. |
Model Not Found | Your client requested a model (like gpt-4), but the CLI tool you are proxying into only understands specific model names (like claude-3-5-sonnet). | Edit your config.yaml and add a model mapping block. Tell the proxy to automatically intercept requests for gpt-4 and route them to claude-3-5-sonnet instead. |
Free vs Paid comparison
| Feature | CLIProxyAPI (Local Open Source) | Official Provider APIs (OpenAI / Anthropic) |
|---|---|---|
| Usage Cost | 🟢 $0 (Leverages free CLI tiers or flat-rate subs) | 🔴 Pay-per-token (can cost hundreds of dollars) |
| Rate Limits | ⚠️ Bound by your specific CLI account tier | 🟢 Massive enterprise limits available |
| Load Balancing | ✅ Yes (Pool multiple accounts together) | ❌ N/A (Requires writing your own fallback logic) |
| Format Translation | ✅ Converts OpenAI endpoints to Claude/Gemini | ❌ Strictly locked to their own API schemas |
Bottom line: CLIProxyAPI is an absolute game-changer for heavy AI users. By acting as a universal adapter, it allows you to break free from vendor lock-in and avoid staggering API bills. If you are already paying for a flat-rate subscription like Claude Code or using the free tiers of Gemini CLI, spinning up this proxy lets you use those exact same models inside Cursor or your custom Python scripts without spending an extra dime.
Alternatives — 3 similar tools
1. LiteLLM
The industry standard for API translation and load balancing. Like CLIProxyAPI, LiteLLM translates OpenAI formats into Claude, Gemini, and 100+ other providers. However, LiteLLM is primarily designed to manage paid API keys, tracking spend across teams. CLIProxyAPI specifically focuses on wrapping CLI tool authentications and OAuth sessions to bypass API key fees.
2. One-API
An incredibly popular open-source API aggregator dashboard. It allows you to pool hundreds of different paid API keys into a single endpoint, complete with a beautiful billing dashboard, user management, and quota limits. It is designed for resellers or massive enterprises, whereas CLIProxyAPI is tailored toward individuals and small teams exploiting CLI-based endpoints.
🔗 github.com/songquanpeng/one-api
3. TokenProxy
A fast, Rust-based alternative that pools multiple ChatGPT, OpenAI, and Anthropic accounts behind one proxy server with automatic failover. It is lighter weight than CLIProxyAPI but lacks the expansive integrated Web UI and deep ecosystem of specific CLI tool wrapping (like Antigravity or Grok Build).
🔗 github.com/cs50victor/tokenproxy
🚀 Want more free AI tools like this?
We find, test, and write setup guides for the best free and open-source AI tools — so you don’t have to dig through GitHub yourself.Browse Free AI Tools at globalaiforce.com/shop →
📸 Follow us for daily AI tool tips and tutorials: instagram.com/globalaiforce