API reference

The ModelPanel CLI, HTTP endpoints, response headers, virtual models, environment variables, and file layout.

CLI

npx modelpanel serve
npx modelpanel add-key <provider>
npx modelpanel models
npx modelpanel status
npx modelpanel doctor

servecmdOPTIONAL

Start the gateway on 127.0.0.1:8787 (spawns the fusion sidecar on 127.0.0.1:8791). Flags: –host, –port — or the MODELPANEL_HOST / MODELPANEL_PORT env vars.

add-keycmdREQUIRED

Prompted key entry for a provider — stored in ~/.modelpanel/keys.json (chmod 600) with a tier flag. Env alternative: MODELPANEL_<PROVIDER>_API_KEY wins over the vault file.

modelscmdOPTIONAL

Print the merged registry view — every probe-verified model with its task class and tier.

statuscmdOPTIONAL

Probe summary and recent changelog.

doctorcmdOPTIONAL

Key validity check per provider.

HTTP endpoints

Endpoint	Dialect	Notes
`POST /v1/chat/completions`	OpenAI Chat Completions	streaming + non-streaming, tools, JSON-schema response format
`POST /v1/responses`	OpenAI Responses (priority dialect)	typed stream events, `previous_response_id` via TTL store, built-in tools rejected with a clear 400
`POST /v1/messages`	Anthropic Messages	streaming + non-streaming, `tool_use` blocks, Claude Code drop-in
`GET /v1/models`	—	merged registry view; per-provider discovery, tagged with task class and tier
`GET /health`	—	gateway + fusion sidecar status

Response headers

Every response says who served:

Header	Meaning
`x-modelpanel-provider`	The provider that served the request
`x-modelpanel-model`	The model that served the request
`x-modelpanel-fallback-from`	Present when the first choice failed over
`x-modelpanel-notice`	Opportunity notice — the served model also lives somewhere healthier
`x-modelpanel-mode: fusion-degraded`	The fusion panel exceeded the latency budget; the best single member served

Notices also appear as a notice body field (non-streamed) and a terminal-event field (streamed) — once per (model, provider-pair) per 24h, never auto-switching.

Virtual models

Model	Resolves to
`free/auto`	Best healthy model overall
`free/reasoning` / `free/code` / `free/fast`	Current best candidate per task class
`modelpanel/fusion` (alias `free/fusion`)	Reasoning panel + judge — 95.0% on matched GSM1K
`modelpanel/fusion-fast`	Fast roster (gpt-oss-20b-class) — gated on fast-panel evidence
`modelpanel/fusion-code`	Code roster — gated on livecodebench evidence
`modelpanel/fusion-general`	General-chat roster — gated on general evidence
`modelpanel/fusion/<your-combo>`	Your recipe from `~/.modelpanel/combos.json` — `{members, method, judge}`
`groq/openai/gpt-oss-120b`	Direct provider-id routing

Streaming fallback semantics

Fallback happens before the first token only. Mid-stream failures surface as an error chunk — retrying is the client’s call (documented behavior, not a bug).

Environment variables

Variable	Purpose
`MODELPANEL_HOST` / `MODELPANEL_PORT`	Bind address (default `127.0.0.1:8787`)
`MODELPANEL_REGISTRY_DIR`	Registry directory (default `registry/`)
`MODELPANEL_KEYS_PATH`	Key vault path (default `~/.modelpanel/keys.json`)
`MODELPANEL_<PROVIDER>_API_KEY`	Per-provider key — env wins over the vault file
`OPENAI_BASE_URL`	Point OpenAI SDK apps at the gateway (`http://127.0.0.1:8787/v1`)
`ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_MODEL`	Point Claude Code at the gateway

File layout

File	Purpose
`~/.modelpanel/keys.json`	Key vault (chmod 600, tier flags per key)
`~/.modelpanel/combos.json`	Your fusion recipes — `{members, method, judge}`
`registry/registry.json`	Model catalog (schema v1, hot-reloaded, fail-fast at boot if missing)

Seed the registry on a fresh clone

The gateway fail-fasts at boot without registry/registry.json: mkdir -p registry && cp gateway/test/fixtures/registry.json registry/registry.json.

Security posture

Keys are sent only to the provider that owns them; never logged (redacted), never resold. Prompts are never persisted (in-memory only); logs are metadata (provider, latency, status). The gateway binds 127.0.0.1 by default.

Source of truth for this page: ModelPanel · open-assistants-lab/ModelPanel