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

<Frame>
  <img src="https://mintcdn.com/ccs-7e541244/eI9u5E9n1MjkuQlm/assets/remote-proxy-settings.png?fit=max&auto=format&n=eI9u5E9n1MjkuQlm&q=85&s=d9230b8b866e037e2b5418854ca3dae9" alt="Remote Proxy Settings" width="4034" height="2806" data-path="assets/remote-proxy-settings.png" />
</Frame>

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

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

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="Local Settings">
    | Option       | Type    | Default | Description                        |
    | ------------ | ------- | ------- | ---------------------------------- |
    | `port`       | number  | `8317`  | Local CLIProxyAPI port             |
    | `auto_start` | boolean | `true`  | Auto-start local proxy when needed |
  </Accordion>
</AccordionGroup>

***

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

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## 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
</Warning>

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