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

# Configuration Schema Reference

> Complete schema reference for config.yaml v13 including all configuration keys, types, and examples

# Configuration Schema Reference

Complete reference for `config.yaml` version 13. This file is the single source of truth for all CCS configuration.

**Location:** `~/.ccs/config.yaml`
**Format:** YAML
**Current Version:** 13

***

## Version History

| Version | Release | Key Changes                                                              |
| ------- | ------- | ------------------------------------------------------------------------ |
| v13     | 2026-04 | Browser automation policy and OpenAI-compatible local proxy config       |
| v12     | 2026-03 | Official Channels multi-provider support (Telegram, Discord, iMessage)   |
| v11     | 2026-03 | Discord Channels runtime auto-enable preferences                         |
| v9      | 2026-03 | Cross-profile continuity inheritance (`continuity.inherit_from_account`) |
| v8      | 2026-02 | Thinking/reasoning budget configuration, image analysis config           |
| v7      | 2025-12 | Quota management for hybrid auto+manual account control                  |
| v6      | 2025-12 | Customizable auth tokens, variant-specific auth, OAuth model aliases     |
| v5      | 2025-10 | Remote proxy configuration                                               |
| v4      | 2025-08 | Copilot API integration, now deprecated compatibility                    |
| v3      | 2025-06 | WebSearch config with model configuration                                |
| v2      | 2025-04 | Initial YAML unified format                                              |
| v1      | 2025-02 | Legacy JSON format (deprecated)                                          |

***

## Root Schema

```yaml theme={null}
version: 13 # REQUIRED - Schema version
default: <profile-name> # OPTIONAL - Default profile name

accounts: { ... } # Account-based profiles
profiles: { ... } # API-based profiles
cliproxy: { ... } # OAuth provider configuration
proxy: { ... } # OpenAI-compatible local proxy configuration (v13+)
logging: { ... } # CCS-owned structured runtime logging
preferences: { ... } # User preferences
websearch: { ... } # WebSearch configuration
global_env: { ... } # Global environment variables
copilot: { ... } # Deprecated GitHub Copilot compatibility
cliproxy_server: { ... } # Remote/local proxy configuration
quota_management: { ... } # Quota management (v7+)
thinking: { ... } # Thinking/reasoning budget (v8+)
channels: { ... } # Official Channels runtime auto-enable (v12+)
dashboard_auth: { ... } # Dashboard authentication
browser: { ... } # Browser automation settings (v13+)
image_analysis: { ... } # Image analysis configuration (v8+)
continuity: { ... } # Cross-profile continuity inheritance (v9+)
docker: { ... } # Docker deployment configuration (auto-generated)
```

***

## CLIProxy Configuration

### `cliproxy.backend`

**Type:** String (`original` | `plus`)
**Priority:** HIGH
**Purpose:** Select CLIProxy backend variant

```yaml theme={null}
cliproxy:
  backend: original # Default: original
```

**Behavior:**

* `original`: CLIProxyAPI (works for `agy`, `claude`, `codex`, `gemini`, `iflow`, `kimi`)
* `plus`: CCS-maintained CLIProxyAPIPlus community fork for plus-only providers. Legacy deleted-upstream Plus installs migrate safely to `original`
* Backend-specific binaries stored in `~/.ccs/cliproxy/bin/original/` and `~/.ccs/cliproxy/bin/plus/`
* Generated local CLIProxy configs also select the matching CPAMC dashboard:
  upstream CPAMC for `original`, maintained CCS dashboard fork for `plus`

**Provider Requirements:**

* **Require `backend: plus`:** `kiro`, `cursor`, `gitlab`, `codebuddy`, `kilo`, `qoder`, and deprecated `ghcp` compatibility
* **Work on either backend:** `agy`, `claude`, `codex`, `gemini`, `iflow`, `kimi`

**Use Cases:**

* Use `original` for the stable default backend and the standard provider set
* Use `plus` only when you need Kiro, Cursor, GitLab Duo, CodeBuddy, Kilo AI, Qoder, or deprecated GitHub Copilot compatibility

**Related:** `--backend` CLI flag, provider compatibility

***

### `cliproxy.management_panel_repository`

**Type:** String
**Priority:** ADVANCED
**Purpose:** Override the CPAMC dashboard repository written to generated CLIProxy config

```yaml theme={null}
cliproxy:
  backend: plus
  management_panel_repository: https://github.com/kaitranntt/Cli-Proxy-API-Management-Center
```

**Behavior:**

* When omitted, `backend: original` uses `router-for-me/Cli-Proxy-API-Management-Center`
* When omitted, `backend: plus` uses `kaitranntt/Cli-Proxy-API-Management-Center`
* When set, this value is written to `remote-management.panel-github-repository`
* CCS regenerates stale local CLIProxy config when the expected panel repository changes

**Use Cases:**

* Pin Plus users to the CCS-maintained management dashboard fork
* Test or maintain a private CPAMC fork without editing generated CLIProxy files

**Related:** `cliproxy.backend`, CLIProxy control panel

***

### `cliproxy.variants.<name>.target`

**Type:** String (`claude` | `droid`)
**Priority:** HIGH
**Purpose:** Route this variant to an alternative CLI target

```yaml theme={null}
cliproxy:
  variants:
    my-variant:
      provider: gemini
      target: droid # Always route to Droid CLI (claude, droid, or codex)
```

**Behavior:**

* `claude` (default): Use Claude Code CLI
* `droid`: Use Droid CLI (`@factory/cli`)
* `codex`: Use OpenAI Codex CLI
* Overridden by `--target` CLI flag

**Also available on:**

