Use Tokun with Claude Code

Connect Claude Code to Tokun using your API key and a supported model.

Overview

Claude Code connects to Tokun's Anthropic-compatible API. Your Claude Code workflow stays the same, and requests use Tokun's pricing and model routing.

Before you start

A Tokun API key (starts with sk-) from the API keys page.
A funded Tokun balance.
Claude Code, installed and working.
A model ID, such as anthropic/claude-opus-4-8.

Quickstart

Set this up yourself rather than asking the Claude Code session you're running to do it. Claude Code usually declines to change its own base URL and API key, and the change only takes effect in a new session. The steps below take about 30 seconds.

Claude Code reads its provider from environment variables. Set these 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, because the Anthropic SDK adds the path itself. Use https://api.tokun.sh, not https://api.tokun.sh/v1.

Set up with an AI assistant

Paste this prompt into your AI coding agent. It reads the setup guide at /llms.txt and sets up Claude Code for you. You only need to provide your API key.

text

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

Prefer exact, step-by-step instructions? Paste this detailed prompt instead. It sets up 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.

Set up manually

To keep the settings in a file, globally or for one project, 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 IDs

Set ANTHROPIC_MODEL to any Tokun model ID in lab/model format, such as anthropic/claude-opus-4-8 or anthropic/claude-sonnet-4-6. Tokun never substitutes a different model: an unknown ID returns an error.

Official model pools

Official model pools appear in the model catalog and use a pool ID such as flash-pool. Choose an available pool from the live catalog; pool names and members are configured by Tokun administrators.

When the pool enables member selection, use pool-id/member-name, replacing the model's lab prefix with the pool ID. The selected member is the only model that can execute; the pool's pricing mode still applies. When selection is disabled, this form returns 400.

Fixed token pricing uses the pool's input, output, cache and context-tier rates for every member, including a member you select yourself.
Actual model pricing uses the serving member's price, frozen before the request. A retry to another member uses that member's frozen price.
Fixed per-request pricing charges once after an upstream success response begins. Missing usage, a partial response or a client disconnect after that point still counts once. Failures before success and unsuccessful retries do not add charges.

Use a pool that lists the API format this client sends. Model pool settings in the live catalog control which members are shown and whether member selection is available.

Troubleshooting

Two settings differ from what you might expect: ANTHROPIC_BASE_URL has no /v1 suffix, and 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 on the Billing page.
`404 / connection error`	/v1 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, such as anthropic/claude-opus-4-8.
`Old provider still used`	Stale session	Start a new Claude Code session after changing the environment or settings.