OpenAI-compatible access to CommandCode models, credentials, and routing inside a trusted network.

English | 한국어 | 中文

CommandCode Bridge is a trusted-environment HTTP gateway for a CommandCode account. It presents standard OpenAI-compatible model and chat endpoints, routes work across eligible upstream credentials, and publishes an exact 52-model catalog aligned with CommandCode 1.14.0. The bridge version always tracks the current CommandCode CLI version with a letter suffix (for example 1.14.0.c); the suffix marks bridge-only releases.

What it does · Install · Usage · How it works · Repository layout · Current limitations · License

What it does

• Plan-aware upstream selection (auto by default). At startup the bridge probes the official Provider API. Accounts on the Provider plan ($15/mo) or higher get native POST /provider/v1/chat/completions calls with OpenAI bodies — no CLI headers, no per-request cmd subprocess, no event conversion. Go ($1), GOAT ($10), and Pro ($20) subscription plans get 403 upgrade_required, so the bridge keeps the /alpha/generate tunnel for them and falls back to it automatically if a plan changes mid-run. Claude models always use the tunnel because the Provider API serves them only through the Anthropic format.

• OpenAI-compatible API. Lists and retrieves models and serves streaming or non-streaming chat to any OpenAI client, with model aliases, allowlist, and per-key routing transparent to the caller.

• Multi-key routing. Supports daily_burn_priority, balance_priority, round_robin, and drain_first, with per-key concurrency, cooldown, model scope, and pre-output failover.

• Universal expiry priority. Under every policy, eligible credentials with a known expiry in 1 day or less are selected before longer-lived credentials.

• Live model catalog. At startup, when the Provider API is available, the bridge refreshes the catalog from the public GET /provider/v1/models, so newly published models and context windows appear without a static-catalog release.

• Context metadata. Emits context_window, context_length, and max_context_length whenever the catalog has a published context (live values fill the five contexts the static catalog leaves unknown).

• Balance alerts without the CLI. Billing and usage snapshots still come from the /alpha/billing surface with the same Studio key, so routing and alerts keep working with zero CLI involvement.

• Mobile dashboard. Manages bind settings, routing, credentials, and model toggles in Korean, English, and Chinese, with models folded by provider.

• Secret boundary. Loads private credentials without shipping keys or the CommandCode CLI bundle; diagnostics remain redacted.

Install

Linux rootless installer

The installer targets Linux user systemd, requires Node.js 22+ for CommandCode CLI 1.14.0, imports CLI auth when available, writes private state under ~/.config/commandcode-bridge, installs under ~/.local/share/commandcode-bridge, and safely defaults to 127.0.0.1:9992. Use 0.0.0.0 only behind a trusted LAN/VPN/tailnet/firewall/reverse proxy with BRIDGE_API_KEY. Use sudo loginctl enable-linger "$USER" for pre-login startup; uninstall with ./uninstall.sh or ./uninstall.sh --purge-config.

./install.sh
./install.sh --yes --host 127.0.0.1 --port 9992
./install.sh --host 0.0.0.0 --port 9992

Manual source run

The bridge runtime supports Node.js 20+. The default auto mode probes your plan at startup: Provider-plan accounts use the official API directly, while lower tiers keep the /alpha tunnel — either way you only need a Studio-issued API key, no CLI install, no cmd login. Provide the key through COMMAND_CODE_API_KEY, COMMANDCODE_API_KEY, or CMD_API_KEY (or ~/.commandcode/auth.json if you already run the CLI). The legacy alpha mode and /alpha billing reuse the same key. Official installation: https://commandcode.ai/install.

git clone <your-commandcode-bridge-repository-url> commandcode-bridge
cd commandcode-bridge
npm install --include=dev
cp .env.example .env
npm run build
npm start

Docker

Docker and Compose require a full source checkout; the Dockerfile verifies and builds before producing the runtime image. See the deployment guide and release/docker-compose.yml.

