Configuring Headroom for GitHub Copilot CLI Subscription Mode

Headroom acts as a local proxy for the GitHub Copilot CLI in subscription mode by intercepting OpenAI-compatible HTTP calls, exchanging stored OAuth tokens for short-lived Copilot API tokens, and applying compression pipelines before forwarding requests to the backend.

The chopratejas/headroom repository enables transparent optimization of AI API traffic through a local proxy architecture. When configuring Headroom for GitHub Copilot CLI subscription mode, the tool inserts itself between the CLI and GitHub's servers to manage authentication, reduce payload sizes, and support enterprise routing requirements.

How the Subscription Mode Proxy Works

In subscription mode, the Copilot CLI authenticates via a device-code OAuth flow. Headroom's proxy architecture intercepts these calls to inject authentication headers and normalize request URLs before forwarding them to the Copilot backend.

Device-Code Authentication and Token Storage

The authentication flow begins with the headroom copilot-auth login command. This executes the device-code flow against GitHub's OAuth endpoint and persists the resulting reusable token in ~/.headroom/copilot_auth.json. According to the source code in headroom/copilot_auth.py (lines 10-16), this path is determined by the headroom_copilot_auth_path constant, ensuring consistent access across the application.

Token Exchange Mechanism

For each intercepted request, Headroom exchanges the stored OAuth token for a short-lived Copilot API token (prefixed with tid_…). The function resolve_subscription_bearer_token in headroom/copilot_auth.py (lines 883-888) handles this exchange unless you explicitly disable it by setting the environment variable GITHUB_COPILOT_USE_TOKEN_EXCHANGE to false (lines 1024-1028).

Header Injection and URL Normalization

Before forwarding requests, Headroom prepares the HTTP headers and target URL. The apply_copilot_api_auth function in headroom/copilot_auth.py (line 1034) injects the Authorization: Bearer <tid_…> header along with required Copilot-specific defaults including User-Agent and Editor-Version. Simultaneously, resolve_copilot_api_url (lines 389-398) rewrites the target URL to https://api.githubcopilot.com unless an enterprise override is present.

Configuring the Headroom Wrapper

To enable subscription mode, you must authenticate once and then use the --subscription flag when wrapping the Copilot CLI.

First, authenticate to store your OAuth token:

headroom copilot-auth login

This writes the device-code credentials to ~/.headroom/copilot_auth.json as implemented in the core auth module.

Next, launch the Copilot CLI through Headroom's proxy using the workflow documented in README.md (lines 203-210):

headroom wrap copilot --subscription -- --model gpt-4o

The --subscription flag instructs the wrapper to use the subscription auth path rather than the standard Copilot editor extension flow. The double-dash (--) separates Headroom options from Copilot CLI arguments, passing everything after it (such as --model gpt-4o) directly to the underlying CLI. Upon startup, the wrapper outputs the upstream URL it is using, typically COPILOT_PROVIDER_API_URL=https://api.githubcopilot.com.

Advanced Configuration and Enterprise Routing

Headroom supports GitHub Enterprise Copilot deployments through environment variable overrides. If you set GITHUB_COPILOT_ENTERPRISE_DOMAIN or GITHUB_COPILOT_API_URL, the proxy routes calls to your enterprise-specific host (e.g., https://copilot-api.mycorp.com) as defined in headroom/copilot_auth.py (lines 188-196).

Manual Token Resolution

For custom integrations or debugging, you can programmatically resolve Copilot tokens using the internal auth module:

from headroom import copilot_auth

# Resolve a Copilot subscription bearer token

token = copilot_auth.resolve_subscription_bearer_token()
print("Copilot token:", token)

This returns the short-lived tid_… token that headroom/cli/proxy.py would normally inject automatically via headroom/providers/copilot.py.

Docker and Container Usage

To route containerized Copilot CLI traffic through the Headroom proxy running on your host:

export HEADROOM_PROXY_URL=http://127.0.0.1:8787
export GITHUB_COPILOT_API_URL=${HEADROOM_PROXY_URL}
docker run -e GITHUB_COPILOT_API_URL=$GITHUB_COPILOT_API_URL myimage:latest copilot ...

This configuration forces the Copilot client inside the container to hit the local proxy, which performs the same token exchange and compression handling (implemented in headroom/coprocessor.py) as the host-side wrapper.

Summary

• Headroom acts as a transparent proxy for the GitHub Copilot CLI subscription mode, intercepting HTTP calls at headroom/cli/proxy.py and processing them through headroom/providers/copilot.py.
• Authentication relies on resolve_subscription_bearer_token in headroom/copilot_auth.py (lines 883-888) to exchange stored OAuth tokens for short-lived tid_… tokens.
• Use headroom wrap copilot --subscription to enable subscription mode, separating Headroom flags from CLI arguments with a double-dash.
• Enterprise deployments override the default https://api.githubcopilot.com endpoint via GITHUB_COPILOT_ENTERPRISE_DOMAIN or GITHUB_COPILOT_API_URL environment variables (lines 188-196).
• The compression pipeline in headroom/coprocessor.py processes requests before they reach GitHub's backend, reducing token usage and latency.

Frequently Asked Questions

How does Headroom handle authentication when the Copilot CLI is in subscription mode?

Headroom stores a reusable GitHub OAuth token obtained via device-code flow in ~/.headroom/copilot_auth.json. For each API request, it automatically exchanges this token for a short-lived Copilot token (prefixed with tid_…) using the resolve_subscription_bearer_token function in headroom/copilot_auth.py (lines 883-888) unless you disable this behavior by setting GITHUB_COPILOT_USE_TOKEN_EXCHANGE to false.

Can I use Headroom with GitHub Enterprise Copilot?

Yes. Set the GITHUB_COPILOT_ENTERPRISE_DOMAIN or GITHUB_COPILOT_API_URL environment variable to point to your enterprise endpoint (e.g., https://copilot-api.mycorp.com). The resolve_copilot_api_url function in headroom/copilot_auth.py (lines 389-398) detects these variables and routes traffic accordingly, while apply_copilot_api_auth maintains proper header injection.

Where does Headroom store the GitHub OAuth tokens?

Tokens are stored in a private JSON file at ~/.headroom/copilot_auth.json. The path is determined by headroom_copilot_auth_path in headroom/copilot_auth.py (lines 10-16), ensuring consistent access across the authentication flow and proxy operations.

What happens if the token exchange fails during a Copilot CLI request?

If the exchange fails, Headroom cannot obtain the tid_… token required by the Copilot API, and the request will fail with an authentication error. Ensure you have run headroom copilot-auth login recently to refresh the stored OAuth token, and verify that GITHUB_COPILOT_USE_TOKEN_EXCHANGE is not set to false unless you are providing tokens manually through other means.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}