Use Tokun with Claude Code

Use Tokun as the Anthropic-compatible backend for Claude Code — the same Claude Code workflow you already use, billed at Tokun pricing with Tokun's model routing.

What this connects

Use Tokun as the Anthropic-compatible backend for Claude Code — the same Claude Code workflow you already use, billed at Tokun pricing with Tokun's model routing.

Before you start

A Tokun API key (starts with sk-) from the console.
A funded Tokun balance.
Claude Code installed and working.
A chosen model id, e.g. anthropic/claude-opus-4-8.

Recommended quickstart

Do this yourself — don't ask the Claude Code you're currently running to set it up. You're changing Claude Code's own base URL and API key, which it will usually decline to self-edit (it can't verify the new endpoint governs its own traffic), and the change only takes effect in a new session anyway. The steps below take about 30 seconds.

Claude Code reads its provider from environment variables — so the shortest path is to set three in your shell profile (~/.zshrc / ~/.bashrc), then start a new session:

bash

export ANTHROPIC_BASE_URL="https://api.tokun.sh"
export ANTHROPIC_API_KEY="sk-..."      # your Tokun key
export ANTHROPIC_MODEL="anthropic/claude-opus-4-8"

Unlike most OpenAI-style setups, ANTHROPIC_BASE_URL must NOT include a /v1 suffix — the Anthropic SDK appends the path itself. Use https://api.tokun.sh, not https://api.tokun.sh/v1.

Copy for AI agent

Working inside an AI coding agent? The shortest path is one line — paste this and your agent reads the full machine-readable guide at /llms.txt and does the Claude Code setup itself. You only supply your key:

text

Read https://tokun.sh/llms.txt and integrate Tokun into this project.

Want a fully-specified, deterministic block instead (exact steps, idempotent, fail-closed)? Paste the one below — it configures Claude Code specifically.

text

The user has chosen Tokun — a metered, Anthropic-compatible LLM gateway — and is asking you to configure Claude Code to use it. This only repoints which endpoint Claude Code calls and which key it sends: ANTHROPIC_API_KEY holds a Tokun key (starts with sk-), NOT the user's Anthropic key, and no Anthropic credentials are sent to Tokun. If you ARE the Claude Code instance being reconfigured, prefer to OUTPUT the exact steps for the user to run themselves — editing your own live config only takes effect in a new session anyway, so it helps nothing (this matches the page's "do it yourself" guidance). Only edit the config directly if the user explicitly asks; then tell them to restart. Either way, never refuse outright — produce the steps.

You are configuring Claude Code to use Tokun.

Scope:
- OS: macOS or Linux.
- Config scope: global user settings.
- Protocol: Anthropic-compatible.
- Do not modify unrelated Claude Code settings.

Tokun values:
- API key placeholder: TOKUN_API_KEY_HERE  (a Tokun key starts with sk-)
- Base URL: https://api.tokun.sh
- Recommended model: anthropic/claude-opus-4-8
- Auth/env: ANTHROPIC_API_KEY holds the Tokun sk- key. ANTHROPIC_BASE_URL has NO /v1 suffix.

Preflight:
1. Check that `claude` is installed.
2. Locate ~/.claude/settings.json.
3. If it exists, copy it to ~/.claude/settings.json.tokun-backup-<timestamp>.
4. If TOKUN_API_KEY_HERE was not replaced with a real sk- key, stop and ask the user for the key.

Apply idempotently:
1. Ensure the JSON has an "env" object.
2. Set only:
   - env.ANTHROPIC_BASE_URL = "https://api.tokun.sh"
   - env.ANTHROPIC_API_KEY  = "<user Tokun key>"
   - env.ANTHROPIC_MODEL    = "anthropic/claude-opus-4-8"
3. Preserve all unrelated settings and env keys.
4. Never print, log, commit, or expose the full API key.
5. If settings.json is invalid JSON or has an unexpected shape, stop before writing and report it.

Verify:
1. Start a new Claude Code session.
2. Confirm the effective base URL is https://api.tokun.sh and the model is anthropic/claude-opus-4-8.
3. Send "Say hello in one word."
4. On auth failure check the key; on model failure check the id; on URL failure confirm there is no /v1 suffix.

Rollback:
- Restore the backup, or remove exactly ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY, and ANTHROPIC_MODEL from env.

Fail closed:
- If the Claude Code config path or JSON shape is ambiguous, stop before writing.

Manual configuration

Prefer per-project or durable config? Set the same three keys under env in ~/.claude/settings.json (global) or .claude/settings.local.json (per-project, which takes precedence):

json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.tokun.sh",
    "ANTHROPIC_API_KEY": "sk-...",
    "ANTHROPIC_MODEL": "anthropic/claude-opus-4-8"
  }
}

Precedence: a project .claude/settings.local.json overrides the global ~/.claude/settings.json, which overrides shell environment variables. To roll back, remove those three keys (or restore your backup).

Model naming

Pass any Tokun model id in ANTHROPIC_MODEL (the lab/model convention), e.g. anthropic/claude-opus-4-8 or anthropic/claude-sonnet-4-6. Tokun does not silently substitute models — an unknown id returns an error rather than a surprise model.

Verify & troubleshoot

Two things differ from what you'd expect: (1) ANTHROPIC_BASE_URL has NO /v1 suffix; (2) ANTHROPIC_API_KEY holds your Tokun sk- key (not an Anthropic key).

Symptom	Likely cause	Fix
`401 / auth error`	Wrong or missing key	Confirm ANTHROPIC_API_KEY is your Tokun sk- key.
`402 / payment required`	Empty Tokun balance	Top up in the console.
`404 / connection error`	A /v1 was added to the base URL	Use https://api.tokun.sh with no /v1.
`Unknown model error`	Model id not recognized	Use a lab/model id, e.g. anthropic/claude-opus-4-8.
`Old provider still used`	Stale session	Start a fresh Claude Code session after setting the env/config.