docker build -t commandcode-bridge .
docker run --rm -p 127.0.0.1:9992:9992 \
  -e HOST=0.0.0.0 \
  -e COMMANDCODE_API_KEY="$COMMANDCODE_API_KEY" \
  -e BRIDGE_API_KEY="$BRIDGE_API_KEY" \
  commandcode-bridge

Usage

Verify and call the API

export BRIDGE_API_KEY='<same value as the bridge runtime>'
curl -fsS http://127.0.0.1:9992/health | jq
curl -fsS http://127.0.0.1:9992/v1/models \
  -H "Authorization: Bearer $BRIDGE_API_KEY" | jq
curl -fsS http://127.0.0.1:9992/v1/models/deepseek%2Fdeepseek-v4-pro \
  -H "Authorization: Bearer $BRIDGE_API_KEY" | jq

/health is public and secret-free. GET /v1/models lists available models, while GET /v1/models/:model returns one available model or 404 model_not_found; slash-bearing IDs must be URL-encoded. POST /v1/chat/completions returns OpenAI completion JSON or SSE with stream: true; stream_options.include_usage adds a final usage chunk. Supported roles are developer, system, user, assistant, and tool. Tool schemas and emitted calls work; forced tool_choice accepts only omitted, "auto", or "none".

curl -sS http://127.0.0.1:9992/v1/chat/completions \
  -H "Authorization: Bearer $BRIDGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "default",
    "messages": [{"role": "user", "content": "Reply exactly: OK"}],
    "max_tokens": 64,
    "temperature": 0
  }' | jq

API surface

Method	Path	Behavior
GET	/health	Public, secret-free health and runtime summary.
GET	/dashboard	Public read-only shell for trusted networks.
GET	/v1/models	Authenticated when BRIDGE_API_KEY is configured; lists available models.
GET	/v1/models/:model	Authenticated when configured; retrieves one available model.
POST	/v1/chat/completions	Authenticated when configured; streaming or non-streaming chat.
GET	/admin/config	Public redacted dashboard state on the trusted network.
GET	/admin/commandcode/credentials	Public redacted diagnostics; ?refresh=true refreshes billing.
PUT	/admin/config	Requires the current BRIDGE_API_KEY; a keyless runtime may bootstrap only over a loopback peer and loopback Host.
POST	/admin/restart	Uses the same authentication rule; the pre-restart key remains current until restart completes.

Model metadata and exact catalog

Each model object includes id, object, created, and provider-derived owned_by. Known context is repeated in context_window, context_length, and max_context_length. When the Provider API is available the catalog is refreshed from the live GET /provider/v1/models at startup, which fills the five contexts the static catalog leaves unpublished (all currently 200,000) and picks up newly added models; the static table below is the shipped 1.14.0 baseline. “Default” is the built-in enabled state.