* `profiles.<name>.target` (API profiles)
* `cliproxy.variants.<name>.target` (CLIProxy variant profiles)
* Composite variant configs

**Not supported for:** `cliproxy`, `copilot`, and `account`

***

### `cliproxy.variants.<name>.auth`

**Type:** Object
**Priority:** HIGH
**Purpose:** Per-variant auth override

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

**Behavior:**

* Overrides global `cliproxy.auth` for specific variant
* Useful for different auth credentials per variant
* Both keys optional (falls back to global)

**Use Cases:**

* Separate auth for dev/prod variants
* Per-team auth credentials
* Testing with different API keys

***

### `cliproxy.variants.<name>.port`

**Type:** Integer (1-65535, recommended: 8318-8417)
**Priority:** HIGH
**Purpose:** Port isolation for concurrent variants

```yaml theme={null}
cliproxy:
  variants:
    gemini-dev:
      provider: gemini
      port: 8318
    gemini-prod:
      provider: gemini
      port: 8319
```

**Behavior:**

* Assigns unique port for variant isolation
* Allows multiple variants to run simultaneously
* Accepts any valid port (1-65535), recommended range: 8318-8417 for CCS variants
* Default: Auto-assigned if not specified

**Use Cases:**

* Run dev and prod variants concurrently
* Isolate variants for different teams
* Avoid port conflicts in multi-user environments

***

### `cliproxy.auth.api_key`

**Type:** String
**Priority:** MEDIUM
**Purpose:** Global API key for CLIProxyAPI

```yaml theme={null}
cliproxy:
  auth:
    api_key: "ccs-internal-managed" # Default
```

**Behavior:**

* Used for CLIProxyAPI authentication
* Sent in `x-api-key` header
* Can be overridden per-variant via `variants.<name>.auth.api_key`
* Default: `"ccs-internal-managed"`

**Security:** Store securely, do not commit to version control

***

### `cliproxy.auth.management_secret`

**Type:** String
**Priority:** MEDIUM
**Purpose:** Global management secret for CLIProxyAPI

```yaml theme={null}
cliproxy:
  auth:
    management_secret: "ccs" # Default
```

**Behavior:**

* Used for CLIProxyAPI management endpoints
* Sent in `x-management-secret` header
* Can be overridden per-variant via `variants.<name>.auth.management_secret`
* Default: `"ccs"`

**Use Cases:**

* Separate auth for management vs API operations
* Enhanced security for admin endpoints

***

### `cliproxy.kiro_no_incognito`

**Type:** Boolean
**Priority:** MEDIUM
**Purpose:** Disable incognito mode for Kiro provider

```yaml theme={null}
cliproxy:
  kiro_no_incognito: true # Default: true
```

**Behavior:**

* `true`: Use normal browser mode (default, saves cookies/session)
* `false`: Force incognito mode

**Use Cases:**

* Persistent AWS SSO login for Kiro
* Avoid re-entering credentials on each auth
* Development/testing with saved browser state

**Related:** `--no-incognito` CLI flag

***

### `cliproxy.routing.strategy`

**Type:** String (`round-robin` | `fill-first`)
**Priority:** MEDIUM
**Purpose:** Persist the proxy-wide routing strategy CCS should prefer

```yaml theme={null}
cliproxy:
  routing:
    strategy: round-robin
```

**Behavior:**

* `round-robin`: Spread requests across matching healthy accounts
* `fill-first`: Drain one healthy account before touching backups
* Default stays `round-robin` until you explicitly change it

**Related:** `ccs cliproxy routing`, dashboard `/cliproxy` routing guidance card

***

### `cliproxy.logging.enabled`

**Type:** Boolean
**Priority:** LOW
**Purpose:** Enable CLIProxy logging to disk

```yaml theme={null}
cliproxy:
  logging:
    enabled: false # Default: false
```

**Behavior:**

* `false`: No disk logging (default, prevents bloat)
* `true`: Write logs to `~/.ccs/cliproxy/logs/`

**Warning:** Logging can consume significant disk space. Enable only for debugging.

***

### `cliproxy.logging.request_log`

**Type:** Boolean
**Priority:** LOW
**Purpose:** Enable detailed request logging

```yaml theme={null}
cliproxy:
  logging:
    enabled: true
    request_log: false # Default: false
```

**Behavior:**

* `false`: Log errors/warnings only
* `true`: Log all HTTP requests/responses
* Requires `logging.enabled: true`

**Warning:** Very verbose. Use only for troubleshooting specific issues.

***

## CCS Logging Configuration

Top-level `logging` controls CCS-owned structured runtime logs. This is separate
from `cliproxy.logging`, which controls CLIProxy runtime files.

### `logging.enabled`

**Type:** Boolean
**Priority:** MEDIUM
**Purpose:** Enable CCS-owned structured runtime logging

```yaml theme={null}
logging:
  enabled: true
```

### `logging.level`

**Type:** String (`error` | `warn` | `info` | `debug`)
**Priority:** MEDIUM
**Purpose:** Minimum log level written to disk

```yaml theme={null}
logging:
  level: info
```

### `logging.rotate_mb`

**Type:** Integer
**Priority:** LOW
**Purpose:** Rotate the current log file when it reaches this size in MB

```yaml theme={null}
logging:
  rotate_mb: 10
```

### `logging.retain_days`

**Type:** Integer
**Priority:** LOW
**Purpose:** Keep archived log segments for this many days

```yaml theme={null}
logging:
  retain_days: 7
```

### `logging.redact`

**Type:** Boolean
**Priority:** HIGH
**Purpose:** Redact sensitive values before persistence

```yaml theme={null}
logging:
  redact: true
```

### `logging.live_buffer_size`

