> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote Proxy

> Connect to a remote CLIProxyAPI server instead of localhost

## 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:**

```bash theme={null}
# 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:**

```yaml theme={null}
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:

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
   * **Backend**: Select CLIProxy backend (original/plus)
5. Click **Test Connection** to verify connectivity
6. Configure fallback options as needed

![Remote Proxy Settings](https://mintcdn.com/ccs-7e541244/eI9u5E9n1MjkuQlm/assets/remote-proxy-settings.png?fit=max\&auto=format\&n=eI9u5E9n1MjkuQlm\&q=85\&s=d9230b8b866e037e2b5418854ca3dae9)

> [!NOTE]
>
> 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:**

```yaml theme={null}
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:**

```bash theme={null}
# 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`:

```yaml theme={null}
# 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

> [accordion] 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 |

> [accordion] 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 |

> [accordion] 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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 theme={null}
# 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"]
```

```bash theme={null}
# 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:

```yaml theme={null}
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:

```bash theme={null}
# 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

> [accordion] Connection Refused
>
> **Error:** `Remote proxy unreachable: Connection refused`
>
> **Solutions:**
>
> * Verify the remote server is running: `curl http://HOST:PORT/health`
> * Check firewall rules allow port 8317
> * Ensure correct host/port configuration

> [accordion] Authentication Failed
>
> **Error:** `Remote proxy unreachable: Authentication failed`
>
> **Solutions:**
>
> * Verify auth token matches server configuration
> * Check token is correctly set (no extra spaces/quotes)
> * Ensure server requires authentication

> [accordion] Timeout
>
> **Error:** `Remote proxy unreachable: Timeout`
>
> **Solutions:**
>
> * Check network connectivity to remote host
> * Verify no proxy/VPN blocking the connection
> * Increase timeout in config if needed

> [accordion] Self-Signed Certificate
>
> **Warning:** When using HTTPS with self-signed certificates
>
> CCS automatically allows self-signed certificates when protocol is `https`.
> A warning is displayed in verbose mode.

***

## Security Considerations

> [!WARNING]
>
> 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.