Configuration

Overview

Configuration exists to keep shunt generic: new upstreams are provider table entries, not code changes, and routing is a data problem expressed as exact model routes, prefix routes, and a default provider. Config::load merges built-in defaults, a TOML file, and SHUNT_ environment overrides before validate checks bind addresses, provider URLs, auth requirements, and provider references src/config.rs:185-194 src/config.rs:196-242.

Area	Responsibility	Key file	Source
Built-in defaults	Seeds anthropic, openai, codex, and xai providers	src/config.rs	src/config.rs:240-311
TOML example	Documents server, providers, routes, aliases	shunt.toml.example	shunt.toml.example:1-134
Runtime docs	Explains config precedence and Claude Code env vars	docs/running.md	docs/running.md:40-159
Route resolver	Applies exact, prefix, default precedence	src/routing.rs	src/routing.rs:37-89
Discovery	Serializes configured [[models]] entries	src/discovery.rs	src/discovery.rs:17-30

Configuration Layers

flowchart TB
    Defaults[Built-in Config default] --> Toml[shunt.toml or --config path]
    Toml --> Env[SHUNT_ environment overrides]
    Env --> Validate[Config::validate]
    Validate --> Runtime[Validated Config in AppState]
    classDef dark fill:#2d333b,stroke:#6d5dfc,color:#e6edf3;
    class Defaults,Toml,Env,Validate,Runtime dark;
    linkStyle default stroke:#8b949e;

Route Resolution

flowchart LR
    Model[Request model id] --> Exact{Exact route?}
    Exact -->|yes| ExactProvider[Route provider + optional upstream_model]
    Exact -->|no| Prefix{Prefix match?}
    Prefix -->|yes| PrefixProvider[Prefix provider]
    Prefix -->|no| DefaultProvider[server.default_provider]
    ExactProvider --> Route[Route]
    PrefixProvider --> Route
    DefaultProvider --> Route
    classDef dark fill:#2d333b,stroke:#6d5dfc,color:#e6edf3;
    class Model,Exact,ExactProvider,Prefix,PrefixProvider,DefaultProvider,Route dark;
    linkStyle default stroke:#8b949e;

Route Entities

erDiagram
    CONFIG ||--|| SERVER_CONFIG : owns
    CONFIG ||--o{ PROVIDER_CONFIG : names
    CONFIG ||--o{ ROUTE_CONFIG : exact_routes
    CONFIG ||--o{ ROUTE_PREFIX_CONFIG : prefix_routes
    CONFIG ||--o{ MODEL_CONFIG : exposes
    PROVIDER_CONFIG ||--o{ ROUTE_CONFIG : selected_by
    PROVIDER_CONFIG ||--o{ ROUTE_PREFIX_CONFIG : selected_by

Credential Strategy

Auth mode	Who supplies credential	Outbound behavior	Source
passthrough	Claude Code request	Forward incoming credential unchanged	src/auth/mod.rs:29-99 src/adapters/anthropic.rs:66-89
api_key	Environment variable named by api_key_env; OpenAI can fall back to Codex auth JSON	Inject provider key as Bearer or x-api-key	src/auth/mod.rs:57-80
chatgpt_oauth	~/.codex/auth.json from codex login	Refresh if near expiry, send Bearer + chatgpt-account-id	src/auth/codex_auth.rs:34-63 src/adapters/responses.rs:180-188
xai_oauth	~/.shunt/xai-auth.json from shunt login xai (SuperGrok / X Premium+)	Refresh with rotated-token persistence, send Bearer only; base_url must stay on an x.ai host	src/auth/xai_auth.rs:87-121 src/config.rs:424-435

Discovery Sequence

sequenceDiagram
    autonumber
    participant CC as Claude Code
    participant S as shunt /v1/models
    participant CFG as Config.models
    CC->>S: GET /v1/models?limit=1000
    S->>CFG: iterate configured aliases
    CFG-->>S: ModelConfig entries
    S-->>CC: data array with id and display_name

Related Pages

Page	Relationship
Overview	Explains why configuration controls routing
Operations	Shows how to run shunt check and connect Claude Code
Routing and Configuration	Deep implementation details
Authentication	Credential resolution internals

References

• src/config.rs:9-269
• shunt.toml.example:1-134
• docs/running.md:40-159
• src/routing.rs:37-89
• src/discovery.rs:17-30