Remote Proxy

Overview

By default, CCS runs CLIProxyAPI as a local binary on your machine. With Remote Proxy, you can connect to a CLIProxyAPI server running on a different machine—Docker container, Kubernetes pod, or dedicated server. Use cases:

Run CLIProxyAPI on a powerful server while working from a laptop
Share a single CLIProxyAPI instance across multiple machines
Deploy CLIProxyAPI in Docker/Kubernetes for team use
Reduce local resource usage

Configuration Methods

CCS supports three ways to configure remote proxy, with the following priority:

Priority	Method	Use Case
1 (Highest)	CLI Flags	One-time overrides
2	Environment Variables	CI/CD automation
3 (Lowest)	config.yaml	Persistent settings

Skip Local OAuth

When connecting to a remote proxy with authentication, you can skip local OAuth entirely. This is useful when the remote server already has authenticated tokens. How it works:

If --proxy-auth-token is provided, CCS skips local OAuth flow
The remote server handles all authentication
No local token storage needed

Use cases:

Shared team proxy with centralized auth
CI/CD pipelines using pre-authenticated remote proxy
Docker/Kubernetes deployments with service tokens

Example:

# Skip local OAuth - remote server authenticates
ccs codex --proxy-host team-proxy.internal --proxy-auth-token <token>

# Remote server handles OAuth, local client just proxies requests

Configuration:

cliproxy_server:
  remote:
    enabled: true
    host: "team-proxy.internal"
    auth_token: "service-token"  # Enables skip-local-auth

Dashboard Configuration

The easiest way to configure remote proxy is via the web dashboard:

Run ccs config to open the dashboard
Navigate to Settings → Proxy tab
Select Remote mode
Enter your remote server details:
- Host: Server hostname or IP address
- Port: CLIProxyAPI port (default: 8317)
- Protocol: HTTP or HTTPS
- Auth Token: Optional authentication token
- Backend: Select CLIProxy backend (original/plus)
Click Test Connection to verify connectivity
Configure fallback options as needed

Available since v7.37.0 - Backend switching allows choosing between original CLIProxyAPI and CLIProxyAPIPlus backends.

Backend Selection

Available Backends:

original - Standard CLIProxyAPI (default)
plus - CCS-maintained CLIProxyAPIPlus community fork for plus-only providers

Configuration:

cliproxy:
  backend: 'original'  # or 'plus'

Dashboard dropdown provides visual selection with auto-detection of available backends.

HTTPS Tunnel

When using --proxy-protocol https, CCS automatically starts a local HTTP→HTTPS tunnel that forwards requests to the remote HTTPS server. This is required because Claude Code’s HTTP client (undici) doesn’t support HTTPS in ANTHROPIC_BASE_URL. Architecture Flow:

Claude Code → HTTP (localhost:random) → HttpsTunnelProxy → HTTPS (remote:443)

Key Features:

Automatic activation - No manual flag needed, activates when protocol=https
Self-signed certificate support - Use --allow-self-signed for dev/test environments
Transparent streaming - No buffering, preserves real-time streaming
Authorization injection - Auth token automatically added to outbound HTTPS requests
No SSL configuration - Tunnel handles all HTTPS complexity internally

Example:

# HTTPS with self-signed cert (tunnel activates automatically)
ccs codex --proxy-host secure.example.com --proxy-protocol https --allow-self-signed

# HTTPS with auth token
ccs codex --proxy-host proxy.internal --proxy-protocol https --proxy-auth-token <token>

Technical Details:

Tunnel binds to random available port on localhost
Only Claude Code can access the tunnel (127.0.0.1)
Tunnel terminates when CCS session ends
No manual SSL certificate installation required

Config File

Add the cliproxy_server section to ~/.ccs/config.yaml:

# CLIProxy Server Configuration
cliproxy_server:
  remote:
    enabled: true                    # Enable remote mode
    host: "192.168.1.100"           # Remote server hostname/IP
    port: 8317                       # CLIProxyAPI port
    protocol: http                   # http or https
    auth_token: ""                   # Optional auth token
  fallback:
    enabled: true                    # Fallback to local if remote unreachable
    auto_start: true                 # Auto-start local proxy on fallback
  local:
    port: 8317                       # Local proxy port
    auto_start: true                 # Auto-start when needed

Configuration Options

Remote Settings

Option	Type	Default	Description
`enabled`	boolean	`false`	Enable remote proxy mode
`host`	string	`""`	Remote server hostname or IP
`port`	number	`8317`	CLIProxyAPI port
`protocol`	string	`http`	`http` or `https`
`auth_token`	string	`""`	Bearer token for authentication

Fallback Settings

Option	Type	Default	Description
`enabled`	boolean	`true`	Fall back to local proxy if remote unreachable
`auto_start`	boolean	`true`	Auto-start local proxy on fallback

Local Settings

Option	Type	Default	Description
`port`	number	`8317`	Local CLIProxyAPI port
`auto_start`	boolean	`true`	Auto-start local proxy when needed

CLI Flags

Override configuration for a single command:

# Connect to remote proxy
ccs codex --proxy-host 192.168.1.100 --proxy-port 8317

# Force local mode (ignore remote config)
ccs codex --local-proxy

# Strict remote mode (fail if unreachable, no fallback)
ccs codex --proxy-host remote.example.com --remote-only

# Use HTTPS with auth token
ccs codex --proxy-host secure.example.com --proxy-protocol https --proxy-auth-token "secret"

Available Flags

