​

Configuration Schema Reference

​

Version History

​

Root Schema

version: 9                    # 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
quota_management: {...}       # Quota management (v7+)
thinking: {...}               # Thinking/reasoning budget (v8+)
dashboard_auth: {...}         # Dashboard authentication
image_analysis: {...}         # Image analysis configuration (v8+)
continuity: {...}             # Cross-profile continuity inheritance (v9+)

​

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

cliproxy:
  variants:
    my-variant:
      provider: gemini
      target: droid    # Always route to Droid CLI

• claude (default): Use Claude Code CLI
• droid: Use Droid CLI (@factory/cli)
• Overridden by --target CLI flag

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

​

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.oauth-model-alias

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

• 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

• 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

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

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

# Auto-regenerate on upgrade
ccs doctor --fix

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

​

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

​

Supported Quota Providers

​

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: ["ultra", "pro", "free"]  # Default: ["ultra", "pro", "free"]

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

• ultra - Ultra subscription accounts
• pro - Pro subscription accounts
• free - Free tier accounts

​

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
• enterprise: Enterprise subscription

• Billing/usage tracking
• Feature access control

​

copilot.rate_limit

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

• null: No rate limiting
• Integer: Seconds between requests

• 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

​

Thinking Configuration

​

thinking.mode

thinking:
  mode: auto  # Default: auto

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

​

thinking.override

thinking:
  mode: manual
  override: "high"  # Or numeric budget value

• 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

thinking:
  tier_defaults:
    opus: "high"      # Default
    sonnet: "medium"  # Default
    haiku: "low"      # Default

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

​

thinking.provider_overrides

thinking:
  provider_overrides:
    gemini:
      opus: "high"
      sonnet: "medium"

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

​

thinking.show_warnings

thinking:
  show_warnings: true  # Default: true

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

​

Image Analysis Configuration

​

image_analysis.enabled

image_analysis:
  enabled: true  # Default: true

• true: Route images through CLIProxy vision models
• false: Disable image analysis

​

image_analysis.timeout

image_analysis:
  timeout: 60  # Default: 60

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

​

image_analysis.provider_models

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"

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

​

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

​

Continuity Configuration

​

continuity.inherit_from_account

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

• 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
• Only applies when target='claude' — has no effect on target: droid profiles
• Never applies to account profiles themselves

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

• Account profiles (type: account)
• Copilot profiles

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

​

Migration from v8 to v9

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

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

​

Migration from v7 to v8

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

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

​

Migration from v6 to v7

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

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

​

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 >= 1
• 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