Skip to content
shunt

Operations

Overview

Section titled “Overview”

Operationally, shunt is a local Rust binary plus a TOML config. You build it with Cargo, validate the config with shunt check, run the gateway, then start Claude Code with ANTHROPIC_BASE_URL pointing at the gateway. Provider credentials stay in the shunt process environment or Codex/Claude credential files; Claude Code does not send OpenAI or ChatGPT credentials for mapped models docs/running.md:1-461 src/auth/mod.rs:29-99.

Operation Command Why it exists Source
Debug build cargo build Compile the gateway while developing docs/running.md:26-37
Release build cargo build --release Produce target/release/shunt for daily use docs/running.md:31-34
Config check cargo run -- check or shunt check Validate before binding or connecting Claude Code src/main.rs:77-83
Run cargo run -- run or shunt run Start Axum HTTP gateway src/main.rs:38-76
Token helper shunt token Print Claude subscription token for apiKeyHelper src/main.rs:51-58
CI validation cargo fmt, cargo clippy, cargo test Enforced before PR merge .github/workflows/ci.yml:1-42

Command Lifecycle

Section titled “Command Lifecycle”
flowchart TB
    Start[Clone repo] --> Build[cargo build --release]
    Build --> Config[cp shunt.toml.example shunt.toml]
    Config --> Check[shunt check]
    Check -->|ok| Run[shunt run]
    Check -->|error| Fix[Fix TOML or env]
    Fix --> Check
    Run --> Claude[Start Claude Code with ANTHROPIC_BASE_URL]
    Claude --> Verify[Run curl or model picker smoke]
    classDef dark fill:#2d333b,stroke:#6d5dfc,color:#e6edf3;
    class Start,Build,Config,Check,Run,Fix,Claude,Verify dark;
    linkStyle default stroke:#8b949e;

Connect Claude Code

Section titled “Connect Claude Code”
sequenceDiagram
    autonumber
    participant Shell as Developer shell
    participant Shunt as shunt process
    participant Claude as Claude Code
    Shell->>Shunt: export provider credentials and run gateway
    Shell->>Claude: export ANTHROPIC_BASE_URL=http://127.0.0.1:3001
    Claude->>Shunt: HEAD / probe
    Claude->>Shunt: POST /v1/messages
    Shunt-->>Claude: Anthropic-shaped response

CI Pipeline

Section titled “CI Pipeline”
flowchart LR
    PR[Push or pull_request] --> Checkout[Checkout pinned SHA]
    Checkout --> Rust[Install stable Rust + rustfmt + clippy]
    Rust --> Cache[Cargo cache]
    Cache --> Fmt[cargo fmt --all --check]
    Fmt --> Clippy[cargo clippy --all-targets --all-features -- -D warnings]
    Clippy --> Test[cargo test --all-features --workspace]
    classDef dark fill:#2d333b,stroke:#6d5dfc,color:#e6edf3;
    class PR,Checkout,Rust,Cache,Fmt,Clippy,Test dark;
    linkStyle default stroke:#8b949e;

Troubleshooting Table

Section titled “Troubleshooting Table”
Symptom Likely cause Fix Source
config check failed Bad bind address, provider URL, missing env setting, or unknown provider reference Run shunt check and follow typed error src/config.rs:196-242
ChatGPT auth not found; run codex login ~/.codex/auth.json is absent or unreadable Run codex login src/auth/codex_auth.rs:34-63
Model absent in /model gpt-* IDs are ignored by gateway discovery Use ANTHROPIC_CUSTOM_MODEL_OPTION or a Claude-named alias docs/running.md:231-287
Claude passthrough fails Gateway credential is dummy or missing Use real Anthropic credential or shunt token helper docs/running.md:289-348
OpenAI/Codex model rejected Upstream slug not entitled or unsupported Use an entitled slug or upstream_model docs/running.md:244-252
Section titled “Related Pages”
Page Relationship
Configuration Defines the settings operations validate
Authentication Explains credential sources and refresh
Testing and Quality Expands on CI and test coverage
Contributor Guide Contributor workflow using these commands

References

Section titled “References”