**Type:** Integer
**Priority:** LOW
**Purpose:** Keep this many recent entries in memory for dashboard reads

```yaml theme={null}
logging:
  live_buffer_size: 250
```

***

### `cliproxy.token_refresh.enabled`

**Type:** Boolean
**Priority:** MEDIUM
**Purpose:** Enable background token refresh worker

```yaml theme={null}
cliproxy:
  token_refresh:
    enabled: false # Default: false
```

**Behavior:**

* `false`: On-demand refresh only (5 min before expiry)
* `true`: Background worker refreshes tokens at intervals

**Use Cases:**

* Long-running services needing proactive refresh
* Preventing mid-request token expiry
* CI/CD environments with extended sessions

***

### `cliproxy.token_refresh.interval_minutes`

**Type:** Integer (minutes)
**Priority:** LOW
**Purpose:** Background refresh check interval

```yaml theme={null}
cliproxy:
  token_refresh:
    enabled: true
    interval_minutes: 30 # Default: 30
```

**Behavior:**

* Worker checks all tokens every N minutes
* Only refreshes tokens approaching expiry

***

### `cliproxy.token_refresh.preemptive_minutes`

**Type:** Integer (minutes)
**Priority:** LOW
**Purpose:** Refresh tokens expiring within N minutes

```yaml theme={null}
cliproxy:
  token_refresh:
    enabled: true
    preemptive_minutes: 45 # Default: 45
```

**Behavior:**

* Tokens expiring within this window are refreshed
* Higher values = more proactive refresh
* Prevents `UND_ERR_SOCKET` errors from stale tokens

***

### `cliproxy.token_refresh.max_retries`

**Type:** Integer
**Priority:** LOW
**Purpose:** Maximum refresh retry attempts

```yaml theme={null}
cliproxy:
  token_refresh:
    enabled: true
    max_retries: 3 # Default: 3
```

**Behavior:**

* Retries on transient failures
* Logs warning after max retries exceeded
* Does not re-authenticate (requires user action)

***

### `cliproxy.token_refresh.verbose`

**Type:** Boolean
**Priority:** LOW
**Purpose:** Enable debug logging for token refresh

```yaml theme={null}
cliproxy:
  token_refresh:
    enabled: true
    verbose: true # Default: false
```

**Behavior:**

* Logs all refresh attempts to console
* Useful for debugging token issues
* Output: timestamps, providers, success/failure

***

### `cliproxy.oauth-model-alias`

**Type:** Object (map of model aliases)
**Priority:** HIGH
**Purpose:** Map OAuth provider model names to CLIProxy internal aliases

```yaml theme={null}
cliproxy:
  oauth-model-alias:
    claude-opus-4-6: gemini-claude-opus-4-6-thinking
    claude-opus-4-6-thinking: gemini-claude-opus-4-6-thinking
    claude-opus-4-5: gemini-claude-opus-4-5-thinking
    gemini-3-pro: gemini-3-pro
    # ... more aliases
```

**Behavior:**

* **Auto-Generated:** `ccs doctor` automatically generates this section
* **Purpose:** Maps Claude/Gemini model names to Antigravity's internal naming
* **Required for:** New models like Opus 4.6 to prevent 502 errors
* **Config Version:** Bumped to v6 to trigger auto-regeneration on upgrade
* **Preservation:** Existing custom aliases preserved during regeneration

**Why This Matters:**

* New Opus 4.6 model added to Antigravity catalog
* Users with outdated config.yaml got 502 errors when selecting Opus 4.6
* Auto-regeneration ensures all models work with new CLIProxy versions

**Default Aliases (Auto-Generated):**

```yaml theme={null}
claude-api-key: claude-api-key
claude-opus-4-6: gemini-claude-opus-4-6-thinking
claude-opus-4-6-thinking: gemini-claude-opus-4-6-thinking
claude-opus-4-5: gemini-claude-opus-4-5-thinking
claude-opus-4-5-thinking: gemini-claude-opus-4-5-thinking
claude-sonnet-4-5: gemini-claude-sonnet-4-5
claude-sonnet-4-5-thinking: gemini-claude-sonnet-4-5-thinking
gemini-2-0-flash-thinking: gemini-2-0-flash-thinking
gemini-3-pro: gemini-3-pro
gemini-3-pro-preview: gemini-3-pro-preview
```

**Customization:**

* Add new aliases for private models
* Override defaults if using custom CLIProxy setup
* Keep `claude-api-key` unless running custom OAuth backend

**Regeneration:**

```bash theme={null}
# Auto-regenerate on upgrade
ccs doctor --fix

# Manual config reset (preserve aliases)
ccs doctor --fix
```

***

## CLIProxy Server Configuration

### `cliproxy_server.fallback.enabled`

**Type:** Boolean
**Priority:** HIGH
**Purpose:** Enable fallback to local proxy if remote fails

```yaml theme={null}
cliproxy_server:
  fallback:
    enabled: true # Default: true
```

**Behavior:**

* `true`: Try local proxy if remote unreachable
* `false`: Fail with `PROXY_ERROR` if remote fails

**Use Cases:**

* Graceful degradation for network issues
* Offline work capability
* Testing without remote infrastructure

**Related:** `--remote-only` CLI flag

***

### `cliproxy_server.fallback.auto_start`

**Type:** Boolean
**Priority:** MEDIUM
**Purpose:** Auto-start local proxy on fallback

```yaml theme={null}
cliproxy_server:
  fallback:
    enabled: true
    auto_start: false # Default: false
```

**Behavior:**

* `false`: Use existing local proxy only
* `true`: Spawn local proxy if not running

**Use Cases:**