Provider	Canonical model ID	Context	Default
DeepSeek	deepseek/deepseek-v4-pro	1,000,000	Yes
DeepSeek	deepseek/deepseek-v4-flash	1,000,000	Yes
Moonshot	moonshotai/Kimi-K3	1,000,000	No
Moonshot	moonshotai/Kimi-K2.7-Code	256,000	No
Moonshot	moonshotai/Kimi-K2.7-Code-Highspeed	262,000	No
Moonshot	moonshotai/Kimi-K2.6	256,000	Yes
Moonshot	moonshotai/Kimi-K2.5	256,000	No
Z.ai	zai-org/GLM-5.2	1,000,000	No
Z.ai	zai-org/GLM-5.2-Fast	1,000,000	No
Z.ai	zai-org/GLM-5.1	200,000 (live)	Yes
Z.ai	zai-org/GLM-5	200,000	No
MiniMax	MiniMaxAI/MiniMax-M3	1,000,000	No
MiniMax	MiniMaxAI/MiniMax-M2.7	200,000 (live)	Yes
MiniMax	MiniMaxAI/MiniMax-M2.5	200,000	No
Xiaomi	xiaomi/mimo-v2.5-pro	1,000,000	No
Xiaomi	xiaomi/mimo-v2.5	1,000,000	No
Qwen	Qwen/Qwen3.8-Max	1,000,000	No
Qwen	Qwen/Qwen3.7-Max	1,000,000	No
Qwen	Qwen/Qwen3.7-Plus	1,000,000	No
Qwen	Qwen/Qwen3.7-Flash	1,000,000	No
Qwen	Qwen/Qwen3.6-Max-Preview	200,000 (live)	No
Qwen	Qwen/Qwen3.6-Plus	200,000 (live)	Yes
StepFun	stepfun/Step-3.7-Flash	256,000	No
StepFun	stepfun/Step-3.5-Flash	1,000,000	No
Tencent	tencent/hy3-paid	262,000	No
NVIDIA	nvidia/nemotron-3-ultra-550b-a55b	1,000,000	No
Thinking Machines	thinkingmachines/inkling	256,000	No
Thinking Machines	thinkingmachines/inkling-small	1,000,000	No
Poolside	poolside/laguna-s-2.1-free	256,000	No
Anthropic	claude-sonnet-5	1,000,000	No
Anthropic	claude-sonnet-4-6	1,000,000	No
Anthropic	claude-fable-5	1,000,000	No
Anthropic	claude-opus-5	1,000,000	No
Anthropic	claude-opus-4-8	1,000,000	No
Anthropic	claude-opus-4-7	1,000,000	No
Anthropic	claude-haiku-4-5-20251001	200,000	No
OpenAI	gpt-5.6-sol	1,050,000	No
OpenAI	gpt-5.6-terra	1,050,000	No
OpenAI	gpt-5.6-luna	1,050,000	No
OpenAI	gpt-5.5	200,000 (live)	No
OpenAI	gpt-5.4	400,000	No
OpenAI	gpt-5.3-codex	400,000	No
OpenAI	gpt-5.4-mini	400,000	No
Google	google/gemini-3.6-flash	1,000,000	No
Google	google/gemini-3.5-flash	1,000,000	No
Google	google/gemini-3.5-flash-lite	1,000,000	No
Google	google/gemini-3.1-flash-lite	1,000,000	No
Sakana	sakana/fugu-ultra	1,000,000	No
Meta	meta/muse-spark-1.1	1,050,000	No
Meta	meta/muse-spark-1.2	1,050,000	No
Meta	meta/muse-spark-1.2-contributor	1,050,000	No
xAI	xai/grok-4.5	500,000	No

Dashboard and credential routing

Open http://127.0.0.1:9992/dashboard. The mobile-first UI stores its Korean/English/Chinese locale in localStorage with Korean fallback. It shows online/version state; edits bind, client key, routing and per-key concurrency; manages and refreshes redacted credentials; and folds the model catalog by provider with enabled/total counts. Secret fields left blank preserve existing keys. Save writes JSON and restart applies changes. Raw upstream keys are never returned.

daily_burn_priority is the default and weights required daily burn (depletion_aware is its legacy alias); balance_priority prefers usable balance; round_robin rotates smoothly by weight; drain_first drains the eligible key with the least remaining time, then moves to the next. Every policy first narrows to eligible credentials expiring within 1 day. Manual disablement, allowedModels, in-flight caps, exhausted/expired balance, auth failure, and 429/5xx/timeout cooldown can exclude a key. Each request stays on one key; failover occurs only before visible output.

Configuration and operations

Upgrades from a persisted 1.3.1 dashboard catalog preserve each current model's enabled state and all custom models, while refreshing built-in metadata from the 1.14.0 canonical definitions. Six retired 1.3.1 IDs are removed rather than forwarded as unknown upstream models; a retired configured default falls back to deepseek/deepseek-v4-pro.

Existing browsers with a saved key continue without interruption. On a fresh browser, enter the current key in Current Admin API Key before saving or restarting. A runtime with no key can bootstrap only from a real loopback connection whose Host is also loopback.

