# Claude Code on sference

> Run Claude Code against open models on sference: one-command launch with hybrid routing, manual ANTHROPIC_BASE_URL config, model recommendations, and known limits.

Source: https://sference.com/docs/anthropic/claude-code

[Claude Code](https://docs.anthropic.com/en/docs/claude-code) talks to the Anthropic Messages API, and sference [serves that API](https://sference.com/docs/anthropic) for open models. Point it at sference and your agent loop runs on `moonshotai/Kimi-K2.7-Code`, `zai-org/GLM-5.2`, or your own fine-tune, on European GPUs, at open-model token prices, with the same request-level audit trail as the rest of the platform.

> **Set expectations**
>
> This is a compatibility layer, not a drop-in replacement for Claude on hard repo work. Open models plan differently and call tools less reliably than Opus/Sonnet, and Anthropic's cryptographic thinking signatures are not implemented. It is genuinely useful for scripted runs, bulk refactors, cost-sensitive loops, and workloads that must stay in the EU. Read [Known limits](#known-limits) before you commit a workflow to it.

## Fastest path: `sference launch claude`

The [sference CLI](https://sference.com/docs/cli) ships a launcher that configures everything and starts Claude Code for you:

```bash
curl -fsSL https://raw.githubusercontent.com/s-ference/sference/main/install.sh | sh
sference auth login --api-key 'sk_...'
sference launch claude
```

By default this runs in **proxy mode**: a local [mitmproxy](https://mitmproxy.org) forward proxy is started, Claude Code launches with `HTTPS_PROXY` pointed at it, and `ANTHROPIC_BASE_URL` is left unset so Claude Code's first-party detection stays on. The result is **hybrid routing**: sference models appear in Claude Code's `/model` picker and are routed to sference's `/v1/messages`, while real `claude-*` models pass straight through to Anthropic. You can switch between them mid-session.

| Command | What it does |
| --- | --- |
| `sference launch claude` | Start the proxy and launch Claude Code. Catalog models are fetched live from `GET /v1/models`. |
| `sference launch claude --model zai-org/GLM-5.2` | Put one specific model in the picker. |
| `sference launch claude --models a,b` | Put a comma-separated set in the picker. |
| `sference launch claude --dry-run` | Print the proxy config and command without launching. |
| `sference launch claude --proxy-port 8082` | Pin the local proxy port (default: auto-pick). |
| `sference launch claude -- -p "summarize this repo"` | Forward flags after `--` to Claude Code itself. |
| `sference launch claude --no-anthropic` | Skip the proxy; route everything to sference via `ANTHROPIC_BASE_URL`. No hybrid routing, no picker. |

Proxy mode needs `mitmdump` on your `PATH`. The installer adds it; on an existing install, `uv tool install mitmproxy`. If it is missing, the launcher tells you and suggests `--no-anthropic`.

> **About the local CA**
>
> The proxy uses mitmproxy's local CA certificate, scoped to the Claude Code process via `NODE_EXTRA_CA_CERTS`. It is **not** added to your system trust store; only that one process trusts it, only for that session.

Default model: `moonshotai/Kimi-K2.7-Code`. Override with `--model` or the `SFERENCE_MODEL` environment variable.

## Manual configuration

If you would rather not run a proxy, configure Claude Code directly. Everything goes through `ANTHROPIC_BASE_URL`, so all traffic, including `claude-*` model names, hits sference, and the model is whatever you pin.

Add to `~/.claude/settings.json` (or `.claude/settings.json` in a project):

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.sference.com",
    "ANTHROPIC_AUTH_TOKEN": "sk_your_sference_key",
    "ANTHROPIC_MODEL": "moonshotai/Kimi-K2.7-Code"
  }
}
```

- **Prefer `ANTHROPIC_AUTH_TOKEN`** (sent as `Authorization: Bearer`). `ANTHROPIC_API_KEY` also works (sference accepts `x-api-key`), but set one or the other, not both.
- **`ANTHROPIC_MODEL` must be a sference catalog id.** There are no `claude-*` aliases; a Claude model name returns 400. See [Models](https://sference.com/docs/models).
- **Restart Claude Code** after editing settings.

Verify the endpoint independently of Claude Code:

```bash
curl https://api.sference.com/v1/messages \
  -H "Authorization: Bearer $SFERENCE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "moonshotai/Kimi-K2.7-Code",
    "max_tokens": 256,
    "messages": [{ "role": "user", "content": "hi" }]
  }'
