Anthropic builds the Claude model family. Apus supports two auth routes:

• API key - Anthropic API access with usage-based billing
• Claude CLI - reuse an existing Claude Code login through the installed executable on the same host

Choose a model route

The model picker shows each Claude model once per route. API and Claude CLI are not interchangeable billing choices: anthropic/* is the canonical model identity and can run through either runtime; claude-cli/* selects the native Claude runtime explicitly. When a configured anthropic/* model already runs through Claude CLI, the picker omits its matching claude-cli/* entry, unless the agent's model policy or a Gateway role allows that claude-cli/* entry but not the anthropic/* one.

• API / API · Apus uses the configured Anthropic API connection.
• Claude CLI / Claude CLI · native runs through Claude Code, using its native login or a selected saved account.
• Configured route means the picker does not have a resolved runtime to show. The provider name alone is not proof of API or subscription billing. An Anthropic Default row also uses this label when it will clear a pinned session runtime: the current session route does not describe the configured route being restored.

The web picker shows route details on hover or keyboard focus. Telegram /models shows route guidance before selection and labels models when their runtime is known. Model IDs and explicit runtime choices remain unchanged.

Check the selected account as well as the runtime. An API key explicitly selected for Claude CLI still uses separate API billing. A Claude CLI selection does not silently switch to the direct API if the executable cannot run.

Claude Haiku 5.5

Select anthropic/claude-haiku-5-5 for API access or claude-cli/claude-haiku-5-5 for an existing Claude Code login. The haiku alias and Anthropic's default utility model use Haiku 5.5; explicit Haiku 4.5 refs remain available.

Haiku 5.5 supports text and image input, a 1M context window, and up to 128K output tokens. Thinking defaults to adaptive at medium effort. Available levels are off, low, medium, high, xhigh, and max; minimal maps to low. Apus omits unsupported sampling parameters and preserves signed thinking for same-model replay. It does not enable native fast mode, Priority Tier, or server-side fallback for this model.

API pricing is $0.10 / $0.50 per million input / output tokens for prompts up to 100K tokens and $0.50 / $2.50 above that threshold. Cache reads and writes use the corresponding tier. Claude CLI retains subscription accounting. See Anthropic's Haiku 5.5 migration guide for the new tokenizer and account-bound thinking requirements.

Usage and cost tracking

Apus detects the available Anthropic credential and selects the matching usage surface:

• Apus-managed subscription/setup credentials show quota windows and optional extra-usage budget.
• Native Claude CLI logins stay under Claude's exclusive refresh control, so Apus does not poll their quota endpoint.
• ANTHROPIC_ADMIN_KEY or ANTHROPIC_ADMIN_API_KEY shows 30 days of provider-reported organization cost and Messages API usage in Control UI Usage, including daily spend, token/cache totals, top models, and cost categories.
• An sk-ant-admin... credential stored in the Anthropic provider profile is detected as an Admin API key automatically.

Admin API cost history comes from Anthropic's Usage and Cost API. It is actual provider billing, separate from Apus's session-derived estimated cost.

Getting started

**Best for:** standard API access and usage-based billing.

    Create an API key in the [Anthropic Console](https://console.anthropic.com/).

    ```bash
    apus onboard
    # choose: Anthropic API key
    ```

    Or pass the key directly:

    ```bash
    apus onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
    ```

    ```bash
    apus models list --provider anthropic
    ```

### Config example

```json5
{
  env: { vars: { ANTHROPIC_API_KEY: "example-anthropic-key-not-real" } },
  agents: { defaults: { model: { primary: "anthropic/claude-opus-5" } } },
}
```

**Best for:** reusing an existing Claude CLI login without a separate API key.

    Apus communicates directly with the installed Claude Code executable.
    Verify that Claude Code is installed and up to date:

    ```bash
    claude --version
    claude auth status --text
    ```

    If Claude is not logged in, authenticate once as the Gateway user:

    ```bash
    claude auth login
    ```

    If the installed build is incompatible, update Claude Code and restart
    Apus so the gateway launches the new binary:

    ```bash
    claude update
    ```

    ```bash
    apus onboard
    # choose: Claude CLI
    ```

    Normal agent turns use the installed, authenticated Claude Code executable
    through Apus's direct CLI transport. Apus uses a non-secret route
    marker and never reads, persists, refreshes, selects, or forwards the
    native login tokens. Claude owns the login and token refresh lifecycle.
    Gateway startup shares the native login availability check across agent
    workspaces using the same config and environment. Explicit catalog/auth
    captures recheck availability for their own generation. Model lists also
    recheck it in the background at most once a minute, so `claude auth login`
    or logout after Gateway startup reaches the model picker without a restart.
    New sessions select saved subscription credentials by account order and
    use protected file-descriptor forwarding, including tokens saved with
    `apus models auth paste-token --provider anthropic`. API keys saved for
    the `anthropic` provider require an explicit account selection for CLI
    forwarding. Existing sessions keep their account until you select another
    or remove its saved profile. Native-tool approvals remain under Apus
    control. Schema-valid native calls pass through Apus's canonical
    tool policy before native approval. Isolated side-question completions
    and paired-node execution retain the supervised CLI path.

    Consecutive agent turns reuse the same warm Claude Code subprocess
    when their authenticated session and execution policy
    match. If that process ends or the gateway restarts, the next turn
    resumes the persisted Claude Code session.

    An explicit Claude CLI model selection stays on that runtime across resumed
    turns. If the executable cannot run, the selection fails instead of switching
    to direct Anthropic API access. Selecting an API route or forwarding an API
    key through an explicit account selection remains a separate billing choice.

    ```bash
    apus models list --provider anthropic
    ```

Setup and runtime details for the Claude CLI backend are in [CLI Backends](/gateway/cli-backends).

You can also sign in from Control UI: **Settings → Models → Provider access →
Anthropic → Add account** runs `claude auth login` for a new Claude Code
config folder under the Gateway state directory and records it as a Claude
Code account. Claude Code still owns the login and its refresh; Apus never
stores the tokens. The card shows each account's email, plan, and status.

Claude CLI reuse expects the Apus process to run on the same host as the
Claude CLI login. Docker installs can persist a container home and log in to
Claude Code there; see
[Claude CLI backend in Docker](/install/docker#claude-cli-backend-in-docker).
Other container installs such as [Podman](/install/podman) do not mount host
`~/.claude` into setup or runtime; use an Anthropic API key there, or choose
a provider with Apus-managed OAuth such as
[OpenAI Codex](/providers/openai).

### Get a setup token

Run `claude setup-token` on any machine with Claude Code installed. It prints
a long-lived token starting with `sk-ant-oat01-`.

During onboarding, paste the token in the macOS app by choosing
**Anthropic setup-token** under **Connect with an API key or token**, or use:

```bash
apus models auth login --provider anthropic --method setup-token
```

Direct Messages API requests using a setup token advertise a maintained
Claude Code client version, or the installed CLI version when newer.
Anthropic uses that identity to gate newer models. A missing, older, or
failed CLI check uses Apus's maintained version floor. Discovery is
shared with the CLI backend and cached until process restart; API-key
requests do not run the check.

### Config example

Prefer the canonical Anthropic model ref plus a CLI runtime override:

```json5
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-5" },
      models: {
        "anthropic/claude-opus-5": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}
```

Legacy `claude-cli/claude-opus-4-7` model refs still work for
compatibility, but new config should keep provider/model selection as
`anthropic/*` and put the execution backend in provider/model runtime policy.

### Billing and `claude -p`

Anthropic currently treats Agent SDK and non-interactive CLI invocations as
programmatic usage:

- Anthropic's June 15, 2026 support update paused the previously announced
  separate Agent SDK credit plan.
- Subscription-plan Claude Agent SDK, `claude -p`, and third-party app usage
  still draw from the signed-in subscription's usage limits.
- The previously announced monthly Agent SDK credit is not available while
  Anthropic revises that plan.
- Console/API-key logins use pay-as-you-go API billing and do not receive
  the subscription Agent SDK credit.

Anthropic can change Claude Code billing and rate-limit behavior without an
Apus release. Check `claude auth status`, `/status`, and
Anthropic's linked docs when billing predictability matters.

For shared production automation, use an Anthropic API key instead of
Claude CLI. Apus also supports subscription-style options from
[OpenAI Codex](/providers/openai), [Qwen Cloud](/providers/qwen),
[MiniMax](/providers/minimax), and [Z.AI / GLM](/providers/zai).

Use Claude Opus 5.5

After setting up either auth route above, select the canonical model ref:

apus models set anthropic/claude-opus-5-5

The bare opus alias and explicit aliases opus-5.5 / opus-5-5 select this model. Fresh API and Claude CLI setup defaults to Opus 5.5; existing version-pinned models and authored aliases remain unchanged.

For Claude CLI authentication, keep the canonical ref and select the CLI runtime:

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-5-5" },
      models: {
        "anthropic/claude-opus-5-5": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}

The API and Claude CLI catalogs expose a 1,000,000-token context window and 128,000-token output limit. API pricing is $4/$20 per million input/output tokens, with $0.20 cache reads and $5 five-minute cache writes. See Anthropic's Opus 5.5 specifications.

Opus 5.5 always uses adaptive thinking. Apus defaults to medium and offers low, medium, high, xhigh, and max. Stored off and minimal settings map to low; stored adaptive uses the medium default. Use /think low to reduce thinking effort. Apus omits manual thinking budgets, custom sampling parameters, assistant prefills, and Priority Tier.

Forced tool choices become auto; state in the prompt when a particular tool must run. Opus 5.5 also binds retained thinking to its conversation prefix. Apus applies the append-only context and retained-thinking repair described under Tool calls and retained thinking. See Anthropic's migration guide for model-switching and response-shape changes.

Use Claude Sonnet 5.5

After setting up either auth route above, select the canonical model ref:

apus models set anthropic/claude-sonnet-5-5

The bare sonnet alias and explicit aliases sonnet-5.5 / sonnet-5-5 select this model. Fresh API and Claude CLI setup still defaults to Opus 5.5; select Sonnet 5.5 explicitly. Existing version-pinned models and authored aliases remain unchanged. Use sonnet-5 to keep Sonnet 5.

For Claude CLI authentication, keep the canonical ref and select the CLI runtime:

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-5-5" },
      models: {
        "anthropic/claude-sonnet-5-5": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}

The API and Claude CLI catalogs expose a 1,000,000-token context window and 128,000-token output limit. Sonnet 5.5 supports image and PDF input. API pricing is $2/$10 per million input/output tokens, with $0.20 cache reads and $2.50 five-minute cache writes, the same rates as Sonnet 5. See Anthropic's Sonnet 5.5 specifications.

Sonnet 5.5 uses adaptive thinking at high effort by default. Apus offers off, low, medium, high, xhigh, and max. /think off sends Anthropic's between_tools setting: it disables up-front thinking, while notes between tool calls still return as ordinary text. New /think minimal and /think adaptive directives are rejected with the supported choices; stored minimal maps to low, and stored adaptive uses the high default. Use /think default to restore that default. Apus omits manual thinking budgets, custom sampling parameters, and assistant prefills. Sonnet 5.5 supports neither native fast mode nor Priority Tier.

Forced tool choices become auto, including with /think off; state in the prompt when a particular tool must run. Sonnet 5.5 binds retained thinking to its conversation prefix. Apus applies the append-only context and retained-thinking repair described under Tool calls and retained thinking. A session moving onto Sonnet 5.5 keeps reasoning from Sonnet 5 or Claude 4.x models, but not from Opus 5, Opus 5.5, Fable, or Mythos. No other model reads Sonnet 5.5 reasoning. Direct API-key requests opt into Anthropic's safety fallback to Sonnet 5 for cyber and frontier_llm declines, at the same price. See Anthropic's migration guide for model-switching and response-shape changes.

Use Claude Fable 5.1

After setting up either auth route above, select the canonical model ref:

apus models set anthropic/claude-fable-5-1

For Claude CLI authentication, keep that same ref and select the CLI runtime:

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-fable-5-1" },
      models: {
        "anthropic/claude-fable-5-1": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}

The API and Claude CLI catalogs expose a 1,000,000-token context window and 128,000-token output limit. Fable 5.1 always uses adaptive thinking. Apus defaults to medium, with native low, medium, high, xhigh, and max effort available. For API-key billing, input and output remain $10/$50 per million tokens; cache reads cost $0.25 per million tokens, one quarter of Fable 5's rate. See Anthropic's Fable 5.1 specifications.

The bare fable alias now selects anthropic/claude-fable-5-1. Explicit fable-5 and anthropic/claude-fable-5 selections still use Fable 5; Apus does not rewrite them to Fable 5.1.

Tool calls and retained thinking

Fable 5.1 accepts automatic or disabled tool use, not forced tool calls. Apus's Anthropic adapter converts a forced tool choice to auto when thinking is enabled. State in the prompt when a particular tool must run; see Anthropic's migration guide.

Fable 5.1 binds retained thinking to the preceding system prompt, tools, and conversation history. Changing that prefix can invalidate later thinking blocks. On direct Anthropic API-key Messages routes, Apus enables inHistorySystemUpdates for Opus 4.8, Opus 5/5.5, Sonnet 5/5.5, Fable 5/5.1, and Mythos 5/5.1. It pins the complete system prompt and appends changed, added, or removed prompt sections as system messages after the current user turn. Workspace instructions, skills, and permission changes therefore preserve the earlier prefix. Changing the provider, model, transport, or selected personal profile, or compacting the session, starts a new prefix series. After a Gateway restart, the saved series continues and any refreshed sections arrive as appended updates. Dynamic suffix changes use the same update path.

These routes also keep runtime context append-only as turn-scoped system messages, without user-message delimiters. Apus sends clear_at: "next_user_message" with the mid-conversation-system-clear-at-2026-08-21 beta: earlier carriers stay in the transcript but consume no input tokens after the next user message. Persistent prompt updates need no beta header. Operator system messages follow all other context for their user turn, including tool results. When replay excludes a Talk consult prompt, Apus inserts a neutral user anchor (.) before any stranded system updates. This preserves their content, order, and lifetime without changing the pinned system prompt. Tool results and queued extension context also clear turn-scoped messages, so Apus renews the current user turn's runtime context after those continuations.

OAuth, proxies, Bedrock, Vertex, and Foundry keep their existing behavior. Prefix-binding models such as Fable 5.1, Opus 5.5, and Sonnet 5.5 retain hidden user-role runtime-context carriers and inline inbound metadata, preserving consecutive user turns on the Messages API; Bedrock Converse still merges consecutive user turns. Those carriers contain the delimited context body, with interpretation guidance once in the stable system prompt. Routes without either capability keep transient carriers and normal user-turn merging. Transient carriers remain the cheaper shape on routes without in-history system updates when thinking does not bind the prefix: old carriers consume no later context or repeated cache-read charges.

Direct Anthropic API-key requests with adaptive thinking send the thinking-binding-controls-2026-08-01 beta and thinking.block_binding.prefix_mismatch_behavior: "drop_block". Anthropic drops invalidated replayed thinking server-side, and Apus logs a warning with the count and up to five affected paths. These controls are not sent for OAuth, proxies, Bedrock, Vertex, Foundry, or budget-based, disabled, or between_tools thinking. Client-side compaction removes stale thinking signatures; a provider-confirmed thinking rejection can still trigger one retry without prior thinking and persist the successful repair. Adaptive mode remains enabled, but a response may contain no thinking block. Integrations that build Messages API requests directly should follow Anthropic's preserved-thinking rules.

With contextPruning.mode: "cache-ttl", direct Anthropic API-key requests use server-side tool-result clearing. Anthropic's server-side clearing and compaction never invalidate Fable 5.1 thinking: the prefix check uses the history sent by the client, before those server edits. See Anthropic's context-editing contract. On other eligible routes, a client-side prune is a one-time prefix edit. Apus retains that projection for later requests, so pruning does not flip back to the original bytes and invalidate newly created thinking. Earlier thinking affected by a client-side edit is handled by drop_block where the binding controls above apply, or by the existing rejection-and-repair path elsewhere.

Fable 5.1 thinking is also bound to the model that produced it. Switching a session from Fable 5.1 to any other model (Opus 5.5, Opus 5, Sonnet 5.5, Sonnet 5, Fable 5, or older) continues the visible conversation without Fable's earlier reasoning; Anthropic drops those blocks unbilled, and Apus's embedded runtime omits them from the replay for the same result. The reverse move keeps compatible reasoning: Fable 5.1 reads thinking produced by Opus 5, Sonnet 5, Opus 4.8, and Fable 5, so a session that moves onto Fable 5.1 replays that history intact. It cannot read Sonnet 5.5 reasoning. Switching away and back does not restore the pre-switch Fable reasoning: the switch changes the system prompt, which invalidates every earlier Fable block. On direct API-key routes Anthropic drops those blocks server-side and Apus logs the drop; elsewhere, organizations that enforce the prefix check reject the request once and the embedded runtime retries without prior thinking. Changing the thinking level with /think has the same effect. Pick the model and thinking level when you start the session when reasoning continuity matters.

Sonnet 5.5 preserves prior Sonnet 5 and Claude 4.x reasoning when a session moves onto it, but drops reasoning from Opus 5, Opus 5.5, Fable, and Mythos. Switching away from Sonnet 5.5 drops its reasoning on every other model.

Claude sessions across computers

The bundled Anthropic plugin adds a Claude Code group to the normal sessions sidebar. Rows open in the normal Chat pane. It discovers non-archived Claude Code sessions on the Gateway and on connected node hosts:

• Claude CLI sessions come from valid project-index records. For unindexed transcripts, a bounded metadata fallback recognizes concurrent non-sidechain interactive (cli) and headless Agent SDK CLI (sdk-cli) sessions under ~/.claude/projects/. Gateway-side discovery also recognizes bidirectional stream-json (sdk-ts) sessions; the native macOS node reader does not.
• Claude Desktop sessions use the Desktop title, activity time, and archive state when its metadata points to the same Claude Code session ID.
• A CLI-only session has no archive flag, so it remains visible while its transcript is present.

Claude Code /rename titles take precedence over automatic titles and the first prompt. /color imports the matching session color; cleared or unrecognized colors stay unset. Discovery reads a bounded transcript prefix and tail, so recent metadata appended to large transcripts is included without reading the entire history. Metadata outside those windows may be unavailable. Desktop rows retain their Desktop title and remain colorless.

Routine discovery reads at most 64 MiB of transcript metadata across 10,000 files. If it reaches either limit, the final discovered page reports DISCOVERY_TRUNCATED instead of claiming the inventory is complete. Search by an exact session ID to look up matching transcripts independently of that frontier; reading, continuing, and opening a known session in a terminal use the same bounded lookup. Per-file metadata windows and normal path, sidechain, and archive checks still apply.

No additional Apus config is required for discovery. The Anthropic plugin is bundled and enabled by default; a native macOS node advertises the read-only Claude session commands when the local Claude projects directory exists ($CLAUDE_CONFIG_DIR/projects/ when CLAUDE_CONFIG_DIR is set, otherwise ~/.claude/projects/, matching Gateway-side discovery). Approve the node pairing upgrade when those commands first appear.

The sidebar groups rows by their Gateway or paired-node host and shows each host's newest bounded page as soon as that computer answers. It reconciles again after host-connectivity changes, when the page regains focus, and at most every 30 seconds while visible, so Claude sessions created outside Apus appear without a reload. A changed catalog gets a faster follow-up pass. Use Load more sessions below a catalog group to append the next page for every host that has more history; appended rows stay visible and are re-fetched to the same depth across refreshes. Catalog clients use sessions.catalog.list; opening a row uses sessions.catalog.read.

Those refreshes are cheap on the Gateway: the plugin watches ~/.claude/projects/ and the Desktop session store for changes instead of re-reading them on every poll, so an unchanged tree costs no disk access and a change re-reads only the affected project directory. It re-reads the whole tree at most every five minutes as a backstop, and falls back to per-request scanning if the platform cannot provide a file watcher. Desktop metadata also refreshes every 60 seconds to pick up custom-group changes outside the watched session store. Desktop metadata caching keeps only bounded catalog fields and PR summaries; unused MCP configurations and launch snapshots are discarded after each read. Gateway enumeration keeps each caller isolated; the plugin reuses its watched filesystem snapshot across those enumerations.

Catalog visibility follows the authenticated Gateway profile. Admin connections see every discovered Claude row, and solo or shared-secret Gateways remain unfiltered. On a multi-user Gateway, a non-admin sees only rows already adopted by their durable profile; unattributed host-discovered Claude CLI and Desktop rows stay hidden. This is a privacy control within one trusted Gateway domain; see Multi-user mode.

Terminal takeover resolves claude from the owning host user's login-shell PATH before the service/daemon PATH. This keeps app-launched sessions aligned with the Claude CLI the operator gets in a normal terminal.

Selecting a row reads the newest transcript page first. Load older transcript items follows an opaque byte cursor and reads another bounded section from the JSONL file instead of loading the entire history. Normal user, assistant, reasoning, tool-call, and tool-result content is preserved. An individual item larger than the node/Gateway safety ceiling is clearly marked as truncated.

For a Gateway-local claude-cli row, typing in the normal composer calls sessions.catalog.continue. Apus re-resolves the local catalog record, creates or reuses a model-locked native session, imports at most 200 visible items or 512 KiB, and seeds the Claude CLI binding. The first turn resumes with --fork-session; Claude assigns the fork a new session ID, so later turns use the fork and the source session stays untouched.

The new Apus session starts with the catalog title and color. Continuing an already adopted session preserves any title or color changes made in Apus.

A headless node host can also make its Claude CLI rows continuable by enabling the node-local setting below and restarting the node host:

{
  nodeHost: {
    agentRuns: {
      claude: { enabled: true },
    },
  },
}

The node advertises agent.cli.claude.run.v1 only when the setting is enabled and its local claude executable resolves. Apus re-resolves the catalog record on that node, imports the same bounded history, and binds the adopted session to the node and catalog-reported working directory. Each turn runs the node's real claude -p process using that node's Claude files and login. The node's exec approval policy still applies; the Gateway cannot force the opt-in.

Node continuation v1 is one-shot only. It omits Gateway loopback MCP config and Gateway skills plugin arguments, does not reseed from a Gateway transcript, and rejects attachments and images. Claude Desktop rows remain view-only. Native macOS app nodes also remain view-only until the app advertises the run command.

See Nodes: Claude sessions and transcripts for the node command and security boundary.

Live model discovery

With an Anthropic API key configured, Apus refreshes the Claude catalog from Anthropic's models endpoint, so newly published models appear without an Apus release. Models the shipped catalog already describes keep their published metadata and pricing.

Each listed row carries the thinking and effort capabilities Anthropic advertises for it (adaptive thinking, whether thinking can be disabled, and xhigh/max effort) as params.claudeCapabilities on the catalog row. Request shaping and the offered thinking levels follow those capabilities, so a new model gets the request shape it accepts on its first turn. Rows without them (shipped models absent from the listing, configured rows, and catalogs saved before discovery ran) keep Apus's model-id rules. An unknown model whose listing carries no capability data stays hidden. Discovery is advisory: without an API key, or if the endpoint is unreachable, the shipped catalog is used unchanged.

anthropic/claude-sonnet-5 uses the same adaptive-thinking defaults and request restrictions. The catalog uses Anthropic's standard $2/$10 input/output pricing per million tokens. Anthropic canceled the previously scheduled September 2026 increase; see current model pricing.

anthropic/claude-fable-5-1 and anthropic/claude-fable-5 always use adaptive thinking. Apus defaults both versions to medium effort. Anthropic does not allow thinking to be disabled for these models, so stored off and minimal settings map to low effort instead. Apus also omits caller-selected sampling parameters for both Fable versions.

Fable effort controls offer low, medium, high, xhigh, and max, matching Anthropic's effort levels. Adaptive thinking is always on; it is not a separate effort choice. Existing stored adaptive selections resolve to Apus's medium default. Custom anthropic-messages providers use the same profile, including model IDs with routing namespaces such as Claude Gateway/claude-fable-5-1.

anthropic/claude-mythos-5 is a limited-access model with the same always-on adaptive-thinking and five-effort contract. Apus defaults to high, maps stored off and minimal settings to low, and omits caller-selected sampling parameters. The catalog publishes its 1,000,000-token context window, 128,000-token output limit, image input, and $10/$50 input/output pricing.

For Opus 5.5, Sonnet 5.5, Fable, and Mythos, new /think minimal and /think adaptive directives are rejected with the supported choices. Use /think low in place of minimal, and /think default to use the model's default effort. The remapping above applies to previously stored settings.

Claude Opus 4.8 keeps thinking off by default in Apus. When you explicitly enable adaptive thinking with /think high|xhigh|max, Apus sends Anthropic's Opus 4.8 effort values; Claude 4.6 models (Opus 4.6 and Sonnet 4.6) default to adaptive.

Override per-message with /think:<level> or in model params:

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-5": {
          params: { thinking: "high" },
        },
      },
    },
  },
}

1. For every direct API-key request to anthropic/claude-opus-5-5, anthropic/claude-opus-5, anthropic/claude-sonnet-5-5, anthropic/claude-fable-5-1, or anthropic/claude-fable-5, Apus sends the server-side-fallback-2026-07-01 beta header plus fallbacks: "default". Anthropic selects the recommended model for the reported refusal category. Sonnet 5.5 falls back to Sonnet 5 for cyber and frontier_llm declines.
2. Only a safety-classifier decline triggers the fallback. Rate limits, overloads, and server errors behave exactly as before and go through Apus's normal model failover.
3. The rescue happens inside the same call. A decline before any output is invisible apart from latency; the whole answer comes from the serving model. On a mid-stream decline the partial text is kept as the prefix the fallback model continues from, while the declined model's reasoning and tool calls are discarded per Anthropic's replay rules (they must not be echoed back or executed).
4. If the recommended model declines as well, the turn surfaces the refusal as an error. Apus does not retry a final refusal or advance to another configured model.

The fallback happens at the Anthropic API level, so the serving model does not need to be in your configured Apus fallback chain.

Observability and billing

• A fallback-served turn records a provider_fallback diagnostic on the assistant message naming fromModel and toModel, and the message's responseModel reports the model that answered.
• Anthropic bills the fallback attempt at the serving model's rates. Apus prices known Opus 4.8 fallback-served turns at Opus 4.8 rates. Sonnet 5.5 fallback-served turns on Sonnet 5 keep the requested cost because their rates are identical.
• A mid-stream decline additionally bills the already-streamed primary-model partial on Anthropic's side; that portion is reported in the API's per-attempt usage but not folded into Apus's per-turn estimate.

Scope

Applies to anthropic/claude-opus-5-5, anthropic/claude-opus-5, anthropic/claude-sonnet-5-5, anthropic/claude-fable-5-1, and anthropic/claude-fable-5 with API-key auth against api.anthropic.com. OAuth (including Claude CLI subscription reuse), proxy base URLs, Bedrock, Vertex, and Foundry requests are unchanged and still surface refusals as errors there.

See Anthropic's refusals and fallback guide for the underlying behavior.

Prompt caching

Apus supports Anthropic's prompt caching feature for API-key auth.

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" },
        },
      },
    },
  },
}

Use model-level params as your baseline, then override specific agents via `agents.entries.*.params`:

```json5
{
  agents: {
    ownership: "explicit",
    defaults: {
      heartbeat: { agentId: "research" },
      systemAgent: { agentId: "research" },
      authInheritance: { agentId: "research" },
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" },
        },
      },
    },
    entries: {
      research: { workspace: "~/.apus/workspace" },
      alerts: { params: { cacheRetention: "none" } },
    },
  },
  talk: { agentId: "research" },
}
```

Config merge order:

1. `agents.defaults.models["provider/model"].params`
2. `agents.entries.*.params` (matching `id`, overrides by key)

This lets one agent keep a long-lived cache while another agent on the same model disables caching for bursty/low-reuse traffic.

- Anthropic Claude models on Bedrock (`amazon-bedrock/*anthropic.claude*`) accept `cacheRetention` pass-through when configured.
- Supported Nova models offer opt-in explicit caching: set `cacheRetention` explicitly to `short` or `long` for system/message checkpoints with a five-minute TTL. Unset retention adds no checkpoints. Nova explicit caching has not been live-verified against AWS by Apus maintainers yet. Other non-Claude models remain at `cacheRetention: "none"`; see [Bedrock prompt caching](/reference/prompt-caching#amazon-bedrock) for model IDs, AWS limits, and the live acceptance proof gap.
- API-key smart defaults also seed `cacheRetention: "short"` for Claude-on-Bedrock refs when no explicit value is set.

Advanced configuration

For Claude Opus 5.5, Opus 5, and Opus 4.8, Apus's shared `/fast` toggle uses
Anthropic's native fast mode for direct API-key traffic to `api.anthropic.com`.

| Command | Maps to |
| --- | --- |
| `/fast on` | `speed: "fast"` plus `fast-mode-2026-02-01` |
| `/fast off` | Standard speed; no `speed` field |

```json5
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-5": {
          params: { fastMode: true },
        },
      },
    },
  },
}
```

- Native fast mode is a research preview with up to 2.5x higher output-token throughput. It is billed at `$8/$40` per million input/output tokens for Opus 5.5 and `$10/$50` for Opus 5 and Opus 4.8. Apus applies the same 2x multiplier to cache pricing in its cost estimate.
- Native fast mode only applies to direct `api.anthropic.com` requests made with an API key. OAuth/subscription-token requests, Claude CLI, proxies, Bedrock, Vertex, and Foundry never receive the beta or `speed` field.
- Accounts need fast-mode access and a non-zero fast-mode rate limit. Anthropic returns a fast-specific `429` when the separate fast quota is exhausted or zero.
- For other direct Anthropic models, `/fast` retains the existing Priority Tier mapping: on uses `service_tier: "auto"` and off uses `service_tier: "standard_only"`.
- Explicit `serviceTier` or `service_tier` params override `/fast` when both are set.
- Claude Sonnet 5.5 and Sonnet 5 support neither native fast mode nor Priority Tier, so Apus omits both fields.
- The Control UI disables confirmed no-op Fast choices, including Sonnet 5.5, Sonnet 5, and requests governed by an explicit service tier. Saved Fast preferences remain clearable; unknown route or auth facts preserve existing controls.

Anthropic server-side compaction is opt-in. For supported `anthropic/*`
models using API-key auth directly against `api.anthropic.com`, enable it
per model:

```json5
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-6": {
          params: { anthropicServerCompaction: true },
        },
      },
    },
  },
}
```

Apus adds the `compact-2026-01-12` beta header and sends an Anthropic
`context_management` compaction edit. When compaction occurs, Apus
assembles the streamed summary and stores it with the provider's opaque
compaction metadata as hidden replay state. Both survive session reopening
and are sent first on the next matching request. Summary text still passes
through transcript redaction; opaque metadata is preserved for replay.
The full transcript remains local;
only the outbound history before the checkpoint is omitted.
If Anthropic rejects a stored checkpoint, that turn reports the provider
error and the following turn falls back to full local history.

When `anthropicCompactThreshold` is omitted, Apus uses
`max(50000, floor(contextWindow * 0.7))`. To choose a different input-token
trigger:

```json5
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-6": {
          params: {
            anthropicServerCompaction: true,
            anthropicCompactThreshold: 120000,
          },
        },
      },
    },
  },
}
```

Configured thresholds below `50000` are clamped to `50000`.

Anthropic server-side compaction is a beta feature and Apus never
enables it automatically. It applies only to direct Anthropic API requests
authenticated with an API key. OAuth/subscription tokens, Claude CLI,
proxies, Bedrock, Vertex, and Foundry are excluded. Apus does not send
`pause_after_compaction` or custom compaction instructions.

See Anthropic's [compaction guide](https://platform.claude.com/docs/en/build-with-claude/compaction).

The bundled Anthropic plugin registers image and PDF understanding. Apus
auto-resolves media capabilities from the configured Anthropic auth; no
additional config is needed.

| Property        | Value                 |
| --------------- | --------------------- |
| Default model   | `claude-opus-5-5`       |
| Supported input | Images, PDF documents |

When an image or PDF is attached to a conversation, Apus automatically
routes it through the Anthropic media understanding provider.

Claude Haiku 5.5, Opus 5.5, Opus 5, Sonnet 5.5, Sonnet 5, Mythos 5, Fable 5.1, and
Fable 5 have an exact 1,000,000-token input window and support up to 128,000 output tokens.
Anthropic's 1M context window is also GA on Claude 4.x models with adaptive
thinking: Opus 4.8,
Opus 4.7, Opus 4.6, and Sonnet 4.6. Apus sizes these models
automatically, no `params.context1m` needed:

```json5
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-5": {},
        "anthropic/claude-sonnet-5-5": {},
        "anthropic/claude-sonnet-5": {},
        "anthropic/claude-mythos-5": {},
        "anthropic/claude-opus-4-8": {},
      },
    },
  },
}
```

Older configs can keep `params.context1m: true`; it is a harmless no-op for
these models and Apus no longer sends the retired
`context-1m-2025-08-07` beta header regardless. Older `anthropicBeta` config
entries with that value are dropped during request header resolution, and
unsupported older Claude models stay on their normal context window.

Claude CLI (`claude-cli/*`) has its own context budget. For older models
such as Sonnet 4.6, API availability does not automatically select the CLI's
extended context. Apus uses CLI-owned metadata and configured limits;
an eligible `[1m]` model ref or `params.context1m: true` selects a 1M budget.
Native extended-context access still depends on the installed CLI and your
account; see [Claude Code extended context](https://code.claude.com/docs/en/model-config#extended-context).

Requires long-context access on your Anthropic credential. OAuth/subscription token auth keeps its required Anthropic beta headers, but Apus strips the retired 1M beta header if it remains in older config.

`anthropic/claude-opus-5` and its `claude-cli` variant have a 1M context
window by default; no `params.context1m: true` needed.

Troubleshooting

Run these commands as the Gateway user on the Gateway host:

```bash
claude auth status --text
claude auth login
apus gateway restart
```

Claude Code owns its login and refresh lifecycle; do not copy an OAuth token into Apus.

Anthropic token auth expires and can be revoked. For new setups, use an Anthropic API key instead.

Agents read shared auth profiles at runtime, with agent-local profiles overriding shared profiles with the same ID. A new agent does not need a separate API key when a usable shared Anthropic profile exists.

Check the affected agent with `apus models status --agent <agentId>`. If no usable credential is available, configure an Anthropic API key on the Gateway host or set up auth for that agent.

Read-through is separate from copying: non-portable profiles can still be used from the shared store. Explicit copy flows follow the [agent copy portability policy](/auth-credential-semantics#agent-copy-portability).

Native Claude CLI logins remain owned by Claude Code, not the shared Apus auth store. For that route, use the [Claude CLI setup](/providers/anthropic#getting-started); do not copy native OAuth tokens into Apus.

Run `apus models status` to see which auth profile is active. Re-run onboarding, or configure an API key for that profile path.

Check `apus models status --json` for `auth.unusableProfiles`. Anthropic rate-limit cooldowns can be model-scoped, so a sibling Anthropic model may still be usable. Add another Anthropic profile or wait for cooldown.

Related

Choosing providers, model refs, and failover behavior.

Claude CLI backend setup and runtime details.

How prompt caching works across providers.

Auth details and credential reuse rules.

Community proxy exposing Claude subscription credentials as an OpenAI-compatible endpoint.

Anthropic models, Claude CLI, and the native Claude session catalog.