* Seamless fallback without manual intervention
* Ensure proxy always available

***

### `cliproxy_server.remote.management_key`

**Type:** String
**Priority:** MEDIUM
**Purpose:** Separate management key for remote proxy

```yaml theme={null}
cliproxy_server:
  remote:
    enabled: true
    host: "proxy.example.com"
    auth_token: "api-token-123"
    management_key: "mgmt-key-456" # Optional
```

**Behavior:**

* Used for management endpoints on remote proxy
* Falls back to `auth_token` if not specified
* Allows separate credentials for API vs management

**Security:** Use different keys for production environments

***

### `cliproxy_server.remote.timeout`

**Type:** Integer (milliseconds)
**Priority:** LOW
**Purpose:** Health check timeout for remote proxy

```yaml theme={null}
cliproxy_server:
  remote:
    enabled: true
    host: "proxy.example.com"
    timeout: 2000 # Milliseconds (defaults to 2000ms if not specified)
```

**Behavior:**

* Used for initial health check only
* Higher values for slow networks
* Does NOT affect API request timeouts

**Related:** `--proxy-timeout` CLI flag

***

## OpenAI-Compatible Local Proxy Configuration

Controls the local Anthropic-compatible proxy used when a Claude-target API
profile points at an OpenAI-compatible chat-completions endpoint.

### `proxy.port`

**Type:** Integer
**Priority:** MEDIUM
**Purpose:** Preferred shared local proxy port

```yaml theme={null}
proxy:
  port: 45000
```

**Behavior:**

* Used as the preferred starting port for compatible profiles
* Legacy `3456` is treated as unset unless explicitly pinned at launch
* Overridden by `--port` and `proxy.profile_ports.<profile>`

***

### `proxy.profile_ports`

**Type:** Object
**Priority:** HIGH
**Purpose:** Exact per-profile local proxy port pins

```yaml theme={null}
proxy:
  profile_ports:
    hf: 3460
    openrouter: 3461
```

**Behavior:**

* Lets multiple OpenAI-compatible profiles run at the same time
* `ccs proxy status <profile>` and `ccs proxy activate <profile>` report the
  actual running port

***

### `proxy.routing`

**Type:** Object
**Priority:** MEDIUM
**Purpose:** Request-time routing for compatible proxy profiles

```yaml theme={null}
proxy:
  routing:
    default: "deepseek:deepseek-chat"
    background: "ollama:qwen2.5-coder:0.5b"
    think: "deepseek:deepseek-reasoner"
    longContext: "openrouter:google/gemini-2.5-pro"
    longContextThreshold: 60000
    webSearch: "openrouter:perplexity/sonar-pro"
```

**Behavior:**

* Supports `profile:model`, `profile`, and exact model-id selectors
* Applies scenario routes for background, thinking, long-context, and web-search requests
* `longContextThreshold` uses an approximate token estimate

**Related:** [OpenAI-Compatible Provider Routing](/features/proxy/openai-compatible-providers)

***

## Browser Automation Configuration

Controls Claude Browser Attach and Codex Browser Tools.

```yaml theme={null}
browser:
  claude:
    enabled: false
    policy: manual
    user_data_dir: "~/.ccs/browser/chrome-user-data"
    devtools_port: 9222
    eval_mode: readonly
  codex:
    enabled: false
    policy: manual
    eval_mode: readonly
```

### `browser.claude`

**Type:** Object
**Priority:** HIGH
**Purpose:** Configure Claude Browser Attach

**Fields:**

* `enabled`: turn the Claude attach lane on or off
* `policy`: `manual` or `auto`
* `user_data_dir`: Chrome user-data directory for attach mode
* `devtools_port`: expected Chrome remote debugging port
* `eval_mode`: `disabled`, `readonly`, or `readwrite`

### `browser.codex`

**Type:** Object
**Priority:** HIGH
**Purpose:** Configure Codex Browser Tools

**Fields:**

* `enabled`: turn managed Codex browser tooling on or off
* `policy`: `manual` or `auto`
* `eval_mode`: `disabled`, `readonly`, or `readwrite`

**Behavior:**

* New installs default both lanes to disabled/manual
* `manual` hides browser tooling until a launch uses `--browser`
* `--no-browser` suppresses tooling even when policy is `auto`

**Related:** [Browser Automation](/features/workflow/browser-automation)

***

## Quota Management Configuration

### Supported Quota Providers

The following providers support quota tracking and rotation via `ccs cliproxy quota` and the `quota_management` section:

| Provider ID | Description                                                |
| ----------- | ---------------------------------------------------------- |
| `agy`       | Antigravity (multi-account)                                |
| `codex`     | OpenAI Codex                                               |
| `gemini`    | Google Gemini                                              |
| `claude`    | Anthropic Claude OAuth (5-hour + weekly windows, failover) |
| `ghcp`      | GitHub Copilot compatibility (deprecated)                  |

***

### `quota_management.mode`

**Type:** String (`auto` | `manual` | `hybrid`)
**Priority:** MEDIUM
**Purpose:** Account selection strategy for OAuth providers

```yaml theme={null}
quota_management:
  mode: hybrid # Default: hybrid
```

**Behavior:**

* `auto`: CCS selects account based on quota/tier automatically
* `manual`: Only use paused/forced\_default settings
* `hybrid`: Auto-selection respects manual overrides (recommended)

***

### `quota_management.auto.preflight_check`

**Type:** Boolean
**Priority:** HIGH
**Purpose:** Check quota before starting Claude session

```yaml theme={null}
quota_management:
  auto:
    preflight_check: true # Default: true
```

**Behavior:**

