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

# Migration Guide (v6 → v7)

> Complete guide for migrating from CCS v5 to v7, including v6 features, v7.1 remote proxy support, v7.2 new providers, and breaking changes

# Migration Guide: v6 → v7

Complete migration guide covering all features introduced in v6 and v7, including customizable auth, variant-specific configuration, remote CLIProxy support, new OAuth providers, and token refresh improvements.

***

## Version Overview

| Version | Release | Key Features                                                    |
| ------- | ------- | --------------------------------------------------------------- |
| v7.2    | 2026-01 | Kiro OAuth support, GHCP Device Code flow                       |
| v7.1    | 2025-12 | Remote CLIProxy support, proactive token refresh                |
| v6      | 2025-11 | Customizable auth tokens, variant-specific auth, port isolation |
| v5      | 2025-10 | Remote proxy configuration (deprecated in v7.1)                 |

***

## Breaking Changes Summary

<Warning>Review all breaking changes before upgrading to v7.</Warning>

### v7.2 Breaking Changes

**None** - Fully backward compatible with v7.1

### v7.1 Breaking Changes

**None** - Fully backward compatible with v6

### v6 Breaking Changes

**Config Schema:**

* `config.json` → `config.yaml` (automatic migration)
* New required field: `version: 6`
* `cliproxy.auth` structure changed (automatic migration)

**CLI Flags:**

* `--proxy-server` deprecated → use `--proxy-host`
* `--proxy-auth` deprecated → use `--proxy-auth-token`

***

## Migration Checklist

<Steps>
  <Step title="Backup Configuration">
    ```bash theme={null}
    cp ~/.ccs/config.yaml ~/.ccs/config.yaml.backup
    cp ~/.ccs/cliproxy/accounts.json ~/.ccs/cliproxy/accounts.json.backup
    ```

    CCS creates automatic backups, but a manual backup is recommended.
  </Step>

  <Step title="Update CCS">
    ```bash theme={null}
    npm update -g @kaitranntt/ccs

    # Or force reinstall
    npm install -g @kaitranntt/ccs@latest
    ```
  </Step>

  <Step title="Verify Migration">
    ```bash theme={null}
    ccs --version
    ccs doctor
    ccs doctor --fix
    ```
  </Step>

  <Step title="Test Profiles">
    ```bash theme={null}
    ccs
    ccs codex --auth
    ccs codex
    ```
  </Step>
</Steps>

***

## New Features in v7.2

### 1. Kiro OAuth Support (HIGH PRIORITY)

**What's New:**

* Full OAuth support for Kiro provider (AWS Bedrock Claude)
* Browser-based authentication flow
* Token import from Kiro IDE

**Migration Steps:**

<Tabs>
  <Tab title="Fresh Setup">
    ```bash theme={null}
    # First-time Kiro setup
    ccs kiro --auth
    ```

    Browser opens for AWS SSO login. Authenticate and grant access.
  </Tab>

  <Tab title="Import from IDE">
    ```bash theme={null}
    # Import token from Kiro IDE
    ccs kiro --import
    ```

    Automatically imports credentials from `~/.kiro/` directory.
  </Tab>

  <Tab title="Incognito Mode">
    ```yaml theme={null}
    # config.yaml - Disable incognito for persistent AWS session
    cliproxy:
      kiro_no_incognito: true
    ```

    Or use the CLI flag:

    ```bash theme={null}
    ccs kiro --no-incognito
    ```
  </Tab>
</Tabs>

**Configuration:**

```yaml theme={null}
cliproxy:
  oauth_accounts:
    kai-work: "kai@work.com" # Kiro account
  variants:
    kiro-dev:
      provider: kiro
      account: kai-work
      settings: "~/.ccs/kiro-dev.settings.json"
  kiro_no_incognito: false # Default: false (use incognito)
```

**CLI Flags:**

| Flag              | Purpose                                 |
| ----------------- | --------------------------------------- |
| `--auth`          | Authenticate via browser OAuth          |
| `--import`        | Import token from Kiro IDE              |
| `--no-incognito`  | Use normal browser mode (saves session) |
| `--use <account>` | Switch Kiro account                     |
| `--accounts`      | List all Kiro accounts                  |

**Use Cases:**

* Access AWS Bedrock Claude via Kiro
* Use Claude via AWS SSO with MFA
* Persistent AWS session (no re-auth)

***

### 2. GHCP Device Code Flow (HIGH PRIORITY)

**What's New:**

* GitHub Copilot (GHCP) provider now uses Device Code flow
* No headless browser required
* Better support for SSH/remote environments

