ModelMeld
Get started

Run the gateway in five minutes.

Self-host the open-source gateway, point your dev tool at it, and you're routing across models on the next request. Pick the path that matches what you already pay for: frontier API keys you hold directly, or a ChatGPT subscription you already use.

1. Install the gateway

ModelMeld ships as a Python package. Python 3.11+ required.

pip install modelmeld
modelmeld serve --host 127.0.0.1 --port 8080

The gateway boots in under a second on a fresh shell. It ships with a bundled routing-data snapshot, so no external services are required to make routing decisions. See docs/self-host.md for Docker + Helm deployment.

2. Pick your auth path

Two ways to give the gateway access to the frontier models it routes to. Pick whichever matches the credentials you already have.

Path A — Bring your own frontier API keys (BYOK)

If you hold direct API keys with Anthropic, OpenAI, or Google, pass them on each request via a custom header. The gateway uses the key to make the upstream call, then forgets it — never stored at rest, never logged.

For Claude Code:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8080
export ANTHROPIC_CUSTOM_HEADERS="x-modelmeld-byok-anthropic: sk-ant-<your-key>"
claude

For Cursor / Aider / Continue / Cline (any OpenAI-compatible tool):

export OPENAI_BASE_URL=http://127.0.0.1:8080/v1
# Pass your frontier key on every request via the BYOK header.
# Cursor / Aider / Continue / Cline all accept custom headers in their
# settings UI — drop in one of:
#   x-modelmeld-byok-anthropic: sk-ant-<your-anthropic-key>
#   x-modelmeld-byok-openai:    sk-<your-openai-key>
#   x-modelmeld-byok-google:    <your-google-api-key>

You can supply multiple BYOK headers at once — the gateway uses whichever one matches the model the router picks for a given request. Per-tool integration guides: claude-code, cursor, aider, continue, cline.

Path B — Use your ChatGPT subscription

If you already pay for a ChatGPT Plus/Pro/Business subscription, ModelMeld can forward requests verbatim using the OAuth bearer the Codex CLI already obtained. Self-host only. Single-user-per-instance. The gateway never persists the token.

First enable the opt-in flag:

export MODELMELD_ALLOW_SUBSCRIPTION_PASSTHROUGH=1
modelmeld serve --host 127.0.0.1 --port 8080

ChatGPT subscription → Codex backend: sign in via the Codex CLI first (it caches the OAuth bearer at ~/.codex/auth.json), then point any OpenAI-compatible client at the gateway with that bearer:

codex login    # opens browser; writes ~/.codex/auth.json

# Then for any /v1/chat/completions client (e.g. simonw/llm-openai-via-codex):
export LLM_OPENAI_BASE_URL=http://127.0.0.1:8080/v1
llm install llm-openai-via-codex
llm -m gpt-5.4 "summarize this readme"

Heads-up: the Codex backend endpoint is undocumented and has no SLA. We forward headers verbatim so upstream sees a request indistinguishable from a direct CLI call, but you're responsible for compliance with your OpenAI subscription terms. Using Anthropic? Anthropic's terms (2026-02-19) restrict OAuth tokens to its own apps, so for Claude use the BYOK API-key path (Path A) — not subscription passthrough. Full setup guide: docs/subscription-passthrough.md.

3. Verify routing took effect

Every response carries audit headers naming the routed model, the task category the scout matched, and the adapter used.

x-modelmeld-routed-model: qwen3-coder-next
x-modelmeld-task-category: coding
x-modelmeld-routed-to: openai
x-modelmeld-quality-threshold: 0.80

For Claude Code, run claude --verbose and grep the response headers. For other tools, your normal HTTP-inspection method works. The routing-hints.md doc explains each header.

4. Pick a routing policy

Three policy aliases set the cost-quality ceiling for a session. Switch between them with your tool's model selector — for Claude Code, /model.

  • →modelmeld-saver — OSS tier only. Predictable cost ceiling; frontier rates never apply. Best for cost-sensitive work.
  • →modelmeld-auto— OSS by default, escalates to frontier only when your prompt contains 2+ reasoning markers ("step by step", "think carefully", etc.). OSS rates on most traffic, frontier on demand.
  • →modelmeld-quality — Frontier-first. Downgrades to OSS only on detected trivial-shape requests (small input, short output, no tools). Best when correctness matters more than cost.

Common gotchas

  • ·Trailing slash on base URL — Anthropic SDK is trailing-slash-sensitive. Use http://127.0.0.1:8080 (no trailing /). 404s are the usual symptom.
  • ·Both auth headers set— Claude Code warns "auth conflict" if both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are set. unset the one you're not using.
  • ·Subscription passthrough returns 403 — you forgot the opt-in flag. Set MODELMELD_ALLOW_SUBSCRIPTION_PASSTHROUGH=1 and restart the gateway.
  • ·BYOK header missing on a frontier route — the gateway returns a 400 naming the exact provider you need to supply (no silent fallthrough). Add the header or stay on -saver.

Where to go from here