​

Configuration Schema Reference

​

Version History

​

Root Schema

version: 6                    # REQUIRED - Schema version
default: <profile-name>       # OPTIONAL - Default profile name

accounts: {...}               # Account-based profiles
profiles: {...}               # API-based profiles
cliproxy: {...}               # OAuth provider configuration
preferences: {...}            # User preferences
websearch: {...}              # WebSearch configuration
global_env: {...}             # Global environment variables
copilot: {...}                # GitHub Copilot integration
cliproxy_server: {...}        # Remote/local proxy configuration

​

CLIProxy Configuration

​

cliproxy.backend

cliproxy:
  backend: plus  # Default: plus

• original: CLIProxyAPI (no Kiro/ghcp support)
• plus: CLIProxyAPIPlus (all providers including Kiro/ghcp)
• Backend-specific binaries stored in ~/.ccs/bin/original/ and ~/.ccs/bin/plus/

• Kiro, ghcp: Require backend: plus
• All other providers work on both backends

• Use original for minimal install if Kiro/ghcp not needed
• Use plus for full provider support (recommended, default)

​

cliproxy.variants.<name>.auth

cliproxy:
  variants:
    my-gemini:
      provider: gemini
      auth:
        api_key: "custom-key-123"
        management_secret: "custom-secret-456"

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

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

​

cliproxy.variants.<name>.port

cliproxy:
  variants:
    gemini-dev:
      provider: gemini
      port: 8318
    gemini-prod:
      provider: gemini
      port: 8319

• 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

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

​

cliproxy.auth.api_key

cliproxy:
  auth:
    api_key: "ccs-internal-managed"  # Default

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

​

cliproxy.auth.management_secret

cliproxy:
  auth:
    management_secret: "ccs"  # Default

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

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

​

cliproxy.kiro_no_incognito

cliproxy:
  kiro_no_incognito: false  # Default: false

• false: Use incognito mode (default, no persistent session)
• true: Use normal browser mode (saves cookies/session)

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

​

cliproxy.logging.enabled

cliproxy:
  logging:
    enabled: false  # Default: false

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

​

cliproxy.logging.request_log

cliproxy:
  logging:
    enabled: true
    request_log: false  # Default: false

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

​

cliproxy.token_refresh.enabled

cliproxy:
  token_refresh:
    enabled: false  # Default: false

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

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

​

cliproxy.token_refresh.interval_minutes

cliproxy:
  token_refresh:
    enabled: true
    interval_minutes: 30  # Default: 30

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

​

cliproxy.token_refresh.preemptive_minutes

cliproxy:
  token_refresh:
    enabled: true
    preemptive_minutes: 45  # Default: 45

• 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

cliproxy:
  token_refresh:
    enabled: true
    max_retries: 3  # Default: 3

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

​

cliproxy.token_refresh.verbose

cliproxy:
  token_refresh:
    enabled: true
    verbose: true  # Default: false

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

​

CLIProxy Server Configuration

​

cliproxy_server.fallback.enabled

cliproxy_server:
  fallback:
    enabled: true  # Default: true

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

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

​

cliproxy_server.fallback.auto_start

cliproxy_server:
  fallback:
    enabled: true
    auto_start: false  # Default: false

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

• Seamless fallback without manual intervention
• Ensure proxy always available

​

cliproxy_server.remote.management_key

cliproxy_server:
  remote:
    enabled: true
    host: "proxy.example.com"
    auth_token: "api-token-123"
    management_key: "mgmt-key-456"  # Optional

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

​

cliproxy_server.remote.timeout

cliproxy_server:
  remote:
    enabled: true
    host: "proxy.example.com"
    timeout: 2000  # Milliseconds (defaults to 2000ms if not specified)

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

​

Quota Management Configuration

​

quota_management.mode

quota_management:
  mode: hybrid  # Default: hybrid

• 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

quota_management:
  auto:
    preflight_check: true  # Default: true

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

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

​

quota_management.auto.exhaustion_threshold

quota_management:
  auto:
    exhaustion_threshold: 5  # Default: 5%

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

