Anthropic & Claude Provider
Relevant source files
The following files were used as context for generating this wiki page:
The Anthropic & Claude Provider implementation in shunt serves as both a primary passthrough for official Anthropic Messages API traffic and a managed integration for Claude-branded services. It allows developers using the Claude Code harness to route traffic to the official Anthropic API (api.anthropic.com) or any Anthropic-compatible backend while supporting advanced authentication flows like Claude OAuth for managed accounts.
As the default_provider in the system, it handles unmapped traffic and ensures that the gateway-protocol compliance is maintained for Claude Code clients.
Sources: ARCHITECTURE.md:12-25, ARCHITECTURE.md:112-118, blueprints/upstream/anthropic.md:1-10
Architecture and Integration
The Anthropic integration is implemented via the anthropic adapter. Unlike translation-heavy adapters, the Anthropic adapter primarily functions as a high-fidelity proxy that preserves the native Anthropic Messages protocol and Server-Sent Events (SSE) framing.
Data Flow for Anthropic Requests
When a request is routed to an Anthropic-based upstream, the system follows a specific sequence from buffering to credential injection and streaming.
This diagram illustrates the lifecycle of a request through the Anthropic adapter, including optional managed credential retrieval.
Sources: ARCHITECTURE.md:12-25, src/adapters/anthropic/mod.rs, src/auth/claude/auth.rs
Authentication Modes
The Anthropic provider supports two distinct authentication strategies, allowing for both client-side and server-side credential management.
| Mode | Configuration Key | Description |
|---|---|---|
| Passthrough | passthrough | Forwards the x-api-key header provided by the inbound client directly to the upstream. |
| Claude OAuth | claude_oauth | Uses shunt-managed credentials from the local session store (e.g., ~/.claude/.credentials.json). |
Sources: blueprints/upstream/anthropic.md:27-44, src/auth/claude/mod.rs
Claude OAuth and Credential Management
The claude_oauth mode relies on a dedicated auth subsystem that manages tokens, refresh logic, and local storage. The ClaudeAuthStore handles reading and writing session data securely.
- Credential Storage: Managed via
src/auth/claude/store.rs, which typically targets~/.claude/for configuration persistence. - Login Flow: Initiated via the CLI (
shunt login claude), which triggers the OAuth exchange and updates the local store. - Refresh Strategy: The system implements cancellation-safe refresh with off-thread I/O to ensure that concurrent requests do not fail during a token rotation.
Sources: src/auth/claude/store.rs, src/auth/claude/auth.rs, ARCHITECTURE.md:135-140
Configuration and Routing
The Anthropic provider can be configured as a generic upstream or a specific route for particular models.
Upstream Definition
An upstream identifies the backend endpoint and its authentication requirements.
[[upstreams]]
name = "official-anthropic"
provider = "anthropic"
auth = "passthrough" # Default
Sources: blueprints/upstream/anthropic.md:19-25
Model Mapping
Specific model IDs can be routed to the Anthropic provider, allowing for "passthrough" behavior even if the default provider is changed.
[[models]]
id = "claude-3-5-sonnet-20240620"
display_name = "Claude 3.5 Sonnet"
[models.upstream_model]
anthropic = "claude-3-5-sonnet-20240620"
Sources: blueprints/upstream/anthropic.md:46-56
Technical Implementation Details
The Anthropic Adapter
The core logic resides in src/adapters/anthropic/mod.rs. Its primary responsibilities include:
- Header Hygiene: Stripping or remapping headers to ensure compatibility between the client and upstream.
- Streaming Preservation: Ensuring that
text/event-streamresponses are piped directly to the client without buffering, maintaining the low latency required by Claude Code. - Error Handling: Mapping upstream network or API failures into the standard Anthropic error envelope (
{"type":"error", "error": {...}}).
Sources: src/adapters/anthropic/mod.rs, ARCHITECTURE.md:112-118, ARCHITECTURE.md:120-124
Component Relationship
Class structure showing the relationship between the proxy state, the adapter, and the auth persistence layer.
Sources: src/adapters/anthropic/mod.rs, src/auth/claude/auth.rs, src/auth/claude/store.rs, ARCHITECTURE.md:41-55
Summary
The Anthropic & Claude Provider is the foundational integration of the shunt gateway. By providing a high-fidelity passthrough for the Anthropic Messages API and a robust OAuth management system for Claude accounts, it enables the gateway to act as a transparent proxy for official services while simultaneously allowing for account pooling and load balancing across multiple Claude subscriptions.