Copy page

Connect your coding agent

Claude Code

Claude Code

Claude Code speaks the Anthropic Messages API. Hyphen serves that API at /v1/messages, so Claude Code works against the gateway — once you map its model tiers to Hyphen models. That mapping is required; skip it and every request fails. The copy-paste block below does the whole thing.

1. Get a key

app.hyphen-solution.com → sign in → Dashboard → API Keys → Create. Copy the sk-hy-... key.

2. Configure — one copy-paste block

Create or edit ~/.claude/settings.json and paste this. Replace the token with your key; leave the model mappings as-is.

Code
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.hyphen-solution.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-hy-YOUR_KEY",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "m3",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "m3",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "m2.5"
  }
}

That's the entire setup. Restart Claude Code so it re-reads the file, then jump to Verify.

Prefer shell exports?

The same config as environment variables — add to ~/.zshrc or ~/.bashrc:

Code
export ANTHROPIC_BASE_URL="https://api.hyphen-solution.com"
export ANTHROPIC_AUTH_TOKEN="sk-hy-YOUR_KEY"
export ANTHROPIC_DEFAULT_SONNET_MODEL="m3"
export ANTHROPIC_DEFAULT_OPUS_MODEL="m3"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="m2.5"

Then source ~/.zshrc (or open a new terminal) and run claude.

Why the model mappings are required

This is the detail that trips people up, so it's worth 30 seconds.

Claude Code doesn't send a model name like m3. It sends Anthropic model names — claude-sonnet-4-..., claude-opus-4-..., claude-haiku-... — because it's built to talk to Anthropic. The Hyphen gateway does not accept those names; sending one returns:

Code
{ "error": { "message": "Invalid model name", "type": "invalid_request_error" } }

So pointing only ANTHROPIC_BASE_URL at Hyphen is not enough — every request 400s on the model name. The ANTHROPIC_DEFAULT_*_MODEL variables fix this: they tell Claude Code to substitute a real Hyphen model wherever it would otherwise send a claude-* name.

Code
Claude Code wants "claude-sonnet-4"  ──▶  sends "m3" instead   (SONNET → m3)
Claude Code wants "claude-opus-4"    ──▶  sends "m3" instead   (OPUS   → m3)
Claude Code wants "claude-haiku"     ──▶  sends "m2.5" instead (HAIKU  → m2.5)

We map both Sonnet and Opus to m3 (Hyphen's strongest, a reasoning model) so heavy agent work always lands on the best model, and Haiku — Claude Code's lightweight background tier — to m2.5 to keep those calls cheap and fast.

Want a lighter, cheaper default?

Map the Sonnet tier to m2.7 (balanced) instead — day-to-day work gets cheaper, and you can still call the strongest model on demand:

Code
"ANTHROPIC_DEFAULT_SONNET_MODEL": "m2.7",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "m3",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "m2.5"

3. Verify

Code
claude -p "Reply with the single word: connected"

If it prints connected, Claude Code is wired to the gateway and the model mapping is working. (A 400 Invalid model name here means the ANTHROPIC_DEFAULT_*_MODEL variables aren't being read — see below.)

Troubleshooting

• 400 Invalid model name — the model mappings aren't taking effect. Confirm ~/.claude/settings.json is valid JSON (no trailing commas) and that you restarted Claude Code. If you used shell exports, make sure the current terminal actually has them (echo $ANTHROPIC_DEFAULT_SONNET_MODEL).
• 401 Invalid API key — the sk-hy-... token is wrong or unset. Re-copy it from the console and check ANTHROPIC_AUTH_TOKEN.
• 429 — your monthly budget is spent. Claude Code surfaces the reset date; see Rate limits & caps.
• Env var names changed? Flag and env names can shift between Claude Code releases. If a variable seems ignored, check claude --help for the current names in your installed version.
• Settings not applied at all — Claude Code reads ~/.claude/settings.json on startup. Fully quit and relaunch; delete and recreate the file if a stale copy is being picked up.