Claude Code Proxy

The single-file version is recommended for deployment. It produces a standalone executable.

# Quick single-file packaging
uv run pyinstaller --onefile --name claude-code-proxy-single src/main.py

To run the proxy in a production environment on Linux, follow these steps to create a systemd service.

1. Upload the binary to your server (e.g., /opt/claude-proxy/).
2. Create a .env file at /opt/claude-proxy/.env containing your API keys and configuration.
3. Create the service file at /etc/systemd/system/claude-proxy.service:

[Unit]
Description=Claude Code Proxy
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/claude-proxy
EnvironmentFile=/opt/claude-proxy/.env
ExecStart=/opt/claude-proxy/claude-code-proxy-single
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

4. Start the service:

systemctl daemon-reload
systemctl start claude-proxy
systemctl enable claude-proxy

You can customize the packaging process to include specific modules or data files.

Include specific modules:

uv run pyinstaller --onefile --hidden-import=src.api.endpoints src/main.py

Include data files:

uv run pyinstaller --onefile --add-data="src:src" src/main.py

Install the necessary dependencies using either uv (recommended) or pip.

# Using UV (recommended)
uv sync

# Or using pip
pip install -r requirements.txt

Once packaged, you can execute the binary using the following methods.

Basic Execution:

# Directory version
./dist/claude-code-proxy/claude-code-proxy

# Single-file version
./dist/claude-code-proxy-single

With Environment Variables: Required: OPENAI_API_KEY. Optional: ANTHROPIC_API_KEY, HOST, PORT, LOG_LEVEL.

# Run in foreground
OPENAI_API_KEY="your-key" ./claude-code-proxy

# Run in background
OPENAI_API_KEY="your-key" nohup ./claude-code-proxy &

1. Start the proxy server using python start_proxy.py.
2. In a separate terminal, run the claude CLI while overriding the ANTHROPIC_BASE_URL to point to the proxy (defaulting to http://localhost:8082).

# Start the proxy server
python start_proxy.py

# In another terminal, use with Claude Code
ANTHROPIC_BASE_URL=http://localhost:8082 claude

The directory version is recommended for development and testing. It produces a folder containing the executable and its dependencies.

# Use custom spec file
uv run pyinstaller claude-proxy.spec

You can install the dependencies using either uv (recommended) or pip.

Using UV:

uv sync

Using pip:

pip install -r requirements.txt

# Using UV (recommended)
uv sync

# Or using pip
pip install -r requirements.txt

To route the Claude Code CLI through the proxy, set the ANTHROPIC_BASE_URL environment variable to the proxy's address (default is http://localhost:8082).

If ANTHROPIC_API_KEY is NOT set in the proxy: You must provide any value for the key in your shell.

If ANTHROPIC_API_KEY IS set in the proxy: You must provide the exact matching key in your shell for validation.

# If ANTHROPIC_API_KEY is not set in the proxy:
ANTHROPIC_BASE_URL=http://localhost:8082 ANTHROPIC_API_KEY="any-value" claude

# If ANTHROPIC_API_KEY is set in the proxy:
ANTHROPIC_BASE_URL=http://localhost:8082 ANTHROPIC_API_KEY="exact-matching-key" claude

To package the project into binary executables, you must install pyinstaller as a development dependency using uv.

# Install PyInstaller using uv
uv add --dev pyinstaller

You can start the server using several methods:

Directly with Python:

python start_proxy.py

Using UV:

uv run claude-code-proxy

Using Docker Compose:

docker compose up -d

# Direct run
python start_proxy.py

# Or with UV
uv run claude-code-proxy

# Or with docker compose
docker compose up -d

The application uses python-dotenv to automatically load environment variables from a .env file in the project root.

1. Copy the template: cp .env.example .env
2. Edit the .env file with your provider credentials and model settings.