headroomlabs-ai/headroom · error · SystemExit

Error: Copilot BYOK mode requires a provider API key. `headr

Error message

Error: Copilot BYOK mode requires a provider API key. `headroom wrap copilot` uses Copilot's BYOK mode, which bypasses GitHub's Copilot API and routes requests directly to the model provider through the Headroom proxy. A GitHub Copilot subscription alone is not sufficient. Set one of: export {src}=sk-... export COPILOT_PROVIDER_API_KEY=sk-...

What it means

`headroom wrap copilot` uses Copilot's bring-your-own-key (BYOK) mode: requests bypass GitHub's Copilot API and route directly to the model provider (Anthropic/OpenAI) through the Headroom proxy. This error fires when neither the provider-specific key (named by _copilot_provider_key_source for the effective provider type) nor the generic COPILOT_PROVIDER_API_KEY is set in the environment. A GitHub Copilot subscription alone cannot authenticate BYOK traffic, so Headroom aborts before launching.

Source

Thrown at headroom/cli/wrap.py:5442

            port=port,
            provider_type=effective_provider_type,
            wire_api=wire_api,
            environ=env,
            project=_project_name_from_cwd(),
        )

        if not env.get("COPILOT_PROVIDER_API_KEY"):
            src = _copilot_provider_key_source(effective_provider_type)
            click.echo(
                f"\n  Error: Copilot BYOK mode requires a provider API key.\n"
                f"  `headroom wrap copilot` uses Copilot's BYOK mode, which bypasses GitHub's\n"
                f"  Copilot API and routes requests directly to the model provider through the\n"
                f"  Headroom proxy. A GitHub Copilot subscription alone is not sufficient.\n\n"
                f"  Set one of:\n"
                f"    export {src}=sk-...          # recommended\n"
                f"    export COPILOT_PROVIDER_API_KEY=sk-...  # also works\n"
            )
            raise SystemExit(1)

    if not subscription and not _copilot_model_configured(copilot_args, env):
        # Distinguish between "--model auto" (wrong model for BYOK) and
        # genuinely missing model (no --model flag at all).
        raw_model = _copilot_model_from_args(copilot_args, env)
        if _is_auto_model(raw_model):
            click.echo(
                "  Error: '--model auto' is not supported in Copilot BYOK mode.\n"
                "  BYOK routes to an external provider (Anthropic/OpenAI) which\n"
                "  does not recognise 'auto' as a model name — the request will\n"
                "  fail with a 400 error.\n"
                "  Options:\n"
                "    • Use a concrete model: --model gpt-4o\n"
                "    • Use subscription mode for native auto-routing:\n"
                "      headroom wrap copilot --subscription -- --model auto"
            )
            raise SystemExit(1)
        else:

View on GitHub (pinned to 322425c43b)

Solutions

Export the provider-specific key as printed in the message, e.g. export ANTHROPIC_API_KEY=sk-... (recommended)
Or export the generic fallback: export COPILOT_PROVIDER_API_KEY=sk-...
Or use subscription mode instead of BYOK: headroom wrap copilot --subscription
Verify the key is non-empty in the launching shell: echo -n "${COPILOT_PROVIDER_API_KEY:-}" | wc -c

Example fix

# before
headroom wrap copilot            # subscription only, no provider key
# Error: Copilot BYOK mode requires a provider API key.

# after
export ANTHROPIC_API_KEY=sk-ant-...
headroom wrap copilot -- --model claude-sonnet-4

Defensive patterns

Strategy: validation

Validate before calling

import os

def byok_key_present(provider_type: str) -> bool:
    specific = {
        "anthropic": "ANTHROPIC_API_KEY",
        "openai": "OPENAI_API_KEY",
    }.get(provider_type, "")
    return bool(os.environ.get(specific) or os.environ.get("COPILOT_PROVIDER_API_KEY"))

assert byok_key_present("anthropic"), "Set ANTHROPIC_API_KEY or COPILOT_PROVIDER_API_KEY for BYOK"

Prevention

Export the provider key in the exact shell that runs headroom wrap copilot
Or explicitly choose --subscription when you have no provider key
Source your .env in the launching shell or use an env manager (direnv)

When it happens

Trigger: Running `headroom wrap copilot` without --subscription while COPILOT_PROVIDER_API_KEY and the provider-specific key (e.g. ANTHROPIC_API_KEY / OPENAI_API_KEY, depending on effective_provider_type from --backend/--provider-type/HEADROOM_BACKEND) are all unset or empty in the environment.

Common situations: Users with an active Copilot subscription assuming it suffices; keys defined in a .env file that the shell never sourced; keys set in a different terminal or launcher (IDE) environment; switching provider backends without exporting the matching key.

Related errors

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/cf44acd66af1c993. Report an issue: GitHub.