Skip to main content

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

VersionReleaseKey Changes
v132026-04Browser automation policy and OpenAI-compatible local proxy config
v122026-03Official Channels multi-provider support (Telegram, Discord, iMessage)
v112026-03Discord Channels runtime auto-enable preferences
v92026-03Cross-profile continuity inheritance (continuity.inherit_from_account)
v82026-02Thinking/reasoning budget configuration, image analysis config
v72025-12Quota management for hybrid auto+manual account control
v62025-12Customizable auth tokens, variant-specific auth, OAuth model aliases
v52025-10Remote proxy configuration
v42025-08Copilot API integration, now deprecated compatibility
v32025-06WebSearch config with model configuration
v22025-04Initial YAML unified format
v12025-02Legacy JSON format (deprecated)

Root Schema

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
cliproxy:
  backend: original # Default: original
Behavior:
  • original: CLIProxyAPI (works for agy, claude, codex, gemini, iflow, kimi, qwen)
  • 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, and deprecated ghcp compatibility
  • Work on either backend: agy, claude, codex, gemini, iflow, kimi, qwen
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, 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
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
cliproxy:
  variants:
    my-variant:
      provider: gemini
      target: droid # Always route to Droid CLI
Behavior:
  • claude (default): Use Claude Code CLI
  • droid: Use Droid CLI (@factory/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
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
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
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
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
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
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
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
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
logging:
  enabled: true

logging.level

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

logging.rotate_mb

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

logging.retain_days

Type: Integer Priority: LOW Purpose: Keep archived log segments for this many days
logging:
  retain_days: 7

logging.redact

Type: Boolean Priority: HIGH Purpose: Redact sensitive values before persistence
logging:
  redact: true

logging.live_buffer_size

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

cliproxy.token_refresh.enabled

Type: Boolean Priority: MEDIUM Purpose: Enable background token refresh worker
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
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
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
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
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
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):
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:
# 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
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
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
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
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
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
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
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

Browser Automation Configuration

Controls Claude Browser Attach and Codex Browser Tools.
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

Quota Management Configuration

Supported Quota Providers

The following providers support quota tracking and rotation via ccs cliproxy quota and the quota_management section:
Provider IDDescription
agyAntigravity (multi-account)
codexOpenAI Codex
geminiGoogle Gemini
claudeAnthropic Claude OAuth (5-hour + weekly windows, failover)
ghcpGitHub Copilot compatibility (deprecated)

quota_management.mode

Type: String (auto | manual | hybrid) Priority: MEDIUM Purpose: Account selection strategy for OAuth providers
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
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”
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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:
# 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:
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:
ccs codex-dev   # Port 8318, dev credentials
ccs codex-prod  # Port 8319, prod credentials

Remote Proxy with Fallback Pattern

Graceful degradation for network issues:
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
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
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
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
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
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
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
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.

channels.unattended

Type: Boolean Priority: HIGH Purpose: Also add runtime --dangerously-skip-permissions
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
This is runtime-only and high risk. CCS does not persist bypass permissions into Claude settings.

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
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
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
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
image_analysis:
  fallback_backend: gemini

image_analysis.profile_backends

Type: Object Priority: MEDIUM Purpose: Override the resolved image-analysis backend for specific settings profiles
image_analysis:
  profile_backends:
    glm: agy

Dashboard Authentication

Optional username/password protection for the CCS dashboard.
See Dashboard Authentication for full setup guide.

dashboard_auth.enabled

Type: Boolean Priority: HIGH Purpose: Enable dashboard login requirement
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
dashboard_auth:
  username: "admin"

dashboard_auth.password_hash

Type: String (bcrypt hash) Priority: HIGH Purpose: Bcrypt-hashed password
dashboard_auth:
  password_hash: "$2b$10$..."
Generate hash:
npx bcrypt-cli hash 'your-password'
Never store plain-text passwords. Always use bcrypt hash.

dashboard_auth.session_timeout_hours

Type: Integer Priority: LOW Purpose: Session duration before re-login required
dashboard_auth:
  session_timeout_hours: 24 # Default: 24

Dashboard Auth Environment Variables

VariableMaps To
CCS_DASHBOARD_AUTH_ENABLEDdashboard_auth.enabled
CCS_DASHBOARD_USERNAMEdashboard_auth.username
CCS_DASHBOARD_PASSWORD_HASHdashboard_auth.password_hash
CCS_SESSION_SECRETCustom session encryption key
Environment variables override config.yaml values.

Continuity Configuration

Available since v9 (CCS v7.51.0)
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
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:
# 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
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
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

docker:
  compose_file: "~/.ccs/docker/docker-compose.yml"
  host: null # null = local, or "user@host" for remote default
The docker section is auto-generated by ccs docker up or ccs docker config. Manual editing is rarely needed.