shunt

shunt

Offline credential import: shunt import opencodex --dry-run previews compatible API keys and Cursor/Command Code access tokens. Exports create new private snapshots without changing existing settings or copying refresh tokens. See credential import.

English · 한국어 · 日本語 · 简体中文

Shunt Claude Code to any model.

shunt is a spec-compliant Claude Code LLM gateway: a transparent proxy that, for the models you map, diverts inference to another LLM provider at the inference layer. It routes by the request's model id — everything else passes through to Anthropic unchanged (the "shunt"; the fallback is configurable via server.default_provider).

The name is the mechanism: an electrical/railway shunt diverts a selected part of the flow onto a parallel path. Here, a mapped model's inference is diverted to another provider while Claude Code's tools and skills stay intact.

Providers for OpenAI, ChatGPT/Codex, xAI, Grok, Cursor, Kimi Code, Zhipu, MiniMax China, OpenCode Zen, Gemini, Antigravity, and Anthropic passthrough ship built in — several of them reusing a subscription you already pay for. Any Anthropic-Messages-compatible backend is one config table away, with no code changes. See Providers.

[!NOTE] shunt is pre-1.0 software under active development. Per SemVer, 0.x releases may include breaking changes to configuration keys, the CLI, and behavior — check the release notes before upgrading.

Install

# Homebrew (macOS / Linux)
brew install pleaseai/tap/shunt

# Install script (macOS / Linux) — prebuilt binary from the GitHub release
curl -fsSL https://shunt.sh/install.sh | sh

# Cargo, directly from the source repository
cargo install --git https://github.com/pleaseai/shunt

New versions are distributed through Homebrew and prebuilt binaries (macOS/Linux, arm64/x64) attached to each GitHub release; the crates.io package stops at the last version published there. See Installation for prebuilt-binary and from-source instructions.

The cargo install line above builds without the admin dashboard: its bundle needs Node.js 22.12+ and is embedded only by --features ui, which Homebrew and the release binaries already enable. Everything else — including the admin JSON API — is identical either way. Installation has the from-source steps.

Run as a service (macOS/Homebrew)

brew services start shunt

Logs go to $(brew --prefix)/var/log/shunt.log. brew services stop sends SIGTERM, and shunt drains in-flight requests before exiting — for up to [server] shutdown_timeout_seconds (default 30; changing this one does need a restart), after which shunt stops waiting and exits, so a quiet SSE stream cannot hold the process open forever. On Unix, Antigravity agent turns are terminated when shutdown starts so their isolated process groups cannot hold the drain open. Editing the config file afterwards doesn't need a restart — it hot-reloads automatically. Details: Running as a service.

Quickstart

# shunt.toml — route a gpt-* id to your ChatGPT subscription
# [[routes]] is legacy for exact ids; prefer [models.upstream_model].
[[routes]]
model = "gpt-5.6-sol"
provider = "codex"        # reuses `codex login`; use `openai` for OPENAI_API_KEY

codex login                                        # provider credential
shunt run                                           # -> listening on 127.0.0.1:3001

export ANTHROPIC_BASE_URL=http://127.0.0.1:3001
export ANTHROPIC_CUSTOM_MODEL_OPTION="gpt-5.6-sol"
claude                                              # /model -> pick gpt-5.6-sol

Unmapped models (all your claude-* ids) keep working exactly as before — shunt forwards them to Anthropic with your own credential. Full walkthrough: Quickstart.

Starter configuration

shunt init creates a commented shunt.toml in an existing directory. Keep the default passthrough starter, or scaffold ordered upstream presets without changing the fallback for unmapped models:

shunt init
shunt init --upstream codex --upstream kimi

Agent-native setup blueprints

shunt add retrieves embedded Markdown implementation guides for coding agents. List the available upstream blueprints with shunt add upstream, or pipe one directly into an agent:

shunt add upstream kimi --print | claude
shunt add upstream https://provider.example/docs --print | claude

The command is offline and read-only: it prints guidance but never edits files, installs anything, or accesses the network. Use shunt add provider <absolute-url> when contributing support for a genuinely new provider protocol.

Providers

A provider is either an ordered [[upstreams]] entry or a legacy [providers.<name>] TOML table (under YAML, an entry in the corresponding sequence or mapping). Two adapter kinds cover most upstreams: kind = "anthropic" (the upstream speaks Anthropic Messages; passed through, optionally with a different key) and kind = "responses" (the upstream speaks the OpenAI Responses API; shunt translates Anthropic Messages ⇄ Responses, streaming included, and emulates stop_sequences gateway-side because the Responses API has no stop parameter). A third native kind, kind = "cursor", bridges Cursor's ConnectRPC/protobuf AgentService so a Cursor subscription is reachable through the same Anthropic-Messages interface.

