0.37.1 • Published yesterdayCLI

copilot-api-node20

Licence

—

Version

0.37.1

Deps

Size

169 kB

Vulns

Weekly

Summary Dependency Versions

copilot-api

A proxy server that turns a GitHub Copilot subscription into fully compatible OpenAI and Anthropic API endpoints. Use Claude Code, Claude Cowork, Codex CLI, and any tool that speaks the API -- all through the Copilot plan you already pay for, no separate API keys required.

  Clients                        Proxy                         Backends
  ───────                        ─────                         ────────

  Claude Code   ─┐                                        ┌─▶ GitHub Copilot API
  Claude Cowork ─┤  /v1/messages     ┌─────────────┐      │     Messages
  Codex CLI     ─┤───── or ─────────▶│ copilot-api │──────┤     Chat Completions
  OpenAI SDK    ─┤  /v1/chat/        └─────────────┘      │     Responses API
  curl          ─┤  completions                           │     Embeddings
  Any tool      ─┘                                        │
                                                          └─▶ Web Search
                                                              (Tavily / Exa)

Key Features
Quick Start
API Endpoints
CLI Reference
Telemetry
Closed Source
Notices
Attribution
License

Key Features

Feature	Description
Full Claude Code support	All Claude models, streaming, extended thinking, and the complete 1M token context window
Claude Cowork support	Run Claude's desktop app through Copilot — one-command setup via Tailscale for zero-trust-hassle HTTPS
Full Codex CLI support	Complete OpenAI Responses API implementation purpose-built for Codex CLI
Web search	Optional web search for Claude Code and Codex sessions, via Tavily and/or Exa with automatic failover
Dual API compatibility	OpenAI Chat Completions, Anthropic Messages, and OpenAI Responses APIs side by side
HTTPS with auto-generated certs	Self-signed TLS certs with configurable SANs -- works across VMs, containers, and LAN
Zero configuration	Single command to start -- authenticates via GitHub device-code OAuth

Quick Start

Prerequisites: Node.js 20+ (or Bun) and an active GitHub Copilot subscription.

Claude Code

Start the proxy with Claude Code mode:

npx copilot-api-node20@latest start --claude-code

On first run, you authenticate via GitHub device-code OAuth. Once authenticated, the proxy starts on http://localhost:4141 and prints a ready-to-paste command. In another terminal:

ANTHROPIC_BASE_URL=http://localhost:4141 claude

To skip the interactive model picker, specify models upfront:

npx copilot-api-node20@latest start \
  --claude-code \
  --model claude-opus-4.6-1m \
  --small-model claude-haiku-4.5

Codex CLI

Start the proxy with Codex mode:

npx copilot-api-node20@latest start --codex --model gpt-5.3-codex

Configure ~/.codex/config.toml:

model = "gpt-5.5"
model_provider = "local"

[model_providers.local]
name = "Local Server"
base_url = "http://localhost:4141/v1"
wire_api = "responses"
requires_openai_auth = false

[model_providers.local.http_headers]
Authorization = "Bearer dummy"

Then run:

codex

Web Search

Web search tool calls (in both Claude Code and Codex sessions) are served by one or more search providers. Configure providers via environment variables — the proxy operates normally when none are set (web search is simply unavailable).

Provider	Env var	Free tier
Tavily	`TAVILY_API_KEY`	1,000 searches/mo
Exa	`EXA_API_KEY`	1,000 searches/mo

Set one or both — web search works with a single provider, and configuring two enables automatic failover.

TAVILY_API_KEY=<key> EXA_API_KEY=<key> npx copilot-api-node20@latest start --claude-code

When more than one provider is configured, searches run against them in order and fail over to the next provider on error or timeout. Control the order with --web-search-provider (comma-separated, primary first); it defaults to all configured providers, Tavily first:

# Prefer Exa, fall back to Tavily
EXA_API_KEY=<key> TAVILY_API_KEY=<key> \
  npx copilot-api-node20@latest start --claude-code --web-search-provider exa,tavily

The --tavily-api-key flag is deprecated — it still works and is equivalent to TAVILY_API_KEY, but prints a deprecation warning on startup. Prefer the environment variables, which also keep keys out of the process list.