Flag	Description
`--proxy-host <host>`	Remote proxy hostname/IP
`--proxy-port <port>`	Proxy port (default: 8317)
`--proxy-protocol <proto>`	Protocol: `http` or `https`
`--proxy-auth-token <token>`	Auth token for remote proxy
`--local-proxy`	Force local mode, ignore remote config
`--remote-only`	Fail if remote unreachable (no fallback)

Environment Variables

For CI/CD pipelines and automation:

# Set remote proxy via environment
export CCS_PROXY_HOST="cliproxy-server.internal"
export CCS_PROXY_PORT="8317"
export CCS_PROXY_PROTOCOL="http"
export CCS_PROXY_AUTH_TOKEN="your-secret-token"
export CCS_PROXY_FALLBACK_ENABLED="1"

# Run CCS normally - it will use the remote proxy
ccs codex "implement the feature"

Available Variables

Variable	Description
`CCS_PROXY_HOST`	Remote proxy hostname
`CCS_PROXY_PORT`	Proxy port
`CCS_PROXY_PROTOCOL`	Protocol (`http`/`https`)
`CCS_PROXY_AUTH_TOKEN`	Auth token
`CCS_PROXY_FALLBACK_ENABLED`	Enable local fallback (`1`/`0`)

Docker Deployment

Run CLIProxyAPI in a Docker container:

# Dockerfile for CLIProxyAPI
FROM debian:bookworm-slim

# Download and install CLIProxyAPI
RUN apt-get update && apt-get install -y curl unzip \
    && curl -L -o cliproxy.zip https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/linux-amd64.zip \
    && unzip cliproxy.zip -d /opt/cliproxy \
    && chmod +x /opt/cliproxy/cli-proxy-api

EXPOSE 8317

CMD ["/opt/cliproxy/cli-proxy-api", "--port", "8317"]

# Build and run
docker build -t cliproxy .
docker run -d -p 8317:8317 --name cliproxy cliproxy

# Configure CCS to use it
export CCS_PROXY_HOST="localhost"
export CCS_PROXY_PORT="8317"
ccs codex "hello"

Kubernetes Deployment

Deploy CLIProxyAPI as a Kubernetes service:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: cliproxy
spec:
  replicas: 1
  selector:
    matchLabels:
      app: cliproxy
  template:
    metadata:
      labels:
        app: cliproxy
    spec:
      containers:
      - name: cliproxy
        image: your-registry/cliproxy:latest
        ports:
        - containerPort: 8317
---
apiVersion: v1
kind: Service
metadata:
  name: cliproxy
spec:
  selector:
    app: cliproxy
  ports:
  - port: 8317
    targetPort: 8317

Access from your local machine:

# Port forward for local access
kubectl port-forward svc/cliproxy 8317:8317

# Or use the cluster DNS
export CCS_PROXY_HOST="cliproxy.default.svc.cluster.local"

Fallback Behavior

When remote proxy is enabled but unreachable:

With fallback enabled (default):
- CCS prompts: “Remote proxy unreachable. Start local proxy? [Y/n]”
- If auto-start enabled, starts local proxy automatically
- Continues with local proxy
With --remote-only flag:
- CCS fails immediately with error message
- No fallback, no prompt
In non-interactive mode (no TTY):
- Falls back to local if fallback.enabled: true
- Fails if fallback disabled or auto-start disabled

Troubleshooting

Connection Refused

Error: Remote proxy unreachable: Connection refusedSolutions:

Verify the remote server is running: curl http://HOST:PORT/health
Check firewall rules allow port 8317
Ensure correct host/port configuration

Authentication Failed

Error: Remote proxy unreachable: Authentication failedSolutions:

Verify auth token matches server configuration
Check token is correctly set (no extra spaces/quotes)
Ensure server requires authentication

Timeout

Error: Remote proxy unreachable: TimeoutSolutions:

Check network connectivity to remote host
Verify no proxy/VPN blocking the connection
Increase timeout in config if needed

Self-Signed Certificate

Warning: When using HTTPS with self-signed certificatesCCS automatically allows self-signed certificates when protocol is https. A warning is displayed in verbose mode.

Security Considerations

When exposing CLIProxyAPI to the network:

Always use authentication tokens in production
Consider HTTPS for encrypted connections
Restrict access via firewall rules
Use private networks when possible

Best practices:

Use --proxy-auth-token for authenticated access
Deploy behind a reverse proxy (nginx, Caddy) for HTTPS
Limit network access to trusted IPs
Rotate auth tokens periodically

Getting Started

Providers

Features

Tutorials

Overview

Configuration Methods

Skip Local OAuth

Dashboard Configuration

Backend Selection

HTTPS Tunnel

Config File

Configuration Options

CLI Flags

Available Flags

Environment Variables

Available Variables

Docker Deployment

Kubernetes Deployment

Fallback Behavior

Troubleshooting

Security Considerations

​Overview

​Configuration Methods

​Skip Local OAuth

​Dashboard Configuration

​Backend Selection

​HTTPS Tunnel

​Config File

​Configuration Options

​CLI Flags

​Available Flags

​Environment Variables

​Available Variables

​Docker Deployment

​Kubernetes Deployment

​Fallback Behavior

​Troubleshooting

​Security Considerations

Overview

Configuration Methods

Skip Local OAuth

Dashboard Configuration

Backend Selection

HTTPS Tunnel

Config File

Configuration Options

CLI Flags

Available Flags

Environment Variables

Available Variables

Docker Deployment

Kubernetes Deployment

Fallback Behavior

Troubleshooting

Security Considerations