Proxy & Model Discovery Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

• src/proxy.rs
• src/discovery.rs
• src/routes.rs
• ARCHITECTURE.md
• README.md
• AGENTS.md
• src/AGENTS.md
• blueprints/upstream/_generic.md

Shunt operates as a spec-compliant Claude Code LLM gateway, serving as a transparent proxy for Anthropic Messages requests. Its primary function is to intercept requests, resolve routing based on model identifiers, and dispatch inference to various providers while maintaining the integrity of the Claude Code tool harness.

The system relies on a set of core endpoints to handle request proxying, model discovery, and protocol metadata. These endpoints allow client applications (primarily Claude Code) to identify available models and execute inference across distributed providers such as OpenAI, Codex, xAI, and native Anthropic backends.

Sources: ARCHITECTURE.md:5, README.md:15-20

The Proxy Request Pipeline

The proxying logic is primarily housed in src/proxy.rs. This module manages the high-level request lifecycle from the moment a client sends a POST /v1/messages request until the response is streamed back.

Request Processing Flow

When an inbound request is received, the gateway follows a strict pipeline:

1. Buffering: The request body is buffered to allow for routing analysis and potential translation.
2. State Snapshotting: The current configuration and authentication state are snapshotted via SharedState to ensure consistency throughout the request lifetime.
3. Routing Resolution: The system calls routing::resolve to map the requested model ID to a specific Route. This resolution follows a hierarchy: Exact Route → Prefix Route → default_provider.
4. Auth Gating: Inbound authentication is validated before proceeding.
5. Adapter Dispatch: The request is handed over to the appropriate Adapter (e.g., Anthropic, Responses, or Cursor) based on the resolved route.

Sources: ARCHITECTURE.md:14-21, src/AGENTS.md:15-18, ARCHITECTURE.md:52

Proxy Sequence Diagram

The following diagram illustrates the sequence of operations for a standard proxied request.

This diagram shows how src/proxy.rs coordinates between the routing logic and the adapters to fulfill requests.
Sources: ARCHITECTURE.md:14-25, AGENTS.md:15-25

Model Discovery

Model discovery is facilitated by the GET /v1/models endpoint, implemented in src/discovery.rs. Claude Code queries this endpoint at startup to populate its /model picker and understand the capabilities of the gateway.

Discovery Logic

• Built-in Models: By default, the gateway includes a curated catalog of Anthropic models.
• Custom Models: Models defined in the configuration (via [[models]] or [[routes]]) are appended to the discovery list.
• Filtering: Claude Code filters this list, typically ignoring entries whose IDs do not begin with claude or anthropic unless they are manually selected via ANTHROPIC_CUSTOM_MODEL_OPTION.
• Deduplication: Entries are deduplicated by ID to ensure a clean interface.

Sources: README.md:353-356, ARCHITECTURE.md:60

Discovery Component Table

Endpoint	Method	Implementation	Purpose
/v1/models	GET	src/discovery.rs	Returns available models for client-side selection.
/protocol	GET	src/protocol.rs	Serves the machine-readable gateway protocol spec.
/routes	GET	src/routes.rs	Provides metadata about active routing tables.

Sources: ARCHITECTURE.md:60, README.md:351

Routing and Metadata Endpoints

The src/routes.rs module provides visibility into the active routing configuration of the gateway. This is part of the metadata suite that allows operators and clients to inspect how specific model IDs are currently mapped to providers.

Routing Logic

The routing resolution process strips context-window suffixes (like [1m]) before matching against the configuration.

• Exact Routes: Matches the full model string.
• Prefix Routes: Matches based on the start of the model ID string.
• Default Provider: If no matches are found, the request falls back to the default_provider (usually anthropic).

Sources: ARCHITECTURE.md:53, src/AGENTS.md:19-20

Routing Resolution Flow

This flowchart describes the logic used by the gateway to determine which upstream provider should handle a request.
Sources: ARCHITECTURE.md:53, README.md:150-160

Implementation Constraints

The proxy and discovery endpoints are subject to several architectural invariants to ensure compatibility with the Claude Code harness:

1. Streaming Integrity: Upstream SSE (Server-Sent Events) must never be buffered. They are forwarded to the client as they arrive to maintain incremental rendering.
2. Error Reshaping: Gateway-owned errors (e.g., routing failures, auth errors) must be reshaped into the Anthropic error envelope ({"type":"error","error":{...}}).
3. Config Snapshots: Configuration is snapshotted once per request. A mid-request config reload will only affect subsequent requests, ensuring a consistent view for in-flight transactions.
4. Unmapped Traffic: Traffic that does not match any specific route must pass through to the default provider (Anthropic) unchanged.

Sources: ARCHITECTURE.md:74-85, src/AGENTS.md:30-35

Summary

The Proxy & Model Discovery endpoints form the backbone of the shunt gateway. By implementing the official Claude Code LLM Gateway Protocol, the system provides a robust mechanism for model-level diversion. The combination of src/proxy.rs for execution and src/discovery.rs for capability advertisement allows for a flexible, multi-provider environment that remains fully compatible with existing developer tools and skills.

Sources: ARCHITECTURE.md:5, README.md:365-370