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 doctorStart 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.
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.
Print the merged registry view — every probe-verified model with its task class and tier.
Probe summary and recent changelog.
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 |
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) |
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