copilot-byok-switcher

Cross-platform launcher for GitHub Copilot CLI custom model providers (BYOK), with interactive selection and automatic model defaults.

Created by Michael Gasperini.

It lets you run GitHub Copilot CLI through native Copilot or a configurable OpenAI/Anthropic-compatible provider without permanently changing your shell environment.

Features

Works on Windows, macOS, and Linux with one Node.js CLI.
Supports GitHub Copilot CLI native mode and BYOK providers.
Keeps provider API keys in environment variables, not in generated shell profiles.
Separates Copilot's required catalog model (COPILOT_MODEL) from the provider wire model.
Ranks provider models automatically using recency, tool support, model family, version, and context length.
Passes BYOK variables only to the child Copilot process.
Avoids the stale VS Code Copilot shim when a working npm CLI is also available on PATH.
Supports Copilot offline mode and both completions and responses wire APIs.
Uses a generic provider config, so any OpenAI-compatible or Anthropic-compatible provider can be added.

Requirements

Node.js 22.13 or newer.
GitHub Copilot CLI 1.0.20 or newer installed and available as copilot on PATH.

Use the latest stable Copilot CLI when possible. Version 1.0.64 or newer includes the most important BYOK Responses and WebSocket fixes recorded in the official Copilot CLI changelog.

The launcher automatically prefers a working standalone CLI over the known stale VS Code shim. If your Copilot binary has another name or location, set:

COPILOT_BIN=/path/to/copilot

Installation

Install globally from GitHub:

npm install -g github:TheStreamCode/copilot-byok-switcher

Then verify the CLI is available:

copilot-byok --help

For local development, clone the repository and link the CLI:

git clone https://github.com/TheStreamCode/copilot-byok-switcher.git
cd copilot-byok-switcher
npm link
copilot-byok --help

Quick Start

Run directly from the repository:

node bin/copilot-byok.mjs --help

Link locally for development:

npm link
copilot-byok --help

Run native GitHub Copilot CLI:

copilot-byok --native

Run a BYOK provider:

copilot-byok --provider chutes --no-model-prompt
copilot-byok --provider deepseek --no-model-prompt
copilot-byok --provider zai --no-model-prompt
copilot-byok --provider minimax --no-model-prompt
copilot-byok --provider openrouter --no-model-prompt
copilot-byok --provider moonshot --no-model-prompt
copilot-byok --provider alibaba-token-plan --no-model-prompt
copilot-byok --provider tencent-token-plan --no-model-prompt

Pass a prompt to Copilot CLI:

copilot-byok --provider chutes --no-model-prompt -p "Explain this repository"

Use an explicit provider model:

copilot-byok --provider chutes --model moonshotai/Kimi-K2.6-TEE -p "Reply exactly: OK"

List ranked models:

copilot-byok --provider chutes --list-models
copilot-byok --provider opencode-go --list-models
copilot-byok --provider fireworks --list-models
copilot-byok --provider deepseek --list-models
copilot-byok --provider zai --list-models
copilot-byok --provider minimax --list-models
copilot-byok --provider openrouter --list-models
copilot-byok --provider moonshot --list-models

Built-In Providers

The CLI includes defaults for Chutes, OpenCode Go, Fireworks AI, OpenRouter, Moonshot AI (Kimi), DeepSeek, Z.ai (GLM), MiniMax, Alibaba Model Studio Token Plan, and Tencent Cloud Token Plan.

API keys are read from environment variables. For example:

export CHUTES_API_KEY=...
export OPENCODE_GO_API_KEY=...
export FIREWORKS_API_KEY=...
export DEEPSEEK_API_KEY=...
export ZAI_API_KEY=...
export MINIMAX_API_KEY=...
export OPENROUTER_API_KEY=...
export MOONSHOT_API_KEY=...
export ALIBABA_TOKEN_PLAN_API_KEY=...
export TENCENT_TOKEN_PLAN_API_KEY=...

PowerShell:

$env:CHUTES_API_KEY = "..."
$env:OPENCODE_GO_API_KEY = "..."
$env:FIREWORKS_API_KEY = "..."
$env:DEEPSEEK_API_KEY = "..."
$env:ZAI_API_KEY = "..."
$env:MINIMAX_API_KEY = "..."
$env:OPENROUTER_API_KEY = "..."
$env:MOONSHOT_API_KEY = "..."
$env:ALIBABA_TOKEN_PLAN_API_KEY = "..."
$env:TENCENT_TOKEN_PLAN_API_KEY = "..."

Every preset is based on the provider's official API documentation:

Provider (id / aliases)	Protocol	Official endpoint	Default model	Documentation
Chutes (`chutes`)	OpenAI	`https://llm.chutes.ai/v1`	auto-ranked	Chutes docs
OpenCode Go (`opencode-go`, `go`, `opencode`)	Anthropic	`https://opencode.ai/zen/go`	auto-ranked	OpenCode Go docs
Fireworks AI (`fireworks`, `fire`)	Anthropic	`https://api.fireworks.ai/inference`	auto-ranked	Fireworks Anthropic compatibility
OpenRouter (`openrouter`, `or`)	OpenAI	`https://openrouter.ai/api/v1`	`openrouter/auto`	OpenRouter models API
Moonshot AI (`moonshot`, `kimi`)	OpenAI	`https://api.moonshot.ai/v1`	`kimi-k3`	Kimi models API
DeepSeek (`deepseek`)	OpenAI	`https://api.deepseek.com`	`deepseek-v4-pro`	DeepSeek models API
Z.ai (`zai`, `glm`)	OpenAI	`https://api.z.ai/api/coding/paas/v4`	`glm-5.1`	Z.ai HTTP API
MiniMax (`minimax`)	OpenAI	`https://api.minimax.io/v1`	`MiniMax-M2.7`	MiniMax models API
Alibaba Model Studio Token Plan (`alibaba-token-plan`, `qwen`)	OpenAI	`https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`	`qwen3.7-plus`	Alibaba Token Plan quickstart
Tencent Cloud Token Plan (`tencent-token-plan`, `tokenhub`)	OpenAI	`https://api.lkeap.cloud.tencent.com/plan/v3`	`tc-code-latest`	Tencent Token Plan quickstart

Provider-specific examples:

copilot-byok --provider deepseek --no-model-prompt -p "Explain this repository"
copilot-byok --provider zai --model glm-5.1 -p "Reply exactly: OK"
copilot-byok --provider minimax --model MiniMax-M2.7 -p "Summarize the latest diff"
copilot-byok --provider openrouter --offline --no-model-prompt
copilot-byok --provider kimi --model kimi-k3 -p "Review this diff"
copilot-byok --provider qwen --model qwen3.7-plus -p "Fix the failing tests"
copilot-byok --provider tokenhub --model tc-code-latest -p "Refactor this module"

Z.ai uses the Coding Plan endpoint by default because it is the endpoint documented for coding tools. If you need the general Z.ai API endpoint instead, create a custom provider with baseUrl set to https://api.z.ai/api/paas/v4.

The Alibaba preset is specifically for the Beijing Model Studio Token Plan and requires its dedicated plan key. The Tencent preset targets the mainland China personal Token Plan and requires its dedicated sk-tp-... key. Pay-as-you-go, enterprise, international, and other regions use different endpoints and should be configured as custom providers.

Gemini is intentionally not duplicated as a built-in BYOK preset because current Copilot CLI releases already expose Gemini through the native Copilot model catalog. A direct Google endpoint can still be added as a custom provider when separate Google billing and credentials are required.

Custom Provider Config

By default, the CLI looks for:

Windows: %APPDATA%\copilot-byok-switcher\providers.json
macOS/Linux: ~/.config/copilot-byok-switcher/providers.json

You can also pass a file explicitly:

copilot-byok --config ./providers.json --provider my-provider

Example:

{
  "$schema": "https://raw.githubusercontent.com/TheStreamCode/copilot-byok-switcher/main/schemas/providers.schema.json",
  "providers": [
    {
      "id": "my-provider",
      "name": "My Provider",
      "type": "openai",
      "baseUrl": "https://api.example.com/v1",
      "apiKeyEnv": "MY_PROVIDER_API_KEY",
      "modelsUrl": "https://api.example.com/v1/models",
      "catalogModelId": "gpt-4.1",
      "requireToolSupport": true
    }
  ]
}

Why `catalogModelId` and the wire model are separate

GitHub Copilot CLI BYOK supports these variables:

COPILOT_MODEL
COPILOT_PROVIDER_WIRE_MODEL

catalogModelId sets the required COPILOT_MODEL value. It should be a model known by Copilot's built-in catalog, such as gpt-4.1 or claude-sonnet-4.6; Copilot uses that catalog entry for internal capabilities and defaults.

COPILOT_PROVIDER_WIRE_MODEL is the model name sent to your provider, such as moonshotai/Kimi-K2.6-TEE or accounts/fireworks/models/minimax-m2p5.

This avoids warnings like:

Model "custom-provider-model" is not in the built-in catalog.

It also avoids GPT-5-specific warnings for providers that only support chat completions.

See GitHub's official Copilot CLI BYOK documentation for the underlying environment variables and compatibility requirements.