* `true`: Check account quota before request, auto-switch if exhausted
* `false`: Skip pre-flight check, rely on 429 error handling

**Use Cases:**

* Prevent delays from exhausted accounts
* Smoother multi-account experience

***

### `quota_management.auto.exhaustion_threshold`

**Type:** Integer (0-100, percentage)
**Priority:** LOW
**Purpose:** Quota % below which account is "exhausted"

```yaml theme={null}
quota_management:
  auto:
    exhaustion_threshold: 5 # Default: 5%
```

**Behavior:**

* Accounts below threshold are skipped in rotation
* Prevents using nearly-exhausted accounts

***

### `quota_management.auto.tier_priority`

**Type:** Array of strings
**Priority:** LOW
**Purpose:** Account tier preference order

```yaml theme={null}
quota_management:
  auto:
    tier_priority: ["ultra", "pro", "free"] # Default: ["ultra", "pro", "free"]
```

**Behavior:**

* Accounts sorted by tier priority, then by quota %
* Tiers not in list get lowest priority

**Available Tiers:**

* `ultra` - Ultra subscription accounts
* `pro` - Pro subscription accounts
* `free` - Free tier accounts

***

### `quota_management.auto.cooldown_minutes`

**Type:** Integer (minutes)
**Priority:** LOW
**Purpose:** Skip exhausted accounts for N minutes

```yaml theme={null}
quota_management:
  auto:
    cooldown_minutes: 5 # Default: 5
```

**Behavior:**

* Exhausted accounts are skipped for cooldown period
* Prevents repeated failed attempts on same account

***

### `quota_management.manual.paused_accounts`

**Type:** Array of strings
**Priority:** HIGH
**Purpose:** Accounts to skip in rotation

```yaml theme={null}
quota_management:
  manual:
    paused_accounts: [] # Default: []
```

**Behavior:**

* Listed accounts are never selected automatically
* Set via `ccs cliproxy pause <provider> <account>`
* Remove via `ccs cliproxy resume <provider> <account>`

***

### `quota_management.manual.forced_default`

**Type:** String | null
**Priority:** HIGH
**Purpose:** Force specific account for all requests

```yaml theme={null}
quota_management:
  manual:
    forced_default: null # Default: null
```

**Behavior:**

* `null`: Normal account rotation
* `<email>`: Always use this account

**Use Cases:**

* Testing specific account
* Temporarily override rotation

***

### `quota_management.manual.tier_lock`

**Type:** String | null
**Priority:** MEDIUM
**Purpose:** Only use accounts of specific tier

```yaml theme={null}
quota_management:
  manual:
    tier_lock: null # Default: null
```

**Behavior:**

* `null`: Use all tiers
* `paid`: Only paid accounts
* `free`: Only free accounts

***

## Global Environment Variables

### `global_env.enabled`

**Type:** Boolean
**Priority:** MEDIUM
**Purpose:** Enable global env var injection

```yaml theme={null}
global_env:
  enabled: true # Default: true
```

**Behavior:**

* `true`: Inject `global_env.env` into all non-Claude profiles
* `false`: Disable feature

**Use Cases:**

* Disable Claude Code telemetry for proxy providers
* Set common env vars across all profiles

***

### `global_env.env`

**Type:** Object (key-value pairs)
**Priority:** MEDIUM
**Purpose:** Environment variables for all non-Claude profiles

```yaml theme={null}
global_env:
  enabled: true
  env:
    DISABLE_BUG_COMMAND: "1"
    DISABLE_ERROR_REPORTING: "1"
    DISABLE_TELEMETRY: "1"
```

**Behavior:**

* Applied to settings-based and CLIProxy profiles
* NOT applied to native Claude or account-based profiles
* Merged with profile-specific env vars

**Default Values:**

* `DISABLE_BUG_COMMAND: "1"`
* `DISABLE_ERROR_REPORTING: "1"`
* `DISABLE_TELEMETRY: "1"`

**Use Cases:**

* Disable Claude Code telemetry globally
* Set API base URLs
* Configure logging levels

***

## WebSearch Configuration

### `websearch.providers.gemini.model`

**Type:** String
**Priority:** LOW
**Purpose:** Gemini model for WebSearch feature

```yaml theme={null}
websearch:
  providers:
    gemini:
      enabled: true
      model: "gemini-2.5-flash" # Default
      timeout: 55
```

**Behavior:**

* Used by WebSearch hook for third-party profiles
* Free tier: 1000 requests/day
* Falls back to OpenCode/Grok if fails

**Available Models:**

* `gemini-2.5-flash` (default, fastest)
* `gemini-2.5-pro` (more accurate)

***

### `websearch.providers.gemini.timeout`

**Type:** Integer (seconds)
**Priority:** LOW
**Purpose:** Gemini CLI timeout for WebSearch

```yaml theme={null}
websearch:
  providers:
    gemini:
      timeout: 55 # Default: 55 seconds
```

**Behavior:**

* Max time for single WebSearch request
* Prevents hanging on slow responses
* Falls back to next provider on timeout

***

### `websearch.providers.opencode`

**Type:** Object
**Priority:** LOW
**Purpose:** OpenCode provider configuration

```yaml theme={null}
websearch:
  providers:
    opencode:
      enabled: false # Default: false
      model: "opencode/grok-code"
      timeout: 90
```

**Behavior:**

* Free provider via Zen platform
* Requires OpenCode CLI installed
* Fallback option after Gemini

**Activation:**

* Set `enabled: true`
* Install: `npm install -g opencode`

***

### `websearch.providers.grok`

**Type:** Object
**Priority:** LOW
**Purpose:** Grok CLI provider configuration