​

quota_management.auto.tier_priority

quota_management:
  auto:
    tier_priority: ["paid"]  # Default: ["paid"]

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

• paid - Paid subscription accounts
• free - Free tier accounts
• unknown - Tier detection failed

​

quota_management.auto.cooldown_minutes

quota_management:
  auto:
    cooldown_minutes: 5  # Default: 5

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

​

quota_management.manual.paused_accounts

quota_management:
  manual:
    paused_accounts: []  # Default: []

• 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

quota_management:
  manual:
    forced_default: null  # Default: null

• null: Normal account rotation
• <email>: Always use this account

• Testing specific account
• Temporarily override rotation

​

quota_management.manual.tier_lock

quota_management:
  manual:
    tier_lock: null  # Default: null

• null: Use all tiers
• paid: Only paid accounts
• free: Only free accounts

​

Global Environment Variables

​

global_env.enabled

global_env:
  enabled: true  # Default: true

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

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

​

global_env.env

global_env:
  enabled: true
  env:
    DISABLE_BUG_COMMAND: "1"
    DISABLE_ERROR_REPORTING: "1"
    DISABLE_TELEMETRY: "1"

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

• DISABLE_BUG_COMMAND: "1"
• DISABLE_ERROR_REPORTING: "1"
• DISABLE_TELEMETRY: "1"

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

​

WebSearch Configuration

​

websearch.providers.gemini.model

websearch:
  providers:
    gemini:
      enabled: true
      model: "gemini-2.5-flash"  # Default
      timeout: 55

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

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

​

websearch.providers.gemini.timeout

websearch:
  providers:
    gemini:
      timeout: 55  # Default: 55 seconds

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

​

websearch.providers.opencode

websearch:
  providers:
    opencode:
      enabled: false  # Default: false
      model: "opencode/grok-code"
      timeout: 90

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

• Set enabled: true
• Install: npm install -g opencode

​

websearch.providers.grok

websearch:
  providers:
    grok:
      enabled: false  # Default: false
      timeout: 55

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

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

​

Copilot Configuration

​

copilot.account_type

copilot:
  enabled: false
  account_type: individual  # Default: individual

• individual: Personal subscription
• business: Enterprise/team subscription

• Billing/usage tracking
• Feature access control

​

copilot.rate_limit

copilot:
  rate_limit: null  # Default: null (no limit)

• null: No rate limiting
• Integer: Max requests per minute

• Prevent API abuse
• Control costs for business accounts

​

copilot.wait_on_limit

copilot:
  rate_limit: 60
  wait_on_limit: true  # Default: true

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

​

Configuration Patterns

​

Priority Resolution

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

# All three set the same value
ccs gemini --proxy-host proxy.example.com                # CLI flag
CCS_PROXY_HOST=proxy.example.com ccs gemini              # Env var
# config.yaml: cliproxy_server.remote.host: proxy.example.com

​

Variant Isolation Pattern

cliproxy:
  variants:
    gemini-dev:
      provider: gemini
      port: 8318
      auth:
        api_key: "dev-key"
        management_secret: "dev-secret"

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

ccs gemini-dev   # Port 8318, dev credentials
ccs gemini-prod  # Port 8319, prod credentials

​

Remote Proxy with Fallback Pattern

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

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

​

Dashboard Authentication

​

dashboard_auth.enabled

dashboard_auth:
  enabled: false  # Default: false

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

​

dashboard_auth.username

dashboard_auth:
  username: "admin"

​

dashboard_auth.password_hash

dashboard_auth:
  password_hash: "$2b$10$..."

npx bcrypt-cli hash 'your-password'

​

dashboard_auth.session_timeout_hours

dashboard_auth:
  session_timeout_hours: 24  # Default: 24

​

Dashboard Auth Environment Variables

​

Migration from v5 to v6

• 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

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

​

Validation Rules

• version must be integer 2-6
• Ports must be 1-65535
• Boolean fields reject non-boolean values

• 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

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

​

Related Resources

• CLI Flags Reference
• CLI Commands Reference
• Error Codes
• Migration Guide