**Migration Steps:**

<CodeGroup>
  ```bash Old Flow (v7.1 and earlier) theme={null}
  # Headless browser flow (deprecated)
  ccs ghcp --headless
  # Copy URL, open in local browser
  ```

  ```bash New Flow (v7.2+) theme={null}
  # Device Code flow (automatic)
  ccs ghcp --auth

  # Output:
  # Visit: https://github.com/login/device
  # Enter code: ABCD-1234
  # Waiting for authentication...
  ```
</CodeGroup>

**Configuration:**

```yaml theme={null}
cliproxy:
  oauth_accounts:
    kai-personal: "kai@github.com"
  variants:
    ghcp-work:
      provider: ghcp
      account: kai-personal
```

**CLI Usage:**

```bash theme={null}
# First-time setup
ccs ghcp --auth

# Add another GitHub account
ccs ghcp --auth --add

# Switch accounts
ccs ghcp --use work-account

# List accounts
ccs ghcp --accounts
```

**Benefits:**

* Works in SSH sessions
* No browser automation
* More reliable auth flow
* Better UX for remote development

***

## New Features in v7.1

### 3. Remote CLIProxy Support (HIGH PRIORITY)

**What's New:**

* Connect to remote CLIProxyAPI server
* Share proxy across multiple machines
* Fallback to local proxy if remote unreachable

**Migration Steps:**

<Steps>
  <Step title="Configure Remote Proxy">
    ```yaml theme={null}
    cliproxy_server:
      remote:
        enabled: true
        host: "proxy.example.com"
        port: 8443 # Optional (default: 443 for HTTPS, 80 for HTTP)
        protocol: "https" # http or https
        auth_token: "your-token-123"
        management_key: "mgmt-key-456" # Optional (falls back to auth_token)
        timeout: 5000 # Optional (default: 2000ms)
      fallback:
        enabled: true # Graceful degradation
      local:
        port: 8317
        auto_start: true # Auto-start local if remote fails
    ```
  </Step>

  <Step title="Test Connection">
    ```bash theme={null}
    ccs glm
    ```

    This will try the remote proxy first. Check logs for connection status:

    ```text theme={null}
    [i] Connecting to remote proxy at https://proxy.example.com:8443
    [OK] Remote proxy connected
    ```
  </Step>

  <Step title="Force Remote Only">
    ```bash theme={null}
    ccs codex --remote-only
    ```

    Fails with `PROXY_ERROR` if the remote proxy is unreachable.
  </Step>
</Steps>

**CLI Flags:**

| Flag                             | Purpose                    | Priority |
| -------------------------------- | -------------------------- | -------- |
| `--proxy-host <host>`            | Remote proxy hostname      | HIGH     |
| `--proxy-port <port>`            | Remote proxy port          | HIGH     |
| `--proxy-auth-token <token>`     | Remote auth token          | HIGH     |
| `--proxy-protocol <http\|https>` | Protocol (default: http)   | MEDIUM   |
| `--local-proxy`                  | Force local mode           | MEDIUM   |
| `--remote-only`                  | Fail if remote unreachable | MEDIUM   |
| `--proxy-timeout <ms>`           | Health check timeout       | LOW      |
| `--allow-self-signed`            | Accept self-signed certs   | LOW      |

**Environment Variables:**

```bash theme={null}
export CCS_PROXY_HOST="proxy.example.com"
export CCS_PROXY_PORT="8443"
export CCS_PROXY_AUTH_TOKEN="your-token-123"
export CCS_PROXY_PROTOCOL="https"
export CCS_PROXY_FALLBACK_ENABLED="true"
export CCS_PROXY_TIMEOUT="5000"
export CCS_ALLOW_SELF_SIGNED="false"
```

**Use Cases:**

* Centralized proxy for teams
* Share OAuth credentials across machines
* Reduce per-machine setup
* Better security (credentials on server only)

**Architecture:**

```
┌─────────────┐          ┌──────────────────┐
│ Machine A   │          │                  │
│ ccs codex   │─────────▶│  Remote Proxy    │
└─────────────┘          │  (8443/HTTPS)    │
                         │                  │
┌─────────────┐          │  - OAuth tokens  │
│ Machine B   │─────────▶│  - Shared cache  │
│ ccs codex   │          │  - Session mgmt  │
└─────────────┘          └──────────────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │  Gemini API      │
                         │  Codex API       │
                         │  Antigravity API │
                         └──────────────────┘
```

**Security:**

* Use HTTPS for production
* Separate `management_key` for admin endpoints
* Rotate tokens regularly
* Use firewall rules for access control

