Getting started

Start one proxy, connect a provider, and generate a Claude Code launch command. Use Docker for an isolated profile or install the native binary. Both support the browser setup UI and independent Default, Opus, Sonnet, and Haiku models.

Install Claude Code on the host and confirm claude --version works. Your project and tools stay on that host.

Get the source

Use the GitHub CLI with an account that can access the maintained source repository:

GH_HOST=github.com gh repo clone fydo-dev/claude-code-proxy -- --branch ninja
cd claude-code-proxy

These guides describe the current source checkout. Build it before using new commands or UI features.

Guided setup with Docker

You need a running Docker engine with Compose v2, repository and provider access, an account with model access, and a free loopback port (normally 18765). Host Rust and provider CLIs are not required for this path. See the complete requirements. Docker Hub and Quay.io images are public and need no registry login. GHCR remains private. See available images. Run from the checkout:

export CCP_IMAGE=docker.io/c0mpiler/claude-code-proxy:0.2.0
docker compose pull
docker compose up -d --no-build --wait
docker compose exec proxy claude-code-proxy ui --print-url

Open the private link, sign in to a provider, choose the four models, and use Verify to check inference. Save the profile and copy the generated command into a host terminal. Credentials and selections persist in the named volume across container replacement.

If a native proxy already uses port 18765, follow the alternate port recipe. See Docker setup and updates for prerequisites, storage, updates, and verification.

1. Install

For a native installation, use a current stable Rust toolchain in a source checkout:

cargo install --locked --path .
claude-code-proxy serve

In a second terminal, open the browser setup flow:

claude-code-proxy ui --print-url

Follow Local setup UI to sign in and generate your launch configuration. The remaining steps provide the equivalent manual CLI setup, including the Cursor recipe with Gemini as Default and Sonnet, Claude Opus for Opus, and Grok for Haiku.

After installing an update, stop the old proxy process and restart the intended executable. claude-code-proxy --version reports the executable on your current PATH, which can differ from a server that is already running. If several installations exist, use command -v claude-code-proxy on macOS or Linux and start that executable explicitly. See Troubleshooting for listener checks.

2. Choose and authenticate a provider

Codex

Use a ChatGPT account with Codex access. This connection uses ChatGPT sign in rather than an OpenAI Platform API key:

claude-code-proxy codex auth login

For SSH or another headless environment, use claude-code-proxy codex auth device instead.

Cursor

Use your Cursor account with the proxy’s own login:

claude-code-proxy cursor auth login
claude-code-proxy models --full

The native Cursor application does not need to be running. Confirm that the model selections in the launch recipe are advertised for your account. See Cursor Agent for protocol and client-version details.

3. Start the proxy

Keep this process running:

claude-code-proxy serve

It listens on 127.0.0.1:18765. In an interactive terminal it opens the monitor TUI.

From another terminal, check that the listener responds:

curl http://127.0.0.1:18765/healthz

{"ok":true} establishes that the proxy is running. A short model request in the next step verifies the provider connection.

4. Start Claude Code

Open another terminal and use the recipe for the provider you authenticated. These shell recipes work in Bash and Zsh; on Windows, use a Bash environment or the JSON settings file.

Codex launch

ANTHROPIC_BASE_URL=http://127.0.0.1:18765 \
ANTHROPIC_AUTH_TOKEN=unused \
ANTHROPIC_MODEL='gpt-6-sol' \
ANTHROPIC_DEFAULT_OPUS_MODEL='gpt-6-sol' \
ANTHROPIC_DEFAULT_SONNET_MODEL='gpt-5.6-terra' \
ANTHROPIC_DEFAULT_HAIKU_MODEL='gpt-6-luna' \
CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 \
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 \
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 \
  claude

Cursor launch with Gemini, Opus, and Grok

ANTHROPIC_BASE_URL=http://127.0.0.1:18765 \
ANTHROPIC_AUTH_TOKEN=unused \
ANTHROPIC_MODEL='cursor:gemini-4-argon[reasoning_effort=high]' \
ANTHROPIC_DEFAULT_SONNET_MODEL='cursor:gemini-4-argon[reasoning_effort=high]' \
ANTHROPIC_DEFAULT_OPUS_MODEL='cursor:claude-opus-5-5[context=1m,effort=high,fast=false]' \
ANTHROPIC_DEFAULT_HAIKU_MODEL='cursor:grok-4.7-high-fast' \
CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 \
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 \
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 \
  claude

This starts the main conversation and Sonnet role on Gemini, assigns the Opus role to Claude Opus, and sends Haiku background work to Grok. All four selections route through Cursor. The role names describe Claude Code’s choices; they do not require matching model families.

These selections were present in the observed account catalog. Check claude-code-proxy models --full for your account before copying them. Availability can change: Gemini requests returned upstream HTTP 429 during the latest walkthrough, so that recording uses Cursor GLM 5.2 and Grok 4.7 instead. An advertised catalog entry alone does not establish inference access. The 200K compaction boundary is conservative, including when the selected Opus variant has a larger window.

Quote model values in shell commands, especially IDs containing brackets, commas, or other shell syntax. Preserve the exact advertised parameter names and values. Shell quotes protect the value; they are not part of the model ID. In JSON settings, use ordinary JSON strings without adding shell quotes.

Send a prompt. The request appears in the monitor and the response streams into Claude Code.

The ANTHROPIC_DEFAULT_*_MODEL values pin Claude Code’s Opus, Sonnet, and Haiku roles to backend IDs. The 200K compaction boundary is conservative; raise it only after checking the actual upstream window. In Claude Code, use /status to inspect the session and /model to choose a discovered model.

For persistent settings, provider switching, and model discovery, continue to Configure Claude Code and Models and routing.