Skip to content

README.md

Latest commit

 

History

History
148 lines (112 loc) · 6.32 KB

README.md

File metadata and controls

148 lines (112 loc) · 6.32 KB
Raw

commandcode-proxy (Go)

CI

A single-binary, dependency-free proxy for the Command Code API. It exposes an OpenAI Chat Completions surface (/v1/chat/completions, /v1/models) and translates generation calls to Command Code's /alpha/generate endpoint, so OpenAI-compatible clients (the openai SDK, Hermes Agent, curl) can drive a Command Code subscription unchanged.

This is a Go port of — and the actively-maintained successor to — the Python commandcode-proxy (now deprecated), built for one-file deployment: a static binary you copy and run, no runtime to install.

Unofficial and community-maintained. Not affiliated with Command Code. It forwards requests to the public Command Code API using your own key.

Why a proxy

Command Code's OpenAI-compatible surface (/provider/v1/chat/completions) requires the paid Provider tier; a normal subscription only works against the custom /alpha/generate endpoint. This proxy speaks /alpha/generate upstream and OpenAI downstream, so your existing plan works from any compatible tool.

What it does

  • POST /v1/chat/completions — streaming and non-streaming, with tool calling, reasoning (reasoning_content out, reasoning_effort in), and image input (image_url parts; data or https URLs), including images in tool messages. Tool-call arguments stream incrementally; images from consecutive tool results are forwarded together after all results.
  • GET /v1/models — proxies Command Code's live model catalog.
  • GET /health, plus a minimal status + request-log dashboard at GET /admin.

Keyless by design: every request carries the caller's own Command Code key (Authorization: Bearer <key>), relayed verbatim. Nothing is stored, so one instance can serve callers on different accounts.

Interrupted upstream streams return errors, including when partial output has already arrived. Streaming responses report an SSE error after headers are sent; buffered responses return an HTTP error. A stream must reach a successful finish event to count as complete.

Build & run

Requires Go 1.23+ to build; the result needs nothing at runtime.

make build                      # -> ./commandcode-proxy (static, CGO disabled)
./commandcode-proxy             # serves http://127.0.0.1:8787

Or straight from source:

go run ./cmd/commandcode-proxy

For Docker, a systemd unit, client/SDK setup, and the full options reference, see docs/INSTALL.md.

Bind elsewhere with COMMANDCODE_PROXY_HOST / COMMANDCODE_PROXY_PORT (e.g. COMMANDCODE_PROXY_HOST=0.0.0.0 to reach it from the LAN).

Deploy the single binary

make release                    # cross-compiled static binaries in ./dist
#   dist/commandcode-proxy-linux-amd64
#   dist/commandcode-proxy-linux-arm64
#   dist/commandcode-proxy-darwin-amd64
#   dist/commandcode-proxy-darwin-arm64

Copy the right one to the target host and run it — no Python, no venv, no dependencies. Pair it with a systemd unit or a container as you like.

Configuration

All optional, via environment variables:

Variable Default Purpose
COMMANDCODE_PROXY_HOST / _PORT 127.0.0.1 / 8787 Listen address
COMMANDCODE_PROXY_LOG_LEVEL info debug/info/warn/error; each request is logged at info+, warn/error quiet it
COMMANDCODE_MODEL_ALIASES – JSON map of model-id overrides
COMMANDCODE_API_BASE https://api.commandcode.ai Upstream base URL
COMMANDCODE_MAX_RETRIES 2 Retries for transient upstream 5xx/429 before any content
COMMANDCODE_TIMEOUT 300 Upstream response-header timeout (seconds)
COMMANDCODE_STREAM_IDLE_TIMEOUT 300 Maximum wait for upstream body data (seconds); 0 disables
COMMANDCODE_WORKING_DIR proxy's cwd Working directory reported to Command Code as grounding context

Model aliases. A request's model is resolved before forwarding: an exact full-id key in COMMANDCODE_MODEL_ALIASES wins, then a Claude-family match — a key of opus/sonnet/haiku overrides that whole family, else the built-in default (opus → deepseek/deepseek-v4-pro, sonnet/haiku → deepseek/deepseek-v4-flash) — then the id unchanged. So {"opus":"zai-org/GLM-5.2"} remaps every opus id in Chat Completions requests.

Connect a client

# OpenAI SDK / curl
curl http://127.0.0.1:8787/v1/chat/completions \
  -H "Authorization: Bearer user_..." -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen3.7-Plus","messages":[{"role":"user","content":"Say PONG"}]}'

Dashboard

A minimal status page lives at http://127.0.0.1:8787/admin — open it in a browser for uptime, total requests, and a live table of recent requests (method, path, model, status, latency), refreshing every few seconds.

It records request metadata only — never your API key or message content — in a small in-memory ring (the last 200 requests, cleared on restart). The page is unauthenticated and meant for loopback; don't expose it on a public bind.

Tests

make test        # unit + route tests (fake Command Code backend, no network)

Layout

Path Responsibility
cmd/commandcode-proxy Entrypoint (env-driven host/port)
internal/config Environment settings, model-alias resolution
internal/auth Keyless API-key extraction
internal/translate Pure OpenAI ⇄ Command Code translation
internal/upstream /alpha/generate streaming, retry, error classification
internal/server Routes, response assembly, error mapping, /admin dashboard

See docs/INSTALL.md for install/deploy/client setup, docs/ARCHITECTURE.md for the design rationale (decisions D1–D16), docs/ROADMAP.md for deferred work, and AGENTS.md for contributor/agent guidance.

Credits

Translation logic ported from the Python commandcode-proxy, itself ported from patlux/pi-commandcode-provider. Licensed under MIT — see LICENSE.