CLIProxyAPI: The Free, Open Source Proxy That Turns CLI Tool Subscriptions Into OpenAI-Compatible API Endpoints (2026 Guide)

Many AI companies offer generous free tiers or flat-rate unlimited usage through their CLI tools like Claude Code, Google Gemini CLI, and OpenAI Codex. But the moment you want to use those same models through a standard REST API, the pricing flips to expensive per-token billing. If you want to use Claude or Gemini inside an AI IDE like Cursor or Windsurf, you are stuck paying API rates even though you already have a CLI subscription that includes the same models.

CLIProxyAPI is a free, open source proxy server written in Go that solves this by acting as a universal translation layer. It wraps CLI tools like Claude Code, Gemini CLI, Codex, Qwen, and Grok Build through their native OAuth flows, then exposes those connections locally as standard OpenAI, Anthropic, or Gemini API endpoints. Your IDE thinks it is talking to the official OpenAI API, but CLIProxyAPI intercepts the request, translates the format, and routes it through your free or flat-rate CLI subscriptions.

In this guide, you'll learn what CLIProxyAPI is, who it's for, and how to deploy it with Docker and connect it to your AI IDE.

What is CLIProxyAPI?

CLIProxyAPI is an open source proxy server written in Go that acts as a universal translation layer for AI models. It solves a fundamental pricing and accessibility problem: many AI companies offer free or flat-rate usage through their CLI tools but charge expensive per-token fees for their REST APIs. CLIProxyAPI bridges this gap by wrapping the CLI tools through their native OAuth authentication flows and exposing those connections as standard, fully compatible API endpoints on your local machine.

The proxy supports tools like Claude Code, Google Gemini CLI, OpenAI Codex, Qwen, and Grok Build. It securely authenticates with each provider using their native OAuth device code flows, stores the tokens locally, and handles token refreshes automatically in the background. You never need to manually extract cookies or session tokens.

On the output side, CLIProxyAPI exposes standard OpenAI, Anthropic, or Gemini API formats. This means you can plug it directly into any application that expects an OpenAI-compatible endpoint, including AI IDEs like Cursor, Windsurf, or Cline, as well as custom Python scripts and multi-agent frameworks. The application sends a standard OpenAI-formatted request to localhost, and CLIProxyAPI translates the message schema to match the target provider's format before routing it through your CLI subscription.

The proxy also includes smart load balancing. If you load multiple OAuth credential files for the same provider, it distributes requests across them using round-robin or fill-first strategies, automatically failing over to the next account if one hits a quota limit. You can also configure model aliasing, so if an application requests gpt-4o, the proxy can silently route that request to gemini-2.5-pro or claude-sonnet-4 instead.

Who is it for?

Developers using AI IDEs: Developers who want to leverage their flat-rate CLI tool subscriptions like Claude Code or Gemini CLI to write code in Cursor, Windsurf, or Cline, rather than paying massive per-token API bills.
Power users with multiple accounts: Users who keep hitting rate limits and want to load several Gemini or Claude accounts into the proxy for automatic load balancing across all of them.
Enterprise teams and homelabbers: Teams looking to pool their individual AI subscriptions into one centralized, high-concurrency local API endpoint for their entire internal network.
AI tinkerers: Developers who want to use models that natively speak one format like Gemini inside applications that are hardcoded to only accept OpenAI-formatted requests.

What makes CLIProxyAPI different from other API proxies?

Seamless format translation: It does not just route traffic, it translates the message schema. You can send a standard OpenAI-formatted API request and it will automatically convert it to work with Gemini or Claude on the fly, including tool calls, system prompts, and streaming responses.
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, so your sessions stay alive without manual intervention.
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 to gemini-2.5-pro or claude-sonnet-4 instead.
Built-in management web UI: A dashboard at localhost:8317/management.html lets you authenticate new providers, view token status, and re-authenticate expired sessions without touching the command line.
Free and open source: The entire proxy is free and open source. No subscription, no per-request pricing, full access to the source code for self-hosting and modification.

