Skip to main content

​
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:
PriorityMethodUse Case
1 (Highest)CLI FlagsOne-time overrides
2Environment VariablesCI/CD automation
3 (Lowest)config.yamlPersistent settings

​
Dashboard Configuration

The easiest way to configure remote proxy is via the web dashboard:
  1. Run ccs config to open the dashboard
  2. Navigate to Settings → Proxy tab
  3. Select Remote mode
  4. 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
  5. Click Test Connection to verify connectivity
  6. Configure fallback options as needed
Remote Proxy Settings

​
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

OptionTypeDefaultDescription
enabledbooleanfalseEnable remote proxy mode
hoststring""Remote server hostname or IP
portnumber8317CLIProxyAPI port
protocolstringhttphttp or https
auth_tokenstring""Bearer token for authentication
OptionTypeDefaultDescription
enabledbooleantrueFall back to local proxy if remote unreachable
auto_startbooleantrueAuto-start local proxy on fallback
OptionTypeDefaultDescription
portnumber8317Local CLIProxyAPI port
auto_startbooleantrueAuto-start local proxy when needed

​
CLI Flags

Override configuration for a single command: 
# Connect to remote proxy
ccs gemini --proxy-host 192.168.1.100 --proxy-port 8317

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

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

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

​
Available Flags

FlagDescription
--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-proxyForce local mode, ignore remote config
--remote-onlyFail 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 gemini "implement the feature"

​
Available Variables

VariableDescription
CCS_PROXY_HOSTRemote proxy hostname
CCS_PROXY_PORTProxy port
CCS_PROXY_PROTOCOLProtocol (http/https)
CCS_PROXY_AUTH_TOKENAuth token
CCS_PROXY_FALLBACK_ENABLEDEnable 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 gemini "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:
  1. 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
  2. With --remote-only flag:
    • CCS fails immediately with error message
    • No fallback, no prompt
  3. In non-interactive mode (no TTY):
    • Falls back to local if fallback.enabled: true
    • Fails if fallback disabled or auto-start disabled

​
Troubleshooting

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
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
Error: Remote proxy unreachable: TimeoutSolutions:
  • Check network connectivity to remote host
  • Verify no proxy/VPN blocking the connection
  • Increase timeout in config if needed
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