```

## Choosing a model

| Model | Why |
| --- | --- |
| `moonshotai/Kimi-K2.7-Code` | The CLI default. Built for agentic coding; strongest multi-turn tool use in the catalog. |
| `zai-org/GLM-5.2` | Strong general coding model, low latency; a good pick when turns are short and interactive. |
| `moonshotai/Kimi-K3` | Largest reasoning model in the catalog; slower and pricier per token, for hard planning turns. |
| Your fine-tune | [Custom models](https://sference.com/docs/custom-models) work on `/v1/messages` like any catalog model. |

Live ids and pricing: `GET https://api.sference.com/v1/models`.

## What to expect

**Two API calls per prompt is normal.** Claude Code fires a separate title-generation request alongside your actual turn: no tools, a `<session>` user body, asking for a JSON title. sference detects it, caps it at 512 completion tokens, and forces reasoning off so it does not burn tokens on chain-of-thought before emitting a title. Seeing two requests per prompt in the console is expected, not a bug.

**Thinking works, signatures do not.** Reasoning models stream `thinking` blocks that Claude Code renders normally, but `signature` is always empty. Multi-turn thinking continuity is best-effort: sference re-injects the inbound thinking text rather than a verified signed block.

**No vision.** Catalog coding models are text-only. Screenshot tools and image attachments are replaced with a placeholder, and sference injects a system notice telling the agent it has no vision so it stops retrying image capture and verifies with `Read`, `grep`, and build output instead. If you specifically need image input, use `Qwen/Qwen3-VL-30B-A3B-Instruct`, but it is not a coding model.

**Tool search may be off.** Claude Code disables tool search on non-Anthropic hosts unless told otherwise. In direct mode, `sference launch claude --no-anthropic --enable-tool-search` sets `ENABLE_TOOL_SEARCH=true` for you.

## Known limits

| Limit | Effect |
| --- | --- |
| Empty thinking `signature` | Multi-turn thinking history degrades; nothing to verify or decrypt. |
| No `redacted_thinking` | Anthropic's encrypted thinking blocks are never produced. |
| `budget_tokens`, `thinking: adaptive`, `effort`, `display` | Accepted and ignored; bound output with `max_tokens`. |
| No prompt-caching controls | `cache_control` blocks are ignored. Prefix caching is automatic; hits show up as `cache_read_input_tokens`. |
| No server-side tools | MCP connectors, web search, code execution, and computer use are Anthropic-hosted and unavailable. Locally-run MCP servers configured in Claude Code work normally. |
| Realtime only | No `service_tier: "flex"`, no background execution on `/v1/messages`. |
| Model-dependent tool reliability | Open models call tools less consistently than Opus/Sonnet on long agent loops. |

The full compatibility surface, covering every supported field, block type, and streaming event, is on the [Anthropic Messages API](https://sference.com/docs/anthropic) page.

## Troubleshooting

**401 Unauthorized.** The key must be a sference `sk_...` key. If both `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` are set, unset one. A stale Anthropic key in your shell profile overriding the sference key is the usual cause.

**400 with an unknown-model message.** `ANTHROPIC_MODEL` is a Claude name, or a catalog id your key is not entitled to. Check `GET /v1/models`.

**402 Payment Required.** The team credit balance is exhausted. Top up in the [console](https://app.sference.com).

**Raw `<tool_call>` or `</think>` text in replies instead of tool calls.** The model emitted tool syntax the parser did not extract, usually because `max_tokens` was too low and the call was truncated mid-JSON. Raise `max_tokens` (Claude Code tool turns need real headroom) or switch to a model with better tool support.

**Slow first token.** Long time-to-first-token on a queued request is normal under load; the stream sends `ping` keepalives while waiting. A request that never completes within the 600s sync window returns 504 and is cancelled server-side.

**504 Gateway Timeout.** A single turn exceeded the sync inference window. Shorten the turn, reduce context, or pick a faster model.

## Related

- [Anthropic Messages API](https://sference.com/docs/anthropic): The endpoint itself: fields, streaming events, tool use, thinking, errors.
- [CLI](https://sference.com/docs/cli): Install, auth, launch, batches, and streams.
- [Models](https://sference.com/docs/models): Catalog ids, pinning, and picking a checkpoint.
- [Custom models](https://sference.com/docs/custom-models): Run your own fine-tune behind the same endpoint.