Ordered upstreams enable cross-provider failover. Declaration order is the attempt order; a model's upstream_model map selects the participating entries and maps its public id to each backend's id:

[server]
default_provider = "anthropic-primary"

[[upstreams]]
name = "anthropic-primary"
provider = "anthropic" # preset: kind, base_url, and default auth
auth = { mode = "claude_oauth", account = "primary" }

[[upstreams]]
name = "codex-fallback"
provider = "codex" # defaults to chatgpt_oauth

[[models]]
id = "claude-opus-4-8"
[models.upstream_model]
anthropic-primary = "claude-opus-4-8"
codex-fallback = "gpt-5.6-sol"

This chain tries anthropic-primary and then codex-fallback. auth accepts either a mode string or a map; claude_oauth and chatgpt_oauth maps can narrow credentials with account = "name" or accounts = [...]. Legacy [providers.<name>] remains supported and becomes implicit name-sorted upstreams. Do not declare both forms: mixing [[upstreams]] with [providers.*] is a configuration error. See the configuration reference for presets, failure classes, and migration details.

Built in

These providers are seeded by default, so provider = "<name>" routes to them with no [providers.*] table of your own — but only while you declare no [[upstreams]]. An ordered [[upstreams]] list replaces the provider map entirely, so under that form every provider you route to must be declared there, presets included:

Name	Kind	Auth	Backend
anthropic	anthropic	passthrough or Claude OAuth account pool	api.anthropic.com — forwards the caller's credential by default; auth = "claude_oauth" enables pooled subscription credentials
openai	responses	OPENAI_API_KEY	api.openai.com/v1
codex	responses	ChatGPT OAuth	chatgpt.com/backend-api — reuses ~/.codex/auth.json (codex login)
xai	responses	XAI_API_KEY	api.x.ai/v1 — the developer API, billed per token
grok	responses	xAI OAuth	cli-chat-proxy.grok.com/v1 — the Grok CLI proxy; reuses ~/.shunt/xai-auth.json (shunt login xai with a SuperGrok / X Premium+ subscription)
cursor	cursor	Cursor OAuth	api2.cursor.sh — reuses ~/.shunt/cursor-auth.json (shunt login cursor)
gemini	gemini	Google OAuth	cloudcode-pa.googleapis.com — Google Code Assist backend; reuses ~/.gemini/oauth_creds.json
antigravity	antigravity	Antigravity OAuth	daily-cloudcode-pa.googleapis.com — Google Antigravity backend over HTTP; uses ~/.shunt/antigravity-auth.json (shunt login antigravity), or named accounts under ~/.shunt/accounts/antigravity (shunt login antigravity --name, selected via accounts = [...])
antigravity-cli	antigravity_cli	None (local CLI)	Deprecated. Local agy binary — same backend via subprocess; superseded by antigravity above

Ordered [[upstreams]] entries additionally accept the presets kimi, kimi-code, zhipu, minimax-cn, and opencode, which fill in kind, base_url, and the default auth for those backends.

Per-provider setup, model ids, and caveats live under Providers — including xAI's OAuth tier gate (xAI / Grok), Cursor's agent-mode prefixes (Cursor), and Antigravity's two transports and the kind = "antigravity" migration (Antigravity).

[!WARNING] antigravity-cli is deprecated and is arbitrary code execution: it runs the local agy binary agentically with --dangerously-skip-permissions, as the user running shunt. Keep its sandbox setting on, keep the bind on loopback, and prefer the antigravity provider, which needs none of this. See the deprecated transport.

Any Anthropic-compatible backend

One table, no code changes:

Provider	base_url	Example model IDs
Kimi (Moonshot)	https://api.moonshot.ai/anthropic	kimi-k3[1m], kimi-k2.7-code
Kimi Code (subscription, OAuth)	https://api.kimi.com/coding	use the ids your subscription exposes
DeepSeek	https://api.deepseek.com/anthropic	deepseek-v4-pro, deepseek-v4-flash
Z.ai (GLM)	https://api.z.ai/api/anthropic	glm-5.2, glm-4.7
Zhipu (GLM China)	https://open.bigmodel.cn/api/anthropic	glm-5.3, glm-5.3-flash
MiniMax	https://api.minimax.io/anthropic	see MiniMax docs
MiniMax China	https://api.minimax.cn/anthropic	MiniMax-M3
OpenCode Zen	https://opencode.ai/zen	claude-fable-5-1, gpt-6-astra — curated cross-vendor catalog; reads x-api-key
OpenRouter	https://openrouter.ai/api	anthropic/claude-opus-4.8
Vercel AI Gateway	https://ai-gateway.vercel.sh	anthropic/claude-opus-4.8