What you need before you start

CLIProxyAPI acts as a background server on your machine. Make sure you have the following:

An operating system: Runs on macOS, Linux, or Windows. Docker is the recommended deployment method for all platforms.
AI accounts: You must have active accounts or subscriptions for the services you want to proxy, such as a Google account for Gemini CLI or an Anthropic account for Claude Code.
Docker: The easiest way to run the proxy without polluting your host environment. Alternatively, macOS users can install via Homebrew.
A config file: The proxy will not start unless you have a config.yaml file defining your server port and routing strategy.
An AI IDE or client: Cursor, Windsurf, Cline, or any application that supports custom OpenAI-compatible API endpoints.

Step-by-step installation

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.yaml

Open the config.yaml file in a text editor and add a basic configuration block:

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

On macOS, you can alternatively install via Homebrew: 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.html

From this dashboard, click on the specific provider you want to connect, such as 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. Repeat this process for each account you want to load for load balancing.

Step 4: Connect your IDE

Now that the proxy is running and authenticated, open your AI editor. In Cursor:

Go to Settings, then Models.
Add a Custom OpenAI Endpoint.
Set the Base URL to http://localhost:8317/v1.
Set the API Key to anything, such as dummy-key, since the proxy handles the real authentication.

You can now chat with your code using your CLI subscriptions. The same approach works for Windsurf, Cline, or any application that supports custom OpenAI-compatible endpoints.

Common errors and how to fix them

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 with `docker logs cliproxyapi`. If the proxy crashed on startup, it is usually because the `config.yaml` file is missing or formatted incorrectly. Verify the YAML syntax.
401 Unauthorized / token expired	The underlying OAuth credential for the CLI tool, such as 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-sonnet-4`.	Edit your `config.yaml` and add a model mapping block. Tell the proxy to intercept requests for `gpt-4` and route them to `claude-sonnet-4` instead.
Rate limit hit on all accounts	All your loaded accounts for a single provider have hit their daily or hourly quota limits simultaneously.	Add more accounts to the pool, or switch to a different provider temporarily by updating your model aliasing config to route to a provider with remaining quota.

CLIProxyAPI vs official provider APIs

Feature	CLIProxyAPI (open source)	Official provider APIs (OpenAI, Anthropic)
Usage cost	$0, leverages free CLI tiers or flat-rate subscriptions	Pay-per-token, can cost hundreds of dollars
Rate limits	Bound by your specific CLI account tier	Massive enterprise limits available for a price
Load balancing	Yes, pool multiple accounts together automatically	Not available, requires writing your own fallback logic
Format translation	Converts OpenAI endpoints to Claude and Gemini formats	Strictly locked to their own API schemas
Model flexibility	Alias any model name to any provider	Locked to vendor's model list
Best for	Developers who want to use CLI subscriptions in their IDE	Teams who need guaranteed enterprise-grade uptime and limits

Bottom line: CLIProxyAPI is a game-changer for heavy AI users. By acting as a universal adapter, it lets you 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. While official APIs charge per token and lock you into their format, CLIProxyAPI is free, open source, and translates between all major providers automatically. For any developer with a CLI subscription, this is the best free tool to maximize its value.

3 alternatives worth checking out

LiteLLM (github.com/BerriAI/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 and track spend across teams, while CLIProxyAPI specifically focuses on wrapping CLI tool authentications and OAuth sessions to bypass API key fees entirely.
One-API (github.com/songquanpeng/one-api): An incredibly popular open source API aggregator dashboard. It lets you pool hundreds of different paid API keys into a single endpoint with a billing dashboard, user management, and quota limits. It is designed for resellers or large enterprises, whereas CLIProxyAPI is tailored toward individuals and small teams exploiting CLI-based endpoints.
TokenProxy (github.com/cs50victor/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 integrated web UI and the deep ecosystem of specific CLI tool wrapping like Codex or Grok Build support.

Found this guide useful? Check out more free tools for developers and AI tools on Sudo Scout.