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

> Deploy CLIProxy to a remote server for team access

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

<Steps>
  <Step title="Install CLIProxyAPI on Server">
    SSH into your server and install CCS:

    ```bash theme={null}
    ssh user@your-server.com
    npm install -g @kaitranntt/ccs@latest
    ```

    Verify installation:

    ```bash theme={null}
    ccs --version
    ```

    **Note:** Server doesn't need Claude Code installed, only CCS CLI.
  </Step>

  <Step title="Configure Server-Side Proxy">
    Create `~/.ccs/config.yaml` on server:

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

    ```bash theme={null}
    # Generate API key
    openssl rand -base64 32

    # Generate management secret
    openssl rand -base64 32
    ```
  </Step>

  <Step title="Authenticate OAuth Providers">
    On the server, authenticate each provider:

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

  <Step title="Start Proxy as Systemd Service">
    Create service file `/etc/systemd/system/ccs-proxy.service`:

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

    ```bash theme={null}
    sudo systemctl daemon-reload
    sudo systemctl enable ccs-proxy
    sudo systemctl start ccs-proxy
    sudo systemctl status ccs-proxy
    ```
  </Step>

  <Step title="Setup Reverse Proxy (Optional but Recommended)">
    Use nginx for HTTPS termination:

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

    ```bash theme={null}
    sudo certbot --nginx -d ccs.your-domain.com
    ```
  </Step>

  <Step title="Configure Client">
    On your local machine, edit `~/.ccs/config.yaml`:

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

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

  <Step title="Test Connection">
    Verify client can reach remote proxy:

    ```bash theme={null}
    ccs codex "Hello from remote proxy"
    ```

    Check logs on server:

    ```bash theme={null}
    sudo journalctl -u ccs-proxy -f
    ```

    Expected output:

    ```
    [i] Request from 203.0.113.45: codex
    [OK] Response sent: 200
    ```
  </Step>

  <Step title="Configure Fallback Behavior">
    Control what happens if remote fails:

    **Fail Fast (No Fallback):**

    ```bash theme={null}
    ccs codex --remote-only "Task"
    ```

    Exits with error if remote unreachable.

    **Force Local (Skip Remote):**

    ```bash theme={null}
    ccs codex --local-proxy "Task"
    ```

    Uses local proxy even if remote configured.

    **Graceful Degradation (Default):**

    ```yaml theme={null}
    cliproxy_server:
      fallback:
        enabled: true
        auto_start: true  # Auto-start local on remote failure
    ```
  </Step>
</Steps>

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

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

1. **CLI flags** (highest priority)
2. **Environment variables**
3. **config.yaml**
4. **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:
  ```bash theme={null}
  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:
  ```yaml theme={null}
  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:

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

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

```yaml theme={null}
cliproxy_server:
  fallback:
    enabled: true
    auto_start: true  # Auto-download binary if missing
```

## Advanced Configuration

### Multi-Region Deployment

<Note>**Planned Feature** - Multi-region auto-selection is not yet implemented. This configuration syntax is reserved for future use.</Note>

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

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

```nginx theme={null}
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;
    }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Multi-Account Setup" icon="users" href="/tutorials/multi-account-setup">
    Manage multiple OAuth accounts on the proxy server
  </Card>

  <Card title="Token Management" icon="key" href="/tutorials/token-management">
    Understand token refresh and session persistence
  </Card>
</CardGroup>