## Description
Supersedes #3403 (parked, stacked on the conflicting #3402) as a
standalone change on `main`.
GitHub's token exchange advertises a per-plan chat host in
`endpoints.api`: `api.business.githubcopilot.com` for Business seats and
`api.enterprise.githubcopilot.com` for Enterprise seats, and GitHub's
own clients route with it. Since #2441 Headroom has folded both into the
generic `api.githubcopilot.com`, because the segmented hosts lagged on
newer Claude models at the time.
That fold breaks enterprises on GitHub's [subscription-based network
routing](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-access/manage-network-access):
their firewall allows only the plan host, the generic host is
unreachable, and the failure looks like a random connection error. It
also made the VS Code guide's Enterprise section wrong, which said
Headroom uses the advertised URL.
This PR honours the Business and Enterprise advertised hosts by default
and adds `GITHUB_COPILOT_USE_ADVERTISED_HOST=0` (also
`false`/`no`/`off`) to restore the generic-host fold for seats where the
segmented host still lags. An explicit `GITHUB_COPILOT_API_URL` or
enterprise domain still wins over both. The individual host keeps being
folded (#610 is unchanged).
Refs #2441, #610, #3352 (an Enterprise seat behind a corporate firewall;
the inline-completions 401 there is #4144).
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
- [x] Documentation update
## Changes Made
- `headroom/copilot_auth.py`:
`_subscription_api_url_from_user_info_payload` returns the advertised
host for the two plan hosts unless `GITHUB_COPILOT_USE_ADVERTISED_HOST`
opts out, and logs the chosen host with the opt-out next to it. That
line is emitted where the host is resolved: the `wrap` process for the
subscription lanes, which does not write to `proxy.log`. The dedicated
proxy's `/health` (`config.openai_api_url`) is where the chosen host
shows up. The generic and individual hosts still normalize to
`DEFAULT_API_URL`. `resolve_copilot_api_url`'s docstring no longer
claims the advertised host is ignored on purpose. Every subscription
lane (`wrap vscode`, `wrap copilot --subscription`, OpenCode
`--copilot-subscription`) already pins `resolution.api_url` into the
dedicated proxy as `--openai-api-url` and `GITHUB_COPILOT_API_URL`, so
they pick this up without changes; `is_copilot_api_url`,
`copilot_completions_base_url` and `_github_host` already treat
`*.githubcopilot.com` as a public Copilot host (verified by an
independent review of the diff).
- `headroom/cli/wrap.py`: `wrap copilot` help text describes the
per-plan routing for `--subscription`; the implicit OAuth lane still
uses the generic host (it performs no token exchange), which the text
now says.
- Docs: `docs/content/docs/vscode-copilot.mdx` Enterprise section is now
true and names the opt-out and the firewall case;
`docs/content/docs/corporate-networks.mdx` lists the plan hosts;
`TESTING-copilot-subscription.md` host section split by lane:
`--subscription` / `wrap vscode` / OpenCode honour the plan host, the
implicit OAuth `wrap copilot` lane is explicitly generic-host (it
performs no token exchange at launch, and `resolve_copilot_api_url` is
pinned network-free by an existing test), and its "open an issue for
auto-detection" paragraph removed.
- Tests: Business and Enterprise honoured; individual and generic still
folded; opt-out restores the fold; explicit pin wins; `wrap copilot
--subscription` pins the advertised host; the implicit OAuth lane stays
on the generic host even when user-info advertises the Enterprise host;
OpenCode subscription lane expectation updated. Three existing tests
that asserted the fold were updated to the new contract.
Follow-ups, not in this PR: `headroom doctor --network` still probes
only `api.githubcopilot.com` (it should probe the resolved plan host);
the implicit OAuth `wrap copilot` lane could resolve the plan host
through the token exchange too.
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy`)
- [x] New tests added for new functionality
- [x] Manual testing performed (live Copilot Business seat, 2026-10-13;
see Live verification)
### Test Output
```text
$ pytest tests/test_copilot_auth.py tests/test_cli/test_wrap_copilot.py tests/test_cli/test_wrap_vscode.py \
tests/test_copilot_vscode_completions_routing.py tests/test_provider_copilot_vscode_config.py \
tests/test_cli/test_wrap_opencode.py tests/test_proxy_copilot_auth_hooks.py tests/test_provider_proxy_routes.py \
tests/test_copilot_integration_id_hmac.py tests/test_proxy/test_anthropic_copilot_upstream_auth.py \
tests/test_copilot_native_mode.py tests/test_copilot_subscription_smoke.py tests/test_cli/test_copilot_auth.py \
tests/test_cli/test_wrap_persistent.py
449 passed, 4 deselected
# the 4 deselected tests (test_wrap_persistent.py::*recover*) fail identically on the base commit 976aa714
# with AttributeError: 'TaskManifest' object has no attribute 'runtime_kind'; unrelated to this change
$ uvx ruff@0.16.8 check . && uvx ruff@0.16.8 format --check .
All checks passed! / 1777 files already formatted
$ mypy headroom/copilot_auth.py headroom/cli/wrap.py --ignore-missing-imports
Success: no issues found in 2 source files
```
## Real Behavior Proof
- Environment: macOS, Python 3.12, repo venv, native core loaded.
- Exact command / steps: the suites above, with the new regressions
failing when `_subscription_api_url_from_user_info_payload` is reverted
to the fold.
- Observed result: the token-exchange and user-info producers, `wrap
vscode`, `wrap copilot --subscription` and the OpenCode lane all hand
the dedicated proxy `https://api.enterprise.githubcopilot.com` (or
`.business.`) as both `--openai-api-url` and `GITHUB_COPILOT_API_URL`;
completions still resolve to `copilot-proxy.githubusercontent.com`.
- Live seat: see "Live verification" below. Not tested: an
Enterprise-plan seat (`api.enterprise.`; same code branch as Business),
and the `wrap copilot --subscription` lane (the test seat has the
Copilot CLI policy off).
### Verification needed before release
No Business or Enterprise seat is available to us. Carrier (Enterprise
seats behind a subscription-routed firewall) runs, on this branch, with
`SSL_CERT_FILE` unset and no `GITHUB_COPILOT_API_URL` exported:
```bash
headroom copilot-auth login # device flow; approve in the browser
headroom wrap vscode # leave running; note the port it prints
curl -s http://127.0.0.1:<port>/health | python3 -m json.tool | grep openai_api_url
# expected: "openai_api_url": "https://api.enterprise.githubcopilot.com"
# then send one Copilot Chat turn in VS Code (any model) and one inline completion
headroom wrap copilot --subscription -- --model claude-sonnet-4.6 -s -p "Reply with exactly: OK"
# expected: the banner shows COPILOT_PROVIDER_API_URL=https://api.enterprise.githubcopilot.com and the reply is OK
```
`curl -s http://127.0.0.1:<port>/health` on the dedicated proxy should
report `"openai_api_url": "https://api.enterprise.githubcopilot.com"`
(the "advertised plan host" log line is printed by the wrap process, not
written to `proxy.log`). If a model that the generic host serves is
rejected on the plan host (`400 ... model is not supported`), the #2455
condition still holds for that seat: set
`GITHUB_COPILOT_USE_ADVERTISED_HOST=0`, restart the wrapper, and report
the model and the response body on this PR before it is released.
### Live verification (2026-10-13, Copilot Business seat)
Branch merged with #4154 on current `main`, isolated
`HEADROOM_WORKSPACE_DIR`, `SSL_CERT_FILE` and `GITHUB_COPILOT_API_URL`
unset, `headroom copilot-auth login` device flow.
- `/copilot_internal/user` for the seat: `copilot_plan: business`,
`endpoints.api: https://api.business.githubcopilot.com`. (For about
three hours after the seat was assigned GitHub still advertised
`api.individual.`; the plan host appeared on its own.)
- Resolution: default → `https://api.business.githubcopilot.com`;
`GITHUB_COPILOT_USE_ADVERTISED_HOST=0` →
`https://api.githubcopilot.com`; explicit `GITHUB_COPILOT_API_URL` wins.
`main`'s `copilot_auth.py` resolves the same seat to
`https://api.githubcopilot.com`.
- `headroom wrap vscode`: dedicated proxy started with `--openai-api-url
https://api.business.githubcopilot.com`; `/health` reports it.
- Model sweep through the proxy, one turn per picker model on each
endpoint it lists (plus `gpt-4o-mini`): **36/36 returned 200** on the
plan host (Claude Haiku/Sonnet/Opus 4.x–5.5 on `/v1/messages` and
`/chat/completions`, Gemini 3.7/3.8/4, GPT-5.x/6.x and Grok on
`/responses`, `gpt-5-mini`, `gpt-4o-mini`). No `model_not_supported`, so
the #2441/#2455 lag does not reproduce on Business today.
- Real VS Code (Copilot Chat 0.69): Ask mode on Auto (`gpt-6-luna`),
Claude Sonnet 5.5 chat (`/v1/messages`), and Agent mode with tool calls
(wrote and ran a pytest file) all went to
`api.business.githubcopilot.com`; every Copilot upstream call in the
proxy log used the plan host, none the generic host.
- Found while testing, not caused by this PR and present on `main`:
ghost text / next edits (`copilot-nes-*` on `/chat/completions`) are
sent to CAPI and get `400 model_not_supported` on both the plan host and
the generic host. Fixed separately in #4188.
## Runtime Rollout Safety
- Rollout-managed feature(s): none; env-gated.
- Minimum rollout channel: stable.
- Stable/default behavior changed: yes. Business and Enterprise
subscription sessions now route to their advertised plan host instead of
`api.githubcopilot.com`. Individual seats, explicit pins and GHE domains
are unchanged.
- Kill switch / disable path: `GITHUB_COPILOT_USE_ADVERTISED_HOST=0`
restores the previous fold without a rollback; `GITHUB_COPILOT_API_URL`
pins any host.
- Unsafe override required: no.
- Qualification impact: adds plan-host routing coverage to the Copilot
auth and wrap suites.
- Rollback path: revert the commit.
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Checklist
- [x] My code follows the project's style guidelines
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
8.5 KiB
Testing: GitHub Copilot subscription mode (headroom wrap copilot --subscription)
This feature has live coverage on macOS and Windows. Additional Linux secret-store coverage is still useful (see Status). If you have a GitHub Copilot subscription and 10 minutes, please run one of the flows below and file a report.
⚠️ This reads your Copilot login token and routes your Copilot CLI traffic through a local Headroom proxy. Only run it if you're comfortable with that. The branch is open for inspection.
What it does (and what "subscription" means here)
Normally headroom wrap copilot is BYOK — you bring an Anthropic/OpenAI API
key and pay that vendor. --subscription is different: it lets you use the
Copilot seat you already pay GitHub for, with no separate API key, while
still routing through Headroom so your context gets compressed.
Mechanically: the Copilot CLI's only interposition hook is its provider-override
(the "BYOK transport"), so Headroom uses that knob but supplies your
subscription token and points back at GitHub's own Copilot API. So the CLI
may print "BYOK" and require an explicit --model, but you are not paying a
third party — it's your subscription, just compressed. (Proof it's working: the
proxy forwards to GitHub's Copilot API — https://api.githubcopilot.com by
default — with your token.)
API host & Enterprise / data-residency
Which host a wrapped session talks to depends on the lane:
--subscription,headroom wrap vscode, and OpenCode--copilot-subscriptionresolve the host from GitHub's token exchange. Business and Enterprise seats route to the plan host GitHub advertises (api.business.githubcopilot.com/api.enterprise.githubcopilot.com), which is what GitHub's own clients use and the only host an enterprise firewall on GitHub's subscription-based network routing allows. If that host rejects a model the generic host serves, setGITHUB_COPILOT_USE_ADVERTISED_HOST=0to fold back to the generic host. Individual seats route to the generic host:api.individual.githubcopilot.comdoes not serve newer models on the responses API, and using it regressedheadroom wrap copilotafter 0.22.4 (#610).- The implicit OAuth path (plain
headroom wrap copilotwith a GitHub login and no provider key) performs no token exchange at launch and always uses the generic public hosthttps://api.githubcopilot.com. On a firewall that allows only the plan host, use--subscriptionor pin the host as below.
An explicit GITHUB_COPILOT_API_URL wins over all of the above.
Enterprise / data-residency: if your organization is provisioned on a
dedicated Copilot API host (GitHub Enterprise Cloud with data residency, or an
egress proxy), pin it explicitly — the override flows through both
--subscription and OAuth, and onward through the proxy to the upstream request:
export GITHUB_COPILOT_API_URL=https://api.<your-host>.githubcopilot.com
headroom wrap copilot --subscription -- --model gpt-5.4
The Business and Enterprise plan hosts are detected from GitHub's token-exchange endpoint (see above); only data-residency and egress-proxy hosts still need the pin.
Status
| Platform | Mechanism (compress + forward) | Token auto-discovery from the OS secret store |
|---|---|---|
| macOS (Keychain) | ✅ verified | ✅ verified (copilot-cli) |
Linux (secret-tool/libsecret) |
✅ expected | ❓ needs testing |
| Windows (Headroom device auth) | ✅ verified | ✅ verified |
| Windows (Copilot CLI credential reuse) | ✅ verified after auth | ❌ Copilot CLI 1.0.81 does not expose the legacy Credential Manager schema |
Any OS via GITHUB_COPILOT_TOKEN env var |
✅ verified by tests | n/a (bypasses discovery) |
The two things we want to learn:
- Does it work end to end on your OS?
- Does it find your Copilot token automatically, or do you have to set
GITHUB_COPILOT_TOKEN? If it can't find it, we need the storage schema (see each flow) so we can fix auto-discovery.
Prerequisites (all platforms)
- A GitHub Copilot subscription.
- The GitHub Copilot CLI:
npm install -g @github/copilot - Log in once: run
copilot, complete the device-code login in your browser, then type/exit.
Linux — the flow we most need (tests auto-discovery)
Auto-discovery only works with a host-native install (a container can't read your host secret store). Linux has prebuilt wheels, so:
pipx install --pip-args='--pre' headroom-ai # or: pip install --pre headroom-ai
# (no separate API key needed — that's the point)
headroom wrap copilot --subscription -- --model gpt-4o -p "Reply with exactly: HEADROOM_OK"
- If it prints
HEADROOM_OK→ auto-discovery works on your Linux. 🎉 Report success. - If it errors with "no reusable bearer token" → discovery missed your token. Please grab the schema so we can fix it (redact the secret), then confirm the mechanism works via the env var:
Report the
secret-tool search --all 2>/dev/null | sed -E 's/^secret = .*/secret = <redacted>/' # then retry, supplying the token explicitly: GITHUB_COPILOT_TOKEN='<your-token>' headroom wrap copilot --subscription -- --model gpt-4o -p "Reply with: HEADROOM_OK"attribute.*lines fromsecret-tooland whether the env-var retry worked.
Windows
For a source checkout with Python and Rust installed, build the current tree with the proxy extra and authorize Headroom's dedicated OAuth app:
uv sync --extra proxy --extra dev
uv run --no-sync headroom copilot-auth login
uv run --no-sync python e2e/copilot_live.py --vscode-extension `
--model gpt-5-mini --model gpt-5.5 `
--model gpt-5.6-luna --model gpt-5.6-sol --model gpt-5.6-terra
The live suite uses the official Copilot CLI, exercises subscription wrapping,
sends requests through an isolated VS Code proxy configuration, and optionally
drives the installed VS Code extension through code chat. It snapshots and
restores real VS Code settings byte-for-byte, deliberately occupies the requested
port to verify fallback-port propagation, and checks every selected model in both
the Copilot response and Headroom's traffic accounting. The Docker-native wrap
suite additionally captures an A-to-B-to-A model sequence at its mock upstream,
proving the outbound request bodies change without stale model state. Neither
suite reads or prints token values.
Packaged-install alternatives:
A. Mechanism test (easiest — Docker Desktop or WSL2):
$env:HEADROOM_DOCKER_IMAGE = "ghcr.io/headroomlabs-ai/headroom:<branch-tag>" # ask the maintainer for the tag
# run the Docker-native installer (scripts/install.ps1), then:
$env:GITHUB_COPILOT_TOKEN = "<your-token>"
headroom wrap copilot --subscription -- --model gpt-4o -p "Reply with: HEADROOM_OK"
Report whether it prints HEADROOM_OK.
B. Native auto-discovery schema: after copilot login, check whether the
installed Copilot CLI exposes a reusable Windows credential target:
cmd /c "cmdkey /list"
Report only a Copilot-related Target: line (it shows the target name, not the
secret). Copilot CLI 1.0.81 did not expose such a target in live Windows testing,
so use headroom copilot-auth login when native reuse is unavailable.
A native Windows wheel is still tracked separately; source builds can run the full Windows authentication and routing matrix today.
macOS (already proven — a second data point still helps)
pipx install --pip-args='--pre' headroom-ai
headroom wrap copilot --subscription -- --model gpt-4o -p "Reply with exactly: HEADROOM_OK"
Schema, for reference: Keychain generic password, service copilot-cli
(security find-generic-password -s copilot-cli -w).
What to report
Please open a Copilot subscription test report with:
- OS + version and how you installed (pipx/pip wheel, Docker, source).
- Was plain
copilotlogged in? - Did
wrap copilot --subscriptionprintHEADROOM_OK? Paste any error. - Did it work without setting
GITHUB_COPILOT_TOKEN(auto-discovery), or only with it? - The storage schema if discovery failed (
secret-tool search --all/cmdkey /list), with the secret redacted.