Copilot CLI features

The switcher exposes current Copilot CLI BYOK capabilities without changing global shell state:

--offline sets COPILOT_OFFLINE=true, preventing Copilot from connecting to GitHub while the selected provider remains reachable.
--wire-api completions|responses overrides COPILOT_PROVIDER_WIRE_API for providers that implement the selected OpenAI wire API.
maxOutputTokens is forwarded to Copilot and is honored by recent Responses-provider releases.
Provider configuration also works when Copilot is used through ACP; that behavior is implemented by Copilot CLI itself.

Use responses only when the selected provider and model officially support it. Otherwise keep the default completions API.

Model Ranking

When no --model is provided, the CLI fetches the provider model catalog and ranks models with these rules:

Exclude non-chat/non-agent model names such as image, embedding, rerank, OCR, guard, TTS, Whisper, audio, and diffusion models.
Require text input when the provider exposes modality metadata.
Require tool support when the provider exposes tool metadata and requireToolSupport is enabled.
Require serverless/ready/OK state when the provider exposes those fields.
Prefer newer updateTime, then newer createTime or created.
Prefer coding/agent model families as a tie-break: MiniMax, Kimi/Moonshot, DeepSeek, Qwen, GLM/Z.ai, GPT, Mistral.
Prefer higher semantic version in the model name, such as m2.7 over m2.5.
Prefer larger context length when available.
Use model name as the final deterministic tie-break.

Provider Fields

Field	Required	Description
`id`	no	Provider id used by `--provider`; derived from `name` when omitted.
`name`	yes	Display name.
`aliases`	no	Additional unique names accepted by `--provider`.
`type`	yes	Copilot BYOK provider type: `openai`, `anthropic`, or `azure`.
`baseUrl`	yes	BYOK provider base URL.
`apiKeyEnv`	no	Env var name or list of names for API key lookup.
`bearerTokenEnv`	no	Env var name or list for bearer token lookup.
`modelsUrl`	no	URL used to fetch model catalog.
`modelsAuth`	no	Send the provider bearer token to a cross-origin catalog only when explicitly `true`; use `false` or `none` to disable catalog auth.
`modelsHeaders`	no	Non-secret string headers for model catalog requests.
`modelsTimeoutMs`	no	Catalog timeout from 10 to 300000 ms; defaults to 10000 ms.
`catalogModelId`	no	Built-in Copilot model id for internal capabilities.
`defaultModel`	no	Fallback model when catalog fetch fails.
`wireApi`	no	BYOK wire API: `completions` or `responses`.
`maxPromptTokens`	no	Manual prompt token limit.
`maxOutputTokens`	no	Manual output token limit.
`requireToolSupport`	no	Exclude models without tool support metadata.

Safety

API keys are read from environment variables.
Provider config files cannot contain inline API keys or bearer tokens.
Dry-run output redacts secret env values.
Stale COPILOT_PROVIDER_* variables are stripped before launching Copilot.
Provider source-key variables are removed case-insensitively from the child environment.
Catalog requests time out after 10 seconds by default.
Credentials are sent automatically only to same-origin catalog URLs; cross-origin auth requires modelsAuth: true.
BYOK environment variables are passed only to the child Copilot process.
The tool does not write tokens to disk.

Development

Run the complete local quality gate:

npm run check
npm run test:coverage
npm pack --dry-run

Run a dry-run:

copilot-byok --provider chutes --no-model-prompt --dry-run -p "hello"

See Provider verification for the latest reproducible test matrix. It distinguishes endpoint reachability, authenticated catalog access, and complete Copilot CLI inference; these are intentionally not treated as equivalent claims.

Support

If this CLI saves you time when testing Copilot BYOK providers, support continued maintenance through GitHub Sponsors: github.com/sponsors/TheStreamCode.

Third-Party Notice

GitHub and GitHub Copilot are trademarks of GitHub, Inc. This project is not affiliated with or endorsed by GitHub.

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.github		.github
bin		bin
docs		docs
examples		examples
schemas		schemas
src		src
test		test
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

copilot-byok-switcher

Features

Requirements

Installation

Quick Start

Built-In Providers

Custom Provider Config

Why `catalogModelId` and the wire model are separate

Copilot CLI features

Model Ranking

Provider Fields

Safety

Development

Support

Third-Party Notice

About

Releases

Packages

Used by

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

copilot-byok-switcher

Features

Requirements

Installation

Quick Start

Built-In Providers

Custom Provider Config

Why catalogModelId and the wire model are separate

Copilot CLI features

Model Ranking

Provider Fields

Safety

Development

Support

Third-Party Notice

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Why `catalogModelId` and the wire model are separate