Claude Cowork

Use Claude's desktop app (Cowork) with your Copilot subscription. Requires Tailscale (free for personal use) for a real Let's Encrypt TLS certificate — no self-signed cert headaches.

1. Install Tailscale and sign in. On macOS, use the App Store or .pkg download (not brew). See docs/claude-cowork.md for Linux/Windows.

2. Generate a TLS cert and configure the proxy:

npx copilot-api-node20@latest cowork-setup install
npx copilot-api-node20@latest start --claude-cowork

3. Follow Anthropic's Cowork 3P Installation guide. When prompted for the gateway URL, paste the Tailscale hostname from the startup banner (e.g. https://your-machine.tail12345.ts.net:4141), then restart Cowork.

Run cowork-setup doctor at any time to diagnose issues:

npx copilot-api-node20@latest cowork-setup doctor

See docs/claude-cowork.md for the full setup guide and troubleshooting. For Cowork's own configuration docs, see Claude Cowork 3P Installation.

First run & troubleshooting

On a successful start the proxy runs a one-shot self-test generation and prints the result, so you know immediately whether everything works end-to-end — you'll see something like:

Self-test passed — generation works via claude-haiku-4.5 (612ms). Point your client at http://127.0.0.1:4141

If it fails, the line tells you why (e.g. no Copilot entitlement, premium quota exhausted, model not supported on your plan). It spends one generation per boot (preferring a cheap, non-premium model when available); disable it with --no-smoke-test (or COPILOT_API_NO_SMOKE_TEST=1) — e.g. in CI or if you restart frequently.

Stuck? Run the doctor. It checks your token, auth, Copilot entitlement, model catalog, and one real generation, then tells you exactly what to fix:

npx copilot-api-node20@latest doctor

Quick smoke test from another terminal (no client needed):

curl http://localhost:4141/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"claude-haiku-4.5","messages":[{"role":"user","content":"ping"}],"max_tokens":1}'

Symptom	Likely cause	Fix
Client connects but nothing happens	Client not pointed at the proxy	Set the base URL (see below); run `doctor`
`400 ... model is not supported`	Premium model not entitled on your plan	Use `claude-haiku-4.5`, or check entitled models with `doctor`
`402 quota_exceeded`	Monthly premium quota used up	Switch to a non-premium model (haiku) or wait for reset
`404` on `/v1/v1/...`	Base URL already ends in `/v1`	Drop the trailing `/v1` from your client's base URL
Works locally but not from Docker/another machine	Bound to localhost	Start with `--hostname 0.0.0.0`

Client base URLs — Claude Code: ANTHROPIC_BASE_URL=http://localhost:4141; Codex: OPENAI_BASE_URL=http://localhost:4141/v1; OpenAI SDKs: baseURL: "http://localhost:4141/v1". See docs/getting-started.md for the full per-client setup, the entitled-model matrix, and detailed troubleshooting.

API Endpoints

All endpoints are served at http://localhost:4141 by default (https:// when --https or --claude-cowork is used). The server binds to 127.0.0.1 (localhost only) by default. To expose to LAN/network/Docker, pass --hostname 0.0.0.0.

Method	Path	Compatibility
`POST`	`/v1/chat/completions`	OpenAI Chat Completions
`POST`	`/v1/responses`	OpenAI Responses API
`POST`	`/v1/messages`	Anthropic Messages
`POST`	`/v1/messages/count_tokens`	Anthropic Token Counting
`POST`	`/v1/embeddings`	OpenAI Embeddings
`GET`	`/v1/models`	OpenAI Models
All OpenAI-compatible routes are also available without the `/v1/` prefix.

CLI Reference

Commands

Command	Description
`copilot-api start`	Start the proxy server
`copilot-api auth`	Authenticate with GitHub
`copilot-api check-usage`	Display Copilot usage quota
`copilot-api doctor`	Diagnose your setup end-to-end (token, auth, entitlement, models, one real generation) and print exact fixes
`copilot-api debug`	Print diagnostic information
`copilot-api cowork-setup`	Manage Claude Cowork OS-level setup

`start` Flags

--claude-code and --codex are mutually exclusive.