Credential precedence is COMMANDCODE_CREDENTIALS_FILE, COMMANDCODE_CREDENTIALS/COMMANDCODE_API_KEYS, then COMMAND_CODE_API_KEY/COMMANDCODE_API_KEY/CMD_API_KEY, then CLI auth files. Core defaults are HOST=127.0.0.1, PORT=9992, COMMANDCODE_UPSTREAM_MODE=auto, COMMANDCODE_ROUTING_POLICY=daily_burn_priority, COMMANDCODE_MAX_IN_FLIGHT_PER_CREDENTIAL=4, COMMANDCODE_CLI_VERSION=1.14.0, COMMANDCODE_TIMEOUT_MS=600000, COMMANDCODE_RETRY_MAX_ATTEMPTS=5, COMMANDCODE_RETRY_BACKOFF_MS=250, and COMMANDCODE_EMPTY_VISIBLE_RESPONSE_POLICY=error_on_length. Transient upstream failures (429, 5xx, timeouts) are retried with exponential backoff up to COMMANDCODE_RETRY_MAX_ATTEMPTS; a credential that fails with 401/402/403 is skipped for the rest of the request while other keys are preferred, and retries stop once any visible output has been emitted. BRIDGE_API_KEY protects /v1/* when set; clients may use Bearer or x-api-key. COMMANDCODE_UPSTREAM_MODE=auto probes the Provider API at startup and uses it whenever the plan allows (the Provider plan at $15/mo or higher); provider forces the official API and alpha forces the legacy /alpha/generate path for every model. Set COMMANDCODE_ZDR=true to send x-cmd-zdr: 1 (zero data retention) on Provider API requests. Protect credential JSON with chmod 600. Optional balance alerts are off. Optional commandcode-router is for least-in-flight routing across multiple bridge hosts.

How it works

1. Authenticate and validate the OpenAI-shaped request.

2. Resolve model aliases against the catalog (live-refreshed when the Provider API is available).

3. Filter disabled, scoped, saturated, cooled-down, expired, and exhausted credentials.

4. Prioritize any eligible credential expiring within 1 day, then apply the configured policy.

5. Call the official POST /provider/v1/chat/completions with a native OpenAI body (Claude models and alpha mode keep using POST /alpha/generate).

6. Stream the provider's OpenAI SSE through with the public model id (alpha mode converts CommandCode stream events instead), including optional usage.

7. Verify with tests, npm run verify, /health, model discovery, and npm run smoke.

Repository layout

src/                 bridge, catalog, routing, dashboard, and API implementation
tests/               deterministic contract and behavior tests
docs/                architecture, deployment, security, and documentation assets
release/             Compose and production deployment material
install.sh           Linux rootless user-systemd installer

Development verification is npm run verify; runtime verification is npm run smoke. SMOKE_ACCEPT_UPSTREAM_ERRORS=1 npm run smoke verifies explicit fail-closed routing when credit blocks generation, but is not a generation-readiness canary.

Current limitations

• Trusted network boundary. Read-only dashboard endpoints reveal redacted operational metadata; keep them on localhost or a trusted VPN/tailnet and set BRIDGE_API_KEY outside localhost.

• Claude traffic uses the alpha tunnel. The Provider API serves Claude models only through the Anthropic /messages format, so Claude requests always go to /alpha/generate; set COMMANDCODE_UPSTREAM_MODE=alpha to force that path for every model.

• Billing stays on the alpha surface. /alpha/billing is not a documented Provider API route; pin COMMANDCODE_CLI_VERSION and smoke-test upgrades so routing and balance alerts keep working.

• No account-limit bypass. Billing, credits, rate limits, and terms still apply; monitor diagnostics and eligible credentials.

• Dynamic catalog is best-effort. The startup refresh falls back to the static catalog when the live models endpoint is unreachable; context metadata is only as current as the last successful refresh.

Do not commit .env, CLI auth files, credential JSON, keys, billing details, private topology, or dashboard exports. This is not a public proxy or internet control plane. See the security guide.

License

CommandCode Bridge uses the MIT License. CommandCode is separate software with its own terms; this repository does not include or repackage its proprietary CLI bundle.

CommandCode Bridge · a trusted boundary for OpenAI-compatible CommandCode access.