```yaml theme={null}
websearch:
  providers:
    grok:
      enabled: false # Default: false
      timeout: 55
```

**Behavior:**

* Requires `GROK_API_KEY` environment variable
* Paid API, better quality than free providers
* Last fallback option

**Activation:**

* Set `enabled: true`
* Set `GROK_API_KEY` env var
* Install: `npm install -g @vibe-kit/grok-cli`

***

## Copilot Configuration (Deprecated)

Copilot configuration remains available for existing compatibility setups. New
provider setup should prefer Codex or another active provider.

### `copilot.account_type`

**Type:** String (`individual` | `business` | `enterprise`)
**Priority:** LOW
**Purpose:** GitHub Copilot subscription type

```yaml theme={null}
copilot:
  enabled: false
  account_type: individual # Default: individual
```

**Behavior:**

* `individual`: Personal subscription
* `business`: Enterprise/team subscription
* `enterprise`: Enterprise subscription

**Use Cases:**

* Billing/usage tracking
* Feature access control

***

### `copilot.rate_limit`

**Type:** Integer | null
**Priority:** LOW
**Purpose:** Rate limiting for Copilot API

```yaml theme={null}
copilot:
  rate_limit: null # Default: null (no limit)
```

**Behavior:**

* `null`: No rate limiting
* Integer: Seconds between requests

**Use Cases:**

* Prevent API abuse
* Control costs for business accounts

***

### `copilot.wait_on_limit`

**Type:** Boolean
**Priority:** LOW
**Purpose:** Wait vs fail on rate limit

```yaml theme={null}
copilot:
  rate_limit: 60
  wait_on_limit: true # Default: true
```

**Behavior:**

* `true`: Wait until rate limit window resets
* `false`: Fail with error immediately

***

## Configuration Patterns

### Priority Resolution

CCS resolves configuration values in this order:

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

**Example:**

```bash theme={null}
# All three set the same value
ccs codex --proxy-host proxy.example.com                 # CLI flag
CCS_PROXY_HOST=proxy.example.com ccs codex               # Env var
# config.yaml: cliproxy_server.remote.host: proxy.example.com
```

**Result:** CLI flag wins, then env var, then config file

***

### Variant Isolation Pattern

Run multiple variants concurrently without conflicts:

```yaml theme={null}
cliproxy:
  variants:
    codex-dev:
      provider: codex
      port: 8318
      auth:
        api_key: "dev-key"
        management_secret: "dev-secret"

    codex-prod:
      provider: codex
      port: 8319
      auth:
        api_key: "prod-key"
        management_secret: "prod-secret"
```

**Usage:**

```bash theme={null}
ccs codex-dev   # Port 8318, dev credentials
ccs codex-prod  # Port 8319, prod credentials
```

***

### Remote Proxy with Fallback Pattern

Graceful degradation for network issues:

```yaml theme={null}
cliproxy_server:
  remote:
    enabled: true
    host: "proxy.example.com"
    port: 8443
    protocol: "https"
    auth_token: "remote-token"
    timeout: 5000

  fallback:
    enabled: true
    auto_start: true

  local:
    port: 8317
    auto_start: true
```

**Behavior:**

1. Try remote proxy at `https://proxy.example.com:8443`
2. If unreachable after 5s, fall back to local proxy
3. Auto-start local proxy if not running
4. Use local proxy on port 8317

***

## Thinking Configuration

Controls thinking/reasoning budget injection for CLIProxy providers.

### `thinking.mode`

**Type:** String (`auto` | `off` | `manual`)
**Priority:** HIGH
**Purpose:** Thinking mode control

```yaml theme={null}
thinking:
  mode: auto # Default: auto
```

**Behavior:**

* `auto`: Apply tier-based defaults (opus→high, sonnet→medium, haiku→low)
* `off`: Disable thinking entirely
* `manual`: Use explicit override value

***

### `thinking.override`

**Type:** String | Integer
**Priority:** MEDIUM
**Purpose:** Manual override value for thinking budget

```yaml theme={null}
thinking:
  mode: manual
  override: "high" # Or numeric budget value
```

**Behavior:**

* Used when `mode: manual`
* Can be level name (e.g., "high", "medium", "low") or numeric budget
* Applies to all providers unless overridden

***

### `thinking.tier_defaults`

**Type:** Object
**Priority:** LOW
**Purpose:** Tier-to-thinking level mapping

```yaml theme={null}
thinking:
  tier_defaults:
    opus: "high" # Default
    sonnet: "medium" # Default
    haiku: "low" # Default
```

**Behavior:**

* Maps Claude tier names to thinking level names
* Used when `mode: auto`
* Customizable per tier

***

### `thinking.provider_overrides`

**Type:** Object
**Priority:** LOW
**Purpose:** Per-provider tier defaults

```yaml theme={null}
thinking:
  provider_overrides:
    gemini:
      opus: "high"
      sonnet: "medium"
```

**Behavior:**

* Overrides global tier defaults for specific providers
* Useful for provider-specific configurations

***

### `thinking.show_warnings`

**Type:** Boolean
**Priority:** LOW
**Purpose:** Show warnings when values are clamped

```yaml theme={null}
thinking:
  show_warnings: true # Default: true
```

**Behavior:**

* `true`: Show warning when budget values are adjusted
* `false`: Silent clamping

***

## Official Channels Configuration

Controls runtime-only auto-enable for Anthropic's official Claude channels.

### `channels.selected`

**Type:** Array of strings
**Priority:** HIGH
**Purpose:** Select which official channel plugins CCS auto-adds at launch

```yaml theme={null}
channels:
  selected: [] # Default: []
```

**Behavior:**