Full flag reference

Flag	Alias	Default	Description
`--port`	`-p`	`4141`	Port to listen on
`--hostname`	`-H`	`127.0.0.1`	Hostname/IP to bind to. Use `0.0.0.0` for LAN/Docker exposure
`--claude-code`	`-c`		Enable Claude Code compatibility mode
`--codex`			Enable Codex CLI compatibility mode
`--model`	`-m`		Primary model to use
`--small-model`	`-s`		Lightweight model for fast tasks (Claude Code)
`--rate-limit`	`-r`		Minimum seconds between requests
`--timeout`	`-t`	`600000`	Request timeout in ms (default 10 min)
`--account-type`	`-a`	`individual`	`individual`, `business`, or `enterprise`
`--github-token`	`-g`		Provide a GitHub token directly (skips OAuth)
`--show-token`			Display tokens on fetch and refresh, and enable the local `/token` debug endpoint
`--smoke-test`		`true`	Run one self-test generation after startup and print PASS/FAIL. Disable with `--no-smoke-test` or `COPILOT_API_NO_SMOKE_TEST=1`
`--tavily-api-key`			Deprecated — prefer `TAVILY_API_KEY` env var. Tavily API key for web search
`--web-search-provider`			Web search providers in primary→fallback order, e.g. `exa,tavily` (keys via `TAVILY_API_KEY` / `EXA_API_KEY`)
`--verbose`	`-v`		Enable debug-level logging
`--https`			Serve over HTTPS using a self-signed cert
`--https-cert`			Path to a PEM-encoded TLS certificate (use with `--https-key`)
`--https-key`			Path to a PEM-encoded TLS private key (use with `--https-cert`)
`--https-hosts`			Extra hostnames or IPs to include in the cert's SANs (comma-separated)
`--claude-cowork`			Auto-detect Tailscale cert and enable HTTPS for Cowork. Run `cowork-setup install` first. See docs/claude-cowork.md

`cowork-setup`

Manage Tailscale-based HTTPS for Claude Cowork.

Subcommand	Description
`cowork-setup doctor`	Diagnose Tailscale + cert status
`cowork-setup install`	Generate a Tailscale TLS certificate for Cowork
`cowork-setup revert`	Remove the generated cert files

Requires Tailscale installed and connected (tailscale up). See docs/claude-cowork.md.

Platform support: macOS, Linux, Windows — anywhere Tailscale runs.

Telemetry

This tool collects anonymous usage telemetry via OpenTelemetry. Only operational metrics are collected -- request counts, latency, model usage, and error rates. No prompts, completions, or personal information is ever collected.

When a server-side error occurs, an anonymous, sanitized error report (error type, status code, model, route, and runtime/version metadata -- never prompts, completions, headers, or tokens) is automatically sent to help diagnose and fix bugs. Disable it with --no-error-reporting or COPILOT_API_ERROR_REPORTING=0.

By using copilot-api, you agree to this telemetry data collection.

Closed Source

The source code is not publicly available.

This fork represents ~9 months of sustained engineering work -- bug fixes, new features, and hardening that go well beyond the original project. Keeping it closed-source protects that investment and ensures a single, well-maintained distribution.

The original open-source project is available at ericc-ch/copilot-api.

Notices

This project relies on reverse-engineered, undocumented GitHub APIs. It is not affiliated with or endorsed by GitHub, Microsoft, Anthropic, or OpenAI and may break without notice.

Use --rate-limit to throttle requests and reduce abuse-detection risk.
Review the GitHub Acceptable Use Policies and GitHub Copilot Terms before use.
This software is provided as-is with no warranty.

Attribution

Originally created by Erick Christian -- ericc-ch/copilot-api. His work built the foundation: authentication flow, API translation layer, and streaming implementation.

This fork has diverged significantly over ~9 months with extensive bug fixes and major new features -- Anthropic Messages API, OpenAI Responses API, Claude Code mode, Codex CLI support, web search integration, usage telemetry, and more. It is maintained as a separate project by johnib.

License

MIT

Keywords

proxy github-copilot openai-compatible anthropic-compatible claude-code claude-cowork codex-cli node20 fork