# Configuring Headroom for GitHub Copilot CLI Subscription Mode

> Configure Headroom for GitHub Copilot CLI subscription mode. Learn how Headroom acts as a local proxy, manages tokens, and applies compression for efficient requests.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-20

---

**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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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:

```bash
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`](https://github.com/chopratejas/headroom/blob/main/README.md) (lines 203-210):

```bash
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`](https://github.com/chopratejas/headroom/blob/main/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:

```python
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`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py) would normally inject automatically via [`headroom/providers/copilot.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/copilot.py).

### Docker and Container Usage

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

```bash
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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py) and processing them through [`headroom/providers/copilot.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/copilot.py).
- Authentication relies on `resolve_subscription_bearer_token` in [`headroom/copilot_auth.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.