***

### 4. Proactive Token Refresh (HIGH PRIORITY)

**What's New:**

* Automatic token refresh 5 minutes before expiration
* Prevents mid-session auth failures
* Supports Gemini, Codex, Antigravity, Qwen, iFlow

**Migration Steps:**

**No action required** - Automatic for all OAuth providers

**How It Works:**

<Steps>
  <Step title="Token Expiry Check">
    Before each API request, CCS checks token expiration.
  </Step>

  <Step title="Proactive Refresh">
    If token expires in \<5 minutes, refresh automatically.
  </Step>

  <Step title="Seamless Session">User experiences no interruption.</Step>
</Steps>

**Configuration:**

```yaml theme={null}
# No configuration needed - enabled by default
cliproxy:
  providers:
    - gemini # Auto-refresh enabled
    - codex # Auto-refresh enabled
    - agy # Auto-refresh enabled
```

**Logging:**

Enable debug logs to see refresh activity:

```bash theme={null}
CCS_DEBUG=1 ccs codex
# Output:
# [i] Token expires in 4m 32s, refreshing...
# [OK] Token refreshed, new expiry: 2025-12-16T15:30:00Z
```

**Benefits:**

* No mid-session auth failures
* Better user experience
* Reduced support tickets

***

## New Features in v6

### 5. Customizable Management Key (HIGH PRIORITY)

**What's New:**

* Separate `management_key` from `api_key`
* Enhanced security for admin endpoints
* Per-variant auth override

**Migration from v5:**

<CodeGroup>
  ```yaml v5 Config (Automatic Migration) theme={null}
  cliproxy:
    auth: "single-key-for-all"
  ```

  ```yaml v6 Config (After Migration) theme={null}
  cliproxy:
    auth:
      api_key: "ccs-internal-managed" # For API requests
      management_secret: "ccs" # For management endpoints
  ```
</CodeGroup>

**Configuration:**

```yaml theme={null}
cliproxy:
  auth:
    api_key: "custom-api-key-123"
    management_secret: "custom-mgmt-secret-456"
  variants:
    my-gemini:
      provider: gemini
      auth:
        api_key: "variant-api-key"
        management_secret: "variant-mgmt-secret"
```

**Use Cases:**

* Separate API vs admin credentials
* Different auth per environment (dev/prod)
* Enhanced security for production

***

### 6. Variant-Specific Auth (HIGH PRIORITY)

**What's New:**

* Per-variant auth override
* Different credentials per variant
* Isolate dev/prod environments

**Migration Steps:**

<Tabs>
  <Tab title="Global Auth">
    ````yaml # Before v6 - Single auth for all variants cliproxy: auth: theme={null}
    "global-key" variants: codex-dev: provider: codex codex-prod: provider:
    codex ```
    </Tab>
    <Tab title="Variant Auth">
    ```yaml # v6+ - Per-variant auth cliproxy: auth: api_key: "global-default"
    management_secret: "global-secret" variants: codex-dev: provider: codex
    auth: api_key: "dev-key" management_secret: "dev-secret" codex-prod:
    provider: codex auth: api_key: "prod-key" management_secret: "prod-secret"
    ````
  </Tab>
</Tabs>

**Use Cases:**

* Separate dev/prod credentials
* Per-team auth keys
* Testing with different API keys
* Security isolation

***

### 7. Port Isolation for Variants (MEDIUM PRIORITY)

**What's New:**

* Assign unique ports to variants (8318-8417)
* Run multiple variants concurrently
* Avoid port conflicts

**Migration Steps:**

```yaml theme={null}
cliproxy:
  variants:
    codex-dev:
      provider: codex
      port: 8318 # NEW: Explicit port assignment
    codex-prod:
      provider: codex
      port: 8319 # Different port = concurrent execution
    custom-qwen:
      provider: qwen
      port: 8320
```

**Port Range:**

* **8317:** Default local proxy (reserved)
* **8318-8417:** Available for variants (100 ports)

**Use Cases:**

* Run dev and prod simultaneously
* Multi-user environments
* Isolated testing

**CLI Usage:**

```bash theme={null}
# Terminal 1
ccs codex-dev    # Port 8318

# Terminal 2 (concurrently)
ccs codex-prod   # Port 8319
```

***

## Configuration Priority Resolution

CCS resolves configuration values in this priority order:

```
1. CLI Flags (highest)
   ↓
2. Environment Variables
   ↓
3. config.yaml
   ↓
4. Defaults (lowest)
```

**Example:**

<CodeGroup>
  ```bash CLI Flag (Wins) theme={null}
  ccs codex --proxy-host proxy.example.com
  ```

  ```bash Environment Variable theme={null}
  CCS_PROXY_HOST=proxy.example.com ccs codex
  ```

  ```yaml Config File theme={null}
  cliproxy_server:
    remote:
      host: "proxy.example.com"
  ```
</CodeGroup>

**Result:** CLI flag overrides env var, env var overrides config file.

***

## Multi-Account OAuth Workflow

**New in v6+**: Multi-account support for all OAuth providers

<Steps>
  <Step title="Add First Account">
    ```bash theme={null}
    ccs codex --auth
    ```

    Browser opens for authentication. The account is saved with the email as the
    default nickname.
  </Step>

  <Step title="Add Second Account">
    ```bash theme={null}
    ccs codex --auth --add
    ```

    Authenticate with a different account.
  </Step>

  <Step title="List Accounts">
    ```bash theme={null}
    ccs codex --accounts
    ```

    Example output:

    ```text theme={null}
    kai@personal.com (default)
    kai@work.com
    ```
  </Step>

  <Step title="Switch Account">
    ```bash theme={null}
    ccs codex --use kai@work.com
    ```
  </Step>

  <Step title="Rename Account">
    ```bash theme={null}
    ccs codex --nickname work-account
    ```

    After renaming, switch with:

    ```bash theme={null}
    ccs codex --use work-account
    ```
  </Step>
</Steps>

**Configuration:**

```yaml theme={null}
cliproxy:
  oauth_accounts:
    personal: "kai@personal.com"
    work: "kai@work.com"
  variants:
    gemini-personal:
      provider: gemini
      account: personal # Use specific account
    gemini-work:
      provider: gemini
      account: work
```

**CLI Flags:**

| Flag                | Purpose                          |
| ------------------- | -------------------------------- |
| `--accounts`        | List all accounts                |
| `--use <account>`   | Switch default account           |
| `--auth`            | Authenticate (current account)   |
| `--auth --add`      | Add new account                  |
| `--nickname <name>` | Rename current account           |
| `--logout`          | Clear tokens for current account |

***

## Troubleshooting Migration Issues

### Issue: Migration Failed

<Tabs>
  <Tab title="Symptom">
    ```
    [X] CONFIG_ERROR: Failed to migrate config
    ```
  </Tab>

  <Tab title="Solution">
    ```bash theme={null}
    # Check migration status
    ccs doctor

    # Manual migration
    ccs migrate

    # Rollback if needed
    ls ~/.ccs/backup-*/
    ccs migrate --rollback ~/.ccs/backup-v1-2025-12-15/
    ```
  </Tab>
</Tabs>

***

### Issue: Remote Proxy Connection Failed

<Tabs>
  <Tab title="Symptom">
    ```
    [X] PROXY_ERROR: Failed to connect to remote proxy
    ```
  </Tab>

  <Tab title="Solution">
    ```bash theme={null}
    # Test connection
    curl -H "x-api-key: your-token" https://proxy.example.com:8443/health

    # Check firewall/network
    telnet proxy.example.com 8443

    # Force local fallback
    ccs codex --local-proxy

    # Debug mode
    CCS_DEBUG=1 ccs codex
    ```
  </Tab>
</Tabs>

***

### Issue: Token Refresh Failed

<Tabs>
  <Tab title="Symptom">
    ```
    [X] AUTH_ERROR: Token refresh failed
    ```
  </Tab>

  <Tab title="Solution">
    ```bash theme={null}
    # Re-authenticate
    ccs codex --logout
    ccs codex --auth

    # Check token expiration
    cat ~/.ccs/cliproxy/accounts.json | jq

    # Enable debug logs
    CCS_DEBUG=1 ccs codex
    ```
  </Tab>
</Tabs>

***

### Issue: Port Conflict

<Tabs>
  <Tab title="Symptom">
    ```
    [X] PROXY_ERROR: Port 8318 already in use
    ```
  </Tab>

  <Tab title="Solution">
    ```bash theme={null}
    # Find process using port
    lsof -i :8318    # macOS/Linux
    netstat -ano | findstr :8318    # Windows

    # Kill process
    kill <PID>

    # Or assign different port
    # config.yaml:
    # cliproxy.variants.my-gemini.port: 8319
    ```
  </Tab>
</Tabs>

***

## Rollback Guide

If migration fails, rollback to previous version:

<Steps>
  <Step title="Stop All CCS Processes">
    ```bash theme={null}
    killall ccs
    killall cli-proxy-api
    ```
  </Step>

  <Step title="Restore Backup">
    ```bash theme={null}
    # List backups
    ls ~/.ccs/backup-*/

    # Restore
    ccs migrate --rollback ~/.ccs/backup-v1-2025-12-15/
    ```
  </Step>

  <Step title="Downgrade CCS">
    ```bash theme={null}
    npm install -g @kaitranntt/ccs@6.5.0
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    ccs --version
    ccs doctor
    ```
  </Step>
</Steps>

***

## Feature Adoption Roadmap

Recommended adoption order for v6/v7 features:

<CardGroup cols={2}>
  <Card title="Week 1: Core Migration" icon="1">
    * Update to v7.2 - Verify automatic migration - Test existing profiles - Run
      `ccs doctor --fix`
  </Card>

  <Card title="Week 2: New Providers" icon="2">
    * Set up Kiro OAuth - Migrate GHCP to Device Code flow - Test multi-account
      workflows
  </Card>

  <Card title="Week 3: Remote Proxy" icon="3">
    * Deploy remote CLIProxy (if team) - Configure fallback - Test connection
      stability
  </Card>

  <Card title="Week 4: Advanced Features" icon="4">
    * Implement port isolation - Configure variant-specific auth - Set up
      monitoring/analytics
  </Card>
</CardGroup>

***

## Environment Variables Reference

New environment variables in v6/v7:

| Variable                     | Version | Purpose                            | Priority |
| ---------------------------- | ------- | ---------------------------------- | -------- |
| `CCS_PROXY_HOST`             | v7.1    | Remote proxy hostname              | HIGH     |
| `CCS_PROXY_PORT`             | v7.1    | Remote proxy port                  | HIGH     |
| `CCS_PROXY_AUTH_TOKEN`       | v7.1    | Remote proxy auth token            | HIGH     |
| `CCS_PROXY_PROTOCOL`         | v7.1    | Remote proxy protocol (http/https) | MEDIUM   |
| `CCS_PROXY_FALLBACK_ENABLED` | v7.1    | Fallback to local proxy            | MEDIUM   |
| `CCS_PROXY_TIMEOUT`          | v7.1    | Remote health check timeout        | LOW      |
| `CCS_ALLOW_SELF_SIGNED`      | v7.1    | Accept self-signed certs           | LOW      |
| `CCS_UNIFIED_CONFIG`         | v6      | Enable unified config mode         | MEDIUM   |
| `CCS_MIGRATE`                | v6      | Trigger auto-migration             | MEDIUM   |
| `CCS_DEBUG`                  | All     | Verbose logging                    | HIGH     |

***

## API Endpoints (New in v7)

Dashboard API endpoints for remote proxy management:

### CLIProxy Control

| Endpoint                     | Method | Purpose               |
| ---------------------------- | ------ | --------------------- |
| `/api/cliproxy/proxy-status` | GET    | Get proxy status      |
| `/api/cliproxy/proxy-start`  | POST   | Start proxy           |
| `/api/cliproxy/proxy-stop`   | POST   | Stop proxy            |
| `/api/cliproxy/update-check` | GET    | Check for updates     |
| `/api/cliproxy/models`       | GET    | List available models |
| `/api/cliproxy/error-logs`   | GET    | Get error logs        |

### Usage Analytics

| Endpoint              | Method | Purpose            |
| --------------------- | ------ | ------------------ |
| `/api/usage/summary`  | GET    | Usage summary      |
| `/api/usage/daily`    | GET    | Daily breakdown    |
| `/api/usage/hourly`   | GET    | Hourly breakdown   |
| `/api/usage/models`   | GET    | Model distribution |
| `/api/usage/insights` | GET    | AI insights        |

**Related:**

* [API Reference](/reference/api-cliproxy)
* [API Reference](/reference/api-usage)

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration Schema" icon="book" href="/reference/config-schema">
    Complete config.yaml v6 reference
  </Card>

  <Card title="File Locations" icon="folder" href="/reference/file-locations">
    Where CCS stores data
  </Card>

  <Card title="CLI Flags" icon="terminal" href="/reference/cli-flags">
    All CLI flags and options
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/reference/troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>

***

## Related Resources

* [Configuration Schema Reference](/reference/config-schema)
* [CLI Commands Reference](/reference/cli-commands)
* [CLI Flags Reference](/reference/cli-flags)
* [File Locations Reference](/reference/file-locations)
* [Error Codes Reference](/reference/error-codes)
* [Troubleshooting Guide](/reference/troubleshooting)