Configuration

Home · Getting Started · Configuration · API Reference · Claude Code & Codex · Headroom Plugin

---

Settings are resolved with the following precedence (highest first):

CLI flags → environment variables → config.yaml → built-in defaults

config.yaml

Located at ~/.ghc-tunnel/config.yaml (%APPDATA%\ghc-tunnel\config.yaml on Windows). Generated on first run, with --config, or through the setup wizard.

# Schema version for migration/write-back behavior
config_version: 6

# Server settings
address: 127.0.0.1
port: 8314
debug: false

# Copilot account tier: individual | business | enterprise
account_type: individual

# Header version strings (mimic the VS Code Copilot Chat client)
vscode_version: "1.130.0"
api_version: "2025-05-01"
copilot_version: "0.48.1"

# Self-update behavior (enabled by default)
auto_upgrade: true

# Model name mappings: exact (full match) and prefix (starts-with)
model_mappings:
  exact:
    opus: claude-opus-5
    sonnet: claude-sonnet-5
    haiku: claude-haiku-4.5
  prefix:
    claude-sonnet-4-: claude-sonnet-5

# Content filtering
system_prompt_remove: []
system_prompt_add: []
tool_result_suffix_remove: []

# Retry: max retries for upstream connection errors (0 = none)
max_connection_retries: 3

# Max seconds of silence from an upstream response before it is treated as
# dead. Bounds silence, not total duration, so long streams are fine.
# 0 disables the timeout.
upstream_read_timeout_seconds: 900

# Optional: require this key on all LLM endpoints (Bearer / x-api-key /
# x-goog-api-key). Omit or leave empty to disable authentication.
# api_key: my-secret-key

Model mappings

Incoming model names are rewritten before the request is forwarded upstream:

• exact — matches the full model name.
• prefix — matches when the model name starts with the key. When several prefixes match, the longest (most specific) one wins.

Exact matches take priority over prefix matches. Unmapped names pass through unchanged. Use the live catalog at GET /v1/models to discover valid targets.

The built-in mappings point every Opus spelling at the newest generally available Opus — currently claude-opus-5 — every Sonnet spelling at the newest Sonnet (claude-sonnet-5), and every Haiku spelling at claude-haiku-4.5. Anthropic writes the same version two ways (4.8 and 4-8), so both forms are listed.

These are defaults for a new config file. A file you already have is never rewritten to follow them: see Schema upgrades.

Account type

Controls the upstream base URL only:

account_type	Upstream base URL
individual	https://api.githubcopilot.com
business	https://api.business.githubcopilot.com
enterprise	https://api.enterprise.githubcopilot.com

Set this to match the Copilot seat your token actually has.

Schema upgrades

config_version records the schema an existing config.yaml was written against. When a newer release introduces configuration properties, it bumps this number; on the next start the proxy fills the missing properties with their default values and rewrites config.yaml automatically, preserving every value you have set. No flag is needed for this.

An upgrade only ever adds. A model mapping already in the file keeps pointing where you told it to, even when a newer release changes the built-in default for that alias. There is no way to tell a mapping left at an old default apart from one deliberately pinned to that version, and pinning is common — so nothing existing is rewritten. To adopt the new defaults, run --setup or start it from built-in defaults with --default.

Schema versions so far:

Version	Introduced
2	Opus 4.8 aliases
3	upstream_read_timeout_seconds; auto_upgrade defaulting to true
4	Opus 5 and Sonnet 5 aliases
5	Gemini CLI model mappings (gemini-* prefixes)
6	Removed the retired GitHub Models settings from persisted configuration

--update-config remains for the other, non-schema write-backs (for example restoring the built-in model_mappings when the file has none).

Command-line options

