Remote Proxy Deployment

Overview

Remote proxy deployment allows you to:

Centralize OAuth tokens - Team shares one authenticated server
Bypass network restrictions - Route through server with API access
Reduce client setup - No local binary installation needed
Monitor usage centrally - Track all requests through proxy

Architecture

┌─────────────┐          ┌──────────────┐          ┌─────────────┐
│ CCS Client  │  HTTPS   │ Remote Proxy │  OAuth   │ AI Provider │
│ (Laptop A)  ├─────────▶│   Server     ├─────────▶│  (Gemini)   │
└─────────────┘          │              │          └─────────────┘
                         │  Port 443    │
┌─────────────┐          │  or 80       │
│ CCS Client  │  HTTPS   │              │
│ (Laptop B)  ├─────────▶│              │
└─────────────┘          └──────────────┘

Prerequisites

Linux server with public IP or domain
Root/sudo access for port binding (80/443)
CCS CLI installed locally
Basic understanding of systemd (for persistent service)

Install CLIProxyAPI on Server

SSH into your server and install CCS:

ssh user@your-server.com
npm install -g @kaitranntt/ccs@latest

Verify installation:

ccs --version

Note: Server doesn’t need Claude Code installed, only CCS CLI.

Configure Server-Side Proxy

Create ~/.ccs/config.yaml on server:

version: 6

cliproxy:
  auth:
    api_key: "your-secure-api-key-here"
    management_secret: "your-management-secret-here"

  providers:
    - gemini
    - codex
    - agy

cliproxy_server:
  local:
    port: 8317
    auto_start: true

Security: Generate strong random keys:

# Generate API key
openssl rand -base64 32

# Generate management secret
openssl rand -base64 32

Authenticate OAuth Providers

On the server, authenticate each provider:

ccs codex --auth
ccs kimi --auth
ccs kiro --auth

Important: Server needs a browser for OAuth flow. Options:

SSH with X11 forwarding: ssh -X user@server
Use --import flag (Kiro only) to copy token from local machine
Temporarily run on desktop, copy ~/.ccs/cliproxy/*.json to server

Start Proxy as Systemd Service

Create service file /etc/systemd/system/ccs-proxy.service:

[Unit]
Description=CCS CLIProxy Server
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/home/your-user
ExecStart=/usr/bin/node /usr/lib/node_modules/@kaitranntt/ccs/dist/cliproxy-server.js
Restart=on-failure
RestartSec=10
Environment="PORT=8317"
Environment="CCS_PROXY_AUTH_TOKEN=your-secure-api-key-here"

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable ccs-proxy
sudo systemctl start ccs-proxy
sudo systemctl status ccs-proxy

Setup Reverse Proxy (Optional but Recommended)

Use nginx for HTTPS termination:

server {
    listen 443 ssl http2;
    server_name ccs.your-domain.com;

    ssl_certificate /etc/letsencrypt/live/ccs.your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ccs.your-domain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8317;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Obtain SSL certificate:

sudo certbot --nginx -d ccs.your-domain.com

Configure Client

On your local machine, edit ~/.ccs/config.yaml:

version: 6

cliproxy_server:
  remote:
    enabled: true
    host: "ccs.your-domain.com"
    port: 443
    protocol: "https"
    auth_token: "your-secure-api-key-here"
    management_key: "your-management-secret-here"  # Optional
    timeout: 2000  # ms

  fallback:
    enabled: true  # Fallback to local if remote unreachable
    auto_start: false

Alternative: Use CLI flags:

export CCS_PROXY_HOST="ccs.your-domain.com"
export CCS_PROXY_PORT="443"
export CCS_PROXY_AUTH_TOKEN="your-secure-api-key-here"
export CCS_PROXY_PROTOCOL="https"

Test Connection

Verify client can reach remote proxy:

ccs codex "Hello from remote proxy"

Check logs on server:

sudo journalctl -u ccs-proxy -f

Expected output:

[i] Request from 203.0.113.45: codex
[OK] Response sent: 200

Configure Fallback Behavior

Control what happens if remote fails:Fail Fast (No Fallback):

ccs codex --remote-only "Task"

Exits with error if remote unreachable.Force Local (Skip Remote):

ccs codex --local-proxy "Task"

Uses local proxy even if remote configured.Graceful Degradation (Default):

cliproxy_server:
  fallback:
    enabled: true
    auto_start: true  # Auto-start local on remote failure

Configuration Reference

Corporate Proxy Support

CCS respects standard system proxy environment variables for binary downloads and network requests:

Variable	Purpose	Example
`http_proxy` / `HTTP_PROXY`	HTTP proxy server	`http://proxy.corp.com:8080`
`https_proxy` / `HTTPS_PROXY`	HTTPS proxy server	`http://proxy.corp.com:8080`
`NO_PROXY`	Comma-separated bypass list	`localhost,127.0.0.1,.internal.com`

Use case: When downloading CLIProxy binary or making outbound requests from behind a corporate firewall.

# Set system proxy before running CCS
export http_proxy=http://proxy.corp.com:8080
export https_proxy=http://proxy.corp.com:8080
export NO_PROXY=localhost,127.0.0.1

ccs cliproxy update  # Will use proxy for binary download

Note: These variables are for outbound network access. For CLIProxy server configuration, use the CCS-specific variables below.

CCS Environment Variables

Variable	Purpose	Example
`CCS_PROXY_HOST`	Remote hostname	`proxy.company.com`
`CCS_PROXY_PORT`	Remote port	`443` (HTTPS) or `80` (HTTP)
`CCS_PROXY_AUTH_TOKEN`	API authentication	`base64-encoded-key`
`CCS_PROXY_PROTOCOL`	Protocol	`https` or `http`
`CCS_PROXY_TIMEOUT`	Health check timeout	`2000` (ms)
`CCS_PROXY_FALLBACK_ENABLED`	Enable fallback	`true` or `false`

CLI Flags

Flag	Description
`--proxy-host <host>`	Override config host
`--proxy-port <port>`	Override config port
`--proxy-auth-token <token>`	Override config token
`--proxy-protocol <http\|https>`	Override protocol
`--proxy-timeout <ms>`	Health check timeout
`--remote-only`	Fail if remote unavailable
`--local-proxy`	Force local, skip remote
`--allow-self-signed`	Accept self-signed certs

Config Priority

CLI flags (highest priority)
Environment variables
config.yaml
Defaults (lowest priority)

Security Best Practices

Authentication

Rotate keys regularly - Update api_key and management_secret quarterly
Use different keys - Separate auth_token and management_key
Limit scope - api_key for queries, management_key for admin operations

Network Security

Use HTTPS - Always in production (self-signed OK for internal networks)

Firewall rules - Restrict proxy port to known IPs:

sudo ufw allow from 203.0.113.0/24 to any port 443

VPN recommended - Route traffic through VPN for extra security

Monitoring

Log all requests - Enable in config:

cliproxy:
  logging:
    enabled: true
    request_log: true

Monitor disk usage - Logs can grow large, rotate with logrotate
Track quotas - Use /api/usage/summary endpoint

Troubleshooting

Connection Refused

Symptom: [X] Proxy error: ECONNREFUSED Causes:

Server not running: sudo systemctl status ccs-proxy
Firewall blocking: sudo ufw status
Wrong port in config

Authentication Failed

Symptom: [X] Auth error: Invalid token Causes:

Token mismatch between client and server
Token expired (server restarted with new config)

Solution: Verify tokens match:

# Server
grep api_key ~/.ccs/config.yaml

# Client
grep auth_token ~/.ccs/config.yaml

SSL Certificate Errors

Symptom: [X] Network error: UNABLE_TO_VERIFY_LEAF_SIGNATURE Solutions:

# Accept self-signed (development only)
ccs codex --allow-self-signed "Task"

# Or set in config:
export CCS_ALLOW_SELF_SIGNED=true

Fallback Not Working

Symptom: Remote fails but local doesn’t start Causes:

fallback.enabled: false in config
fallback.auto_start: false and local binary missing

Solution:

cliproxy_server:
  fallback:
    enabled: true
    auto_start: true  # Auto-download binary if missing

Advanced Configuration

Multi-Region Deployment

Planned Feature - Multi-region auto-selection is not yet implemented. This configuration syntax is reserved for future use.

Deploy proxies in different regions, clients auto-select fastest:

cliproxy_server:
  remote:
    hosts:
      - host: "us-east.proxy.com"
        region: "us-east"
      - host: "eu-west.proxy.com"
        region: "eu-west"
    auto_select: true  # Ping-based selection

Load Balancing

Use nginx upstream for multiple proxy instances:

upstream ccs_proxy {
    least_conn;
    server 127.0.0.1:8317;
    server 127.0.0.1:8318;
    server 127.0.0.1:8319;
}

server {
    location / {
        proxy_pass http://ccs_proxy;
    }
}

Getting Started

Providers

Features

Tutorials

Overview

Architecture

Prerequisites

Configuration Reference

Corporate Proxy Support

CCS Environment Variables

CLI Flags

Config Priority

Security Best Practices

Authentication

Network Security

Monitoring

Troubleshooting

Connection Refused

Authentication Failed

SSL Certificate Errors

Fallback Not Working

Advanced Configuration

Multi-Region Deployment

Load Balancing

Next Steps

Multi-Account Setup

Token Management

​Overview

​Architecture

​Prerequisites

​Configuration Reference

​Corporate Proxy Support

​CCS Environment Variables

​CLI Flags

​Config Priority

​Security Best Practices

​Authentication

​Network Security

​Monitoring

​Troubleshooting

​Connection Refused

​Authentication Failed

​SSL Certificate Errors

​Fallback Not Working

​Advanced Configuration

​Multi-Region Deployment

​Load Balancing

​Next Steps

Multi-Account Setup

Token Management

Overview

Architecture

Prerequisites

Configuration Reference

Corporate Proxy Support

CCS Environment Variables

CLI Flags

Config Priority

Security Best Practices

Authentication

Network Security

Monitoring

Troubleshooting

Connection Refused

Authentication Failed

SSL Certificate Errors

Fallback Not Working

Advanced Configuration

Multi-Region Deployment

Load Balancing

Next Steps