* Accepted values: `telegram`, `discord`, `imessage`
* `all` is accepted by the CLI helper, but config.yaml stores the explicit array
* CCS adds `--channels` with every selected ready official plugin at runtime
* Applies only to native Claude `default` and `account` sessions
* Ignored for API-key profiles, CLIProxy, Copilot, Cursor proxy, and Droid target flows
* iMessage is macOS-only
* Telegram and Discord use Claude channel env files for bot tokens

<Note>
  Claude bot tokens are not stored in `config.yaml`. CCS writes them to Claude's
  official channel env files: `~/.claude/channels/telegram/.env` as
  `TELEGRAM_BOT_TOKEN` and `~/.claude/channels/discord/.env` as
  `DISCORD_BOT_TOKEN`.
</Note>

***

### `channels.unattended`

**Type:** Boolean
**Priority:** HIGH
**Purpose:** Also add runtime `--dangerously-skip-permissions`

```yaml theme={null}
channels:
  unattended: false # Default: false
```

**Behavior:**

* `true`: Adds `--dangerously-skip-permissions` only when at least one selected official channel is auto-enabled
* `false`: Leaves permission mode unchanged
* Explicit user permission flags override this default

<Warning>
  This is runtime-only and high risk. CCS does not persist bypass permissions
  into Claude settings.
</Warning>

***

## Image Analysis Configuration

Controls MCP-first image/PDF analysis for third-party launches.

### `image_analysis.enabled`

**Type:** Boolean
**Priority:** HIGH
**Purpose:** Enable image analysis via CLIProxy

```yaml theme={null}
image_analysis:
  enabled: true # Default: true
```

**Behavior:**

* `true`: Expose the managed `ImageAnalysis` path when the runtime is healthy
* `false`: Disable image analysis

***

### `image_analysis.timeout`

**Type:** Integer (seconds)
**Priority:** LOW
**Purpose:** Timeout for vision analysis requests

```yaml theme={null}
image_analysis:
  timeout: 60 # Default: 60
```

**Behavior:**

* Max time for single vision analysis request
* Prevents hanging on slow responses

***

### `image_analysis.provider_models`

**Type:** Object
**Priority:** MEDIUM
**Purpose:** Provider-to-model mapping for vision analysis

```yaml theme={null}
image_analysis:
  provider_models:
    agy: "gemini-2.5-flash"
    gemini: "gemini-2.5-flash"
    codex: "gpt-5.1-codex-mini"
    kiro: "kiro-claude-haiku-4-5"
    ghcp: "claude-haiku-4.5"
    claude: "claude-haiku-4-5-20251001"
    kimi: "kimi-k2.5"
```

**Behavior:**

* Maps provider names to vision model IDs
* Customizable per provider
* Defaults provided for all supported providers

***

### `image_analysis.fallback_backend`

**Type:** String
**Priority:** MEDIUM
**Purpose:** Default backend for bridge-backed profiles that need image analysis

```yaml theme={null}
image_analysis:
  fallback_backend: gemini
```

***

### `image_analysis.profile_backends`

**Type:** Object
**Priority:** MEDIUM
**Purpose:** Override the resolved image-analysis backend for specific settings profiles

```yaml theme={null}
image_analysis:
  profile_backends:
    glm: agy
```

***

## Dashboard Authentication

Optional username/password protection for the CCS dashboard.

<Info>
  See [Dashboard Authentication](/features/dashboard/auth) for full setup guide.
</Info>

### `dashboard_auth.enabled`

**Type:** Boolean
**Priority:** HIGH
**Purpose:** Enable dashboard login requirement

```yaml theme={null}
dashboard_auth:
  enabled: false # Default: false
```

**Behavior:**

* `false`: Dashboard accessible without login (default)
* `true`: Requires username/password to access dashboard

***

### `dashboard_auth.username`

**Type:** String
**Priority:** HIGH
**Purpose:** Login username

```yaml theme={null}
dashboard_auth:
  username: "admin"
```

***

### `dashboard_auth.password_hash`

**Type:** String (bcrypt hash)
**Priority:** HIGH
**Purpose:** Bcrypt-hashed password

```yaml theme={null}
dashboard_auth:
  password_hash: "$2b$10$..."
```

**Generate hash:**

```bash theme={null}
npx bcrypt-cli hash 'your-password'
```

<Warning>Never store plain-text passwords. Always use bcrypt hash.</Warning>

***

### `dashboard_auth.session_timeout_hours`

**Type:** Integer
**Priority:** LOW
**Purpose:** Session duration before re-login required

```yaml theme={null}
dashboard_auth:
  session_timeout_hours: 24 # Default: 24
```

***

### Dashboard Auth Environment Variables

| Variable                      | Maps To                        |
| ----------------------------- | ------------------------------ |
| `CCS_DASHBOARD_AUTH_ENABLED`  | `dashboard_auth.enabled`       |
| `CCS_DASHBOARD_USERNAME`      | `dashboard_auth.username`      |
| `CCS_DASHBOARD_PASSWORD_HASH` | `dashboard_auth.password_hash` |
| `CCS_SESSION_SECRET`          | Custom session encryption key  |

<Note>Environment variables override config.yaml values.</Note>

***

## Continuity Configuration

<Note>Available since v9 (CCS v7.51.0)</Note>

Cross-profile continuity inheritance lets API profiles and CLIProxy variant profiles reuse an account profile's workspace context (`CLAUDE_CONFIG_DIR`). This shares conversation history, project files, and session state across profiles, which means the inherited profile is no longer isolated from that source account lane.

### `continuity.inherit_from_account`

**Type:** Object (map of profile names to account names)
**Priority:** MEDIUM
**Purpose:** Inherit workspace continuity from an account profile