ghc-proxy [options]

  -s, --setup               Launch the interactive setup wizard
      --claudecode          Configure Claude Code to use this proxy (with --setup)
      --codex               Configure Codex to use this proxy (with --setup)
      --gemini              Configure Gemini CLI to use this proxy (with --setup)
  -d, --default             Reset config to defaults during setup
  -p, --port <port>         Port to listen on (default: 8314)
  -a, --address <addr>      Address to listen on (default: 127.0.0.1)
      --debug / --no-debug  Toggle debug mode
      --account-type <t>    individual | business | enterprise
  -c, --config              Generate the default config file and exit
      auth                  Authenticate with GitHub and exit (CI/headless)
      check-usage           Print Copilot quota/usage and exit
      info                  Print diagnostics (version, paths, token) and exit
      --json                Emit machine-readable JSON (with info)
      --show-token          Log GitHub and Copilot tokens on refresh
      --rate-limit <secs>   Minimum seconds between forwarded requests
      --wait                When rate limited, wait instead of returning HTTP 429
      --manual              Require interactive approval before each request
      --fetch-version       Fetch the latest VS Code version at startup
      --no-fetch-version    Disable dynamic VS Code version fetching
      --auto-upgrade        Auto-upgrade app when a newer release is available
                            (default: on)
      --no-auto-upgrade     Disable app auto-upgrade
      --update-config       Persist non-schema config write-backs (schema upgrades apply automatically)
  -v, --version             Show version
  -h, --help                Show help

Environment variables

Every config field has a GHC_PROXY_* override:

Variable	Purpose
GHC_PROXY_ADDRESS	Listen address
GHC_PROXY_PORT	Listen port
GHC_PROXY_DEBUG	Enable debug mode (true/1)
GHC_PROXY_ACCOUNT_TYPE	Account tier
GHC_PROXY_VSCODE_VERSION	Editor-Version string
GHC_PROXY_API_VERSION	X-GitHub-Api-Version string
GHC_PROXY_COPILOT_VERSION	Copilot Chat plugin version string
GHC_PROXY_MAX_CONNECTION_RETRIES	Max connection retries
GHC_PROXY_UPSTREAM_READ_TIMEOUT	Max seconds of upstream silence (0 disables)
GHC_PROXY_REDIRECT_ANTHROPIC	Always translate Anthropic via chat completions
GHC_PROXY_EXTEND_CACHE_TTL	Promote cache_control breakpoints to the 1h tier (true/1)
GHC_PROXY_SHOW_TOKEN	Log tokens on refresh (true/1)
GHC_PROXY_DYNAMIC_VSCODE_VERSION	Fetch latest VS Code version (true/1)
GHC_PROXY_AUTO_UPGRADE	Auto-upgrade app on startup (true/1); set 0 to disable
GHC_PROXY_RATE_LIMIT_SECONDS	Minimum seconds between requests
GHC_PROXY_RATE_LIMIT_WAIT	Wait instead of rejecting when limited (true/1)
GHC_PROXY_MANUAL_APPROVE	Require manual approval per request (true/1)
GHC_PROXY_API_KEY	Require this key on LLM endpoints (empty = disabled)

Token-related variables (COPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN) are covered in Getting Started.

Rate limiting & manual approval

To stay comfortably under GitHub Copilot abuse thresholds:

• --rate-limit 5 enforces a minimum 5-second gap between forwarded requests. Combine with --wait to delay instead of returning HTTP 429.
• --manual pauses before each upstream call until you approve it on the console — useful when dialing in a new client.

Endpoint authentication

By default the proxy accepts all requests. Set api_key in config.yaml (or the GHC_PROXY_API_KEY environment variable) to require a key on the LLM endpoints. The key is accepted from Authorization: Bearer <key>, x-api-key, or x-goog-api-key, and compared in constant time. The dashboard, metrics, and static pages remain open so local monitoring keeps working without a key.

Mimicking the Copilot client

The proxy sends the same identity headers as the real VS Code Copilot Chat client. These version strings occasionally need refreshing when GitHub rejects stale clients:

Config value	Where to read it
copilot_version	latest GitHub.copilot-chat version on the VS Code Marketplace
vscode_version	latest VS Code stable release
api_version	X-GitHub-Api-Version in the Copilot Chat client source

Enable dynamic_vscode_version (or --fetch-version) to refresh the VS Code version automatically at startup.

Self-update

auto_upgrade is enabled by default, including for config files written before the setting existed. On startup the proxy checks GitHub releases and, if a newer version is published, downloads and replaces its own binary. The replacement takes effect on the next start — the running process keeps serving the old code until it restarts.

Disable it with any of:

auto_upgrade: false

ghc-proxy --no-auto-upgrade
GHC_PROXY_AUTO_UPGRADE=0 ghc-proxy

Turn it off if the binary is managed by a package manager, or if it lives somewhere the process should not rewrite — for example a build output directory that cargo build or cargo clean also writes to.