```yaml theme={null}
continuity:
  inherit_from_account:
    glm: pro # GLM profile inherits from "pro" account
    albb: work # albb profile inherits from "work" account
    gemini-dev: dev # gemini-dev variant inherits from "dev" account
```

**Behavior:**

* Maps a non-account profile name to an account profile name
* When the mapped profile runs with `target: claude`, it uses the account's `CLAUDE_CONFIG_DIR`
* Conversation history, project state, and sessions are shared with that account profile
* The inherited profile and source account now reuse the same underlying Claude config directory
* Only applies when `target='claude'` — has no effect on `target: droid` profiles
* Never applies to account profiles themselves

**Supported profile types:**

* Settings-based profiles (`profiles.<name>`)
* CLIProxy variant profiles (`cliproxy.variants.<name>`)
* Built-in API presets (glm, albb, etc.)

**Not supported for:**

* Account profiles (type: account)
* Copilot profiles

**Example use case — share session context between Claude and GLM:**

```yaml theme={null}
# config.yaml
continuity:
  inherit_from_account:
    glm: pro # GLM reuses the "pro" account's Claude config dir

# Now running "ccs glm" will:
# 1. Load GLM's API endpoint and key
# 2. Set CLAUDE_CONFIG_DIR to the "pro" account's instance path
# 3. Access same project files/conversations as "ccs pro"
```

**Legacy support:** The root-level `continuity_inherit_from_account` key in `config.json` is still supported for backward compatibility but deprecated. Migrate to `continuity.inherit_from_account` in `config.yaml`.

***

## Migration from v12 to v13

Version 13 adds OpenAI-compatible local proxy settings and browser automation
settings. Migration is automatic.

**Changes:**

* Added `proxy` section for local compatible-provider proxy ports and routing
* Added `browser` section for Claude Browser Attach and Codex Browser Tools
* New installs default browser lanes to disabled/manual

**Required Action:** None. Run `ccs doctor --fix` if you want CCS to rewrite the
current config file with the latest commented template.

***

## Migration from v8 to v9

Version 9 adds cross-profile continuity inheritance. Migration is automatic.

**Changes:**

* Added `continuity` section with `inherit_from_account` mapping
* Config version bumped from 8 to 9

**Action Required:**

* None (automatic migration with empty defaults)
* Optional: Configure `continuity.inherit_from_account` to share workspace context between profiles

***

## Migration from v7 to v8

Version 8 adds thinking/reasoning budget and image analysis configuration. Migration is automatic.

**Changes:**

* Added `thinking` section for reasoning budget control
* Added `image_analysis` section for vision model configuration
* Updated config version from 7 to 8

**Action Required:**

* None (automatic migration with defaults)
* Optional: Customize thinking levels or vision models

***

## Migration from v6 to v7

Version 7 adds quota management for hybrid auto+manual account control. Migration is automatic.

**Changes:**

* Added `quota_management` section
* Added tier-based quota prioritization
* Added manual account controls (pause/force/tier-lock)

**Action Required:**

* None (automatic migration with defaults)
* Optional: Configure quota management preferences

***

## Migration from v5 to v6

Version 6 adds customizable auth tokens. Migration is automatic.

**Changes:**

* Added `cliproxy.auth.api_key` (default: `"ccs-internal-managed"`)
* Added `cliproxy.auth.management_secret` (default: `"ccs"`)
* Added `cliproxy.variants.<name>.auth` for per-variant override
* Added `cliproxy_server.remote.management_key` for separate management auth

**Action Required:**

* None (automatic migration with defaults)
* Optional: Customize auth keys for enhanced security

***

## Validation Rules

CCS validates configuration on load. Common errors:

**Schema Errors:**

* `version` must be integer >= 1
* Ports must be 1-65535
* Boolean fields reject non-boolean values

**Semantic Errors:**

* Variant names must not conflict with built-in providers
* Profile names cannot be reserved words
* Email addresses must be valid format
* Hostnames must be valid DNS/IP

**Recovery:**

* Run `ccs doctor --fix` for auto-repair
* Run `ccs migrate` for version upgrades
* Delete corrupt config and run `ccs setup`

***

## Docker Deployment Configuration

Auto-generated section written by `ccs docker up`. Stores paths and defaults for the Docker deployment stack.

### `docker.compose_file`

**Type:** String (file path)
**Priority:** LOW
**Purpose:** Path to the generated Docker Compose file

```yaml theme={null}
docker:
  compose_file: "~/.ccs/docker/docker-compose.yml"
```

**Behavior:**

* Auto-written by `ccs docker up`
* Points to the bundled compose file in `~/.ccs/docker/`
* Override only if using a custom compose setup

***

### `docker.host`

**Type:** String | null
**Priority:** MEDIUM
**Purpose:** Default SSH target for remote Docker operations

```yaml theme={null}
docker:
  host: "user@myserver.com" # or null for local
```

**Behavior:**

* `null`: All `ccs docker` commands target localhost
* `"user@host"`: All `ccs docker` commands default to remote target
* Overridden by `--host` CLI flag per-command

***

### Full Docker Section Example

```yaml theme={null}
docker:
  compose_file: "~/.ccs/docker/docker-compose.yml"
  host: null # null = local, or "user@host" for remote default
```

<Note>
  The `docker` section is auto-generated by `ccs docker up` or `ccs docker
      config`. Manual editing is rarely needed.
</Note>

***

## Related Resources

* [CLI Flags Reference](/reference/cli-flags)
* [CLI Commands Reference](/reference/cli-commands)
* [Error Codes](/reference/error-codes)
* [Migration Guide](/reference/migration-v6-v7)