From b689067598c5e908e7edf1f018586c18ac845028 Mon Sep 17 00:00:00 2001 From: Ryan Lempka Date: Tue, 29 Sep 2026 10:52:06 -0500 Subject: [PATCH 1/3] docs: add coding agent login recipes Signed-off-by: Ryan Lempka --- docs/index.md | 1 + docs/integrations/coding_agents.md | 180 +++++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 182 insertions(+) create mode 100644 docs/integrations/coding_agents.md diff --git a/docs/index.md b/docs/index.md index b477c1eeb..af1dffd5e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,6 +8,7 @@ It supports OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages. | Goal | Path | Start here | |---|---|---| | Run Switchyard as a standalone proxy for API clients | Server Path | [Build and run the Rust server](getting_started.md#server-path) | +| Route Codex or Claude Code using your existing login | Server Path | [Coding agent recipes](integrations/coding_agents.md) | | Add Switchyard routing to a Rust application | Library Path | [`switchyard-libsy`](../crates/libsy/README.md) | | Add Switchyard routing to NeMo Relay | Native Plugin Path | [Use Switchyard with NeMo Relay](integrations/nemo_relay.md) | | Point the pi coding agent at the standalone proxy | Server Path | [Use Switchyard with pi](integrations/pi.md) | diff --git a/docs/integrations/coding_agents.md b/docs/integrations/coding_agents.md new file mode 100644 index 000000000..8dc1f7cb6 --- /dev/null +++ b/docs/integrations/coding_agents.md @@ -0,0 +1,180 @@ +# Coding agents with your existing login + +Run Codex or Claude Code through Switchyard using the login already saved by your +CLI. Switchyard forwards that credential to the same provider, including classifier +calls. You do not need to put a key in the server config. + +Both recipes use [composite routing](../routing_algorithms/composite_routing.md). +A classifier chooses the default tier for each user turn. The stage router uses +tool results to adjust that choice during the turn. Keep every target, including +the classifier, with the same provider when using +[`forward_auth`](../reference/toml_schema.md#llm_clientsname). + +From a checkout of current `main`, install the server, then choose one recipe. +Each uses local port `4123`. + +```bash +cargo install --locked --path crates/switchyard-server +``` + +## Codex with OpenAI + +Sign in with `codex login`. This example uses Terra to classify and routes between +Sol and Luna. Use model IDs available to your ChatGPT account. + +Save as `codex-routing.toml`: + +```toml +schema_version = 1 + +[llm_clients.chatgpt] +format = "openai_responses" +base_url = "https://chatgpt.com/backend-api/codex" +forward_auth = true + +[targets.capable] +id = "gpt-5.6-sol" +llm_client = "chatgpt" + +[targets.efficient] +id = "gpt-5.6-luna" +llm_client = "chatgpt" + +[targets.judge] +id = "gpt-5.6-terra" +llm_client = "chatgpt" +extra_body = { store = false, stream = true } +omit_body_fields = ["max_output_tokens"] + +[routes.switchyard] +id = "switchyard" +type = "composite" + +[routes.switchyard.classifier] +target = "judge" +base_threshold = 0.5 +classify_trigger = "user_turn" + +[routes.switchyard.stage] +capable_target = "capable" +efficient_target = "efficient" +confidence_threshold = 0.5 +``` + +The ChatGPT backend requires `store = false` and `stream = true`, and rejects +`max_output_tokens`. The judge settings above adapt its generated request. +`omit_body_fields` requires a build newer than v0.3.0. Codex already supplies the +right fields for the answer requests. + +Start the server: + +```bash +switchyard-server --config codex-routing.toml --dry-run +switchyard-server --config codex-routing.toml --host 127.0.0.1 --port 4123 +``` + +Create `~/.codex/switchyard.config.toml` (or place it beside your `config.toml` if +you use a custom Codex config directory): + +```toml +model = "switchyard" +model_provider = "switchyard" + +[model_providers.switchyard] +name = "Switchyard" +base_url = "http://127.0.0.1:4123/v1" +wire_api = "responses" +requires_openai_auth = true +``` + +In another terminal, launch Codex: + +```bash +codex --profile switchyard +``` + +`requires_openai_auth` makes Codex send its saved OpenAI login. Switchyard forwards +it and the account headers to the ChatGPT backend. See the +[Codex configuration reference](https://developers.openai.com/codex/config-reference/) +for profile and provider settings. + +## Claude Code with Anthropic + +Sign in to Claude Code with your Claude account first. This example uses Haiku to +classify and routes between Opus and Sonnet. Use model IDs available to your account. + +Save as `claude-routing.toml`: + +```toml +schema_version = 1 + +[llm_clients.anthropic] +format = "anthropic_messages" +base_url = "https://api.anthropic.com" +forward_auth = true + +[targets.capable] +id = "claude-opus-5-5" +llm_client = "anthropic" + +[targets.efficient] +id = "claude-sonnet-5-5" +llm_client = "anthropic" + +[targets.judge] +id = "claude-haiku-4-5-20251001" +llm_client = "anthropic" + +[routes.switchyard] +id = "switchyard" +type = "composite" + +[routes.switchyard.classifier] +target = "judge" +base_threshold = 0.5 +classify_trigger = "user_turn" + +[routes.switchyard.stage] +capable_target = "capable" +efficient_target = "efficient" +confidence_threshold = 0.5 +``` + +Start the server: + +```bash +switchyard-server --config claude-routing.toml --dry-run +switchyard-server --config claude-routing.toml --host 127.0.0.1 --port 4123 +``` + +In another terminal, launch Claude Code: + +```bash +env -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN \ + ANTHROPIC_BASE_URL=http://127.0.0.1:4123 \ + ANTHROPIC_DEFAULT_OPUS_MODEL=switchyard \ + ANTHROPIC_DEFAULT_SONNET_MODEL=switchyard \ + ANTHROPIC_DEFAULT_HAIKU_MODEL=switchyard \ + claude --model switchyard +``` + +Do not append `/v1` to Claude Code's base URL. The CLI adds it. The model overrides +keep its Opus, Sonnet, and Haiku aliases pointed at the configured route. + +Leave gateway credentials and `apiKeyHelper` unset when using your saved login. +A placeholder `ANTHROPIC_AUTH_TOKEN` would replace the real credential. Switchyard +forwards Anthropic's credential and the `oauth-*` beta marker required for OAuth. +See [Anthropic's gateway authentication docs](https://code.claude.com/docs/en/llm-gateway#subscriptions-and-gateways). + +## Check the routing + +Send a short prompt, then inspect the server's counters: + +```bash +curl -s http://127.0.0.1:4123/v1/stats \ + | jq '{answers: .models, classifier: .classifier.models}' +``` + +The answer appears under the selected model. The classifier has separate counters. +Both CLIs send session headers that Switchyard uses to retain the classifier's +choice between user turns. Stop the local server with `Ctrl-C`. diff --git a/mkdocs.yml b/mkdocs.yml index 5cd2a986c..a7b27fe8f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,6 +24,7 @@ nav: - Core Concepts: core_concepts.md - Architecture: architecture.md - Integrations: + - Coding Agents: integrations/coding_agents.md - NeMo Relay: integrations/nemo_relay.md - pi: integrations/pi.md - Oh My Pi: integrations/oh_my_pi.md From 587485ed2f62df2ab66584251ee004fe1557ed19 Mon Sep 17 00:00:00 2001 From: Ryan Lempka Date: Tue, 29 Sep 2026 14:22:11 -0500 Subject: [PATCH 2/3] docs: simplify single-provider coding agent recipes Signed-off-by: Ryan Lempka --- docs/index.md | 2 +- .../single_provider_coding_agents.md} | 65 +++++++------------ mkdocs.yml | 3 +- 3 files changed, 28 insertions(+), 42 deletions(-) rename docs/{integrations/coding_agents.md => recipes/single_provider_coding_agents.md} (53%) diff --git a/docs/index.md b/docs/index.md index af1dffd5e..b8971e066 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,7 +8,7 @@ It supports OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages. | Goal | Path | Start here | |---|---|---| | Run Switchyard as a standalone proxy for API clients | Server Path | [Build and run the Rust server](getting_started.md#server-path) | -| Route Codex or Claude Code using your existing login | Server Path | [Coding agent recipes](integrations/coding_agents.md) | +| Route Codex or Claude Code using your existing login | Server Path | [Single-provider coding agents](recipes/single_provider_coding_agents.md) | | Add Switchyard routing to a Rust application | Library Path | [`switchyard-libsy`](../crates/libsy/README.md) | | Add Switchyard routing to NeMo Relay | Native Plugin Path | [Use Switchyard with NeMo Relay](integrations/nemo_relay.md) | | Point the pi coding agent at the standalone proxy | Server Path | [Use Switchyard with pi](integrations/pi.md) | diff --git a/docs/integrations/coding_agents.md b/docs/recipes/single_provider_coding_agents.md similarity index 53% rename from docs/integrations/coding_agents.md rename to docs/recipes/single_provider_coding_agents.md index 8dc1f7cb6..b7e90510a 100644 --- a/docs/integrations/coding_agents.md +++ b/docs/recipes/single_provider_coding_agents.md @@ -1,27 +1,26 @@ -# Coding agents with your existing login +# Interactive coding agents with single-provider auth -Run Codex or Claude Code through Switchyard using the login already saved by your -CLI. Switchyard forwards that credential to the same provider, including classifier -calls. You do not need to put a key in the server config. +Route Codex or Claude Code between models from one provider using your saved CLI +login. Every target, including the classifier, must use that provider. -Both recipes use [composite routing](../routing_algorithms/composite_routing.md). -A classifier chooses the default tier for each user turn. The stage router uses -tool results to adjust that choice during the turn. Keep every target, including -the classifier, with the same provider when using -[`forward_auth`](../reference/toml_schema.md#llm_clientsname). +These [composite routing](../routing_algorithms/composite_routing.md) recipes use a +classifier to choose the starting tier for each user turn. Stage adjusts routing +during tool calls. [`forward_auth`](../reference/toml_schema.md#llm_clientsname) +passes your login through to the models. -From a checkout of current `main`, install the server, then choose one recipe. -Each uses local port `4123`. +Choose one recipe. Each uses local port `4123`. + +## Codex with OpenAI + +Sign in with `codex login`. Terra classifies, and Stage routes between Sol and Luna. + +This recipe needs Codex classifier support added after v0.3.0. Install from a +checkout of current `main`: ```bash cargo install --locked --path crates/switchyard-server ``` -## Codex with OpenAI - -Sign in with `codex login`. This example uses Terra to classify and routes between -Sol and Luna. Use model IDs available to your ChatGPT account. - Save as `codex-routing.toml`: ```toml @@ -61,11 +60,6 @@ efficient_target = "efficient" confidence_threshold = 0.5 ``` -The ChatGPT backend requires `store = false` and `stream = true`, and rejects -`max_output_tokens`. The judge settings above adapt its generated request. -`omit_body_fields` requires a build newer than v0.3.0. Codex already supplies the -right fields for the answer requests. - Start the server: ```bash @@ -93,15 +87,16 @@ In another terminal, launch Codex: codex --profile switchyard ``` -`requires_openai_auth` makes Codex send its saved OpenAI login. Switchyard forwards -it and the account headers to the ChatGPT backend. See the -[Codex configuration reference](https://developers.openai.com/codex/config-reference/) -for profile and provider settings. - ## Claude Code with Anthropic -Sign in to Claude Code with your Claude account first. This example uses Haiku to -classify and routes between Opus and Sonnet. Use model IDs available to your account. +Sign in to Claude Code with your Claude account. Haiku classifies, and Stage routes +between Opus and Sonnet. + +Install the released server: + +```bash +cargo install --locked --version 0.3.0 switchyard-server +``` Save as `claude-routing.toml`: @@ -158,23 +153,13 @@ env -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN \ claude --model switchyard ``` -Do not append `/v1` to Claude Code's base URL. The CLI adds it. The model overrides -keep its Opus, Sonnet, and Haiku aliases pointed at the configured route. - -Leave gateway credentials and `apiKeyHelper` unset when using your saved login. -A placeholder `ANTHROPIC_AUTH_TOKEN` would replace the real credential. Switchyard -forwards Anthropic's credential and the `oauth-*` beta marker required for OAuth. -See [Anthropic's gateway authentication docs](https://code.claude.com/docs/en/llm-gateway#subscriptions-and-gateways). +Use your saved Claude login, without an `apiKeyHelper` or gateway token. ## Check the routing -Send a short prompt, then inspect the server's counters: +Send a prompt, then check which models handled the answer and classification: ```bash curl -s http://127.0.0.1:4123/v1/stats \ | jq '{answers: .models, classifier: .classifier.models}' ``` - -The answer appears under the selected model. The classifier has separate counters. -Both CLIs send session headers that Switchyard uses to retain the classifier's -choice between user turns. Stop the local server with `Ctrl-C`. diff --git a/mkdocs.yml b/mkdocs.yml index a7b27fe8f..57cf32d62 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,10 +24,11 @@ nav: - Core Concepts: core_concepts.md - Architecture: architecture.md - Integrations: - - Coding Agents: integrations/coding_agents.md - NeMo Relay: integrations/nemo_relay.md - pi: integrations/pi.md - Oh My Pi: integrations/oh_my_pi.md + - Recipes: + - Single-provider coding agents: recipes/single_provider_coding_agents.md - Routing: - Overview: routing_algorithms/overview.md - Task (LLM Classifier): routing_algorithms/llm_classifier_routing.md From 323802fd7e63dc1ccfc090e28c236a9fab245758 Mon Sep 17 00:00:00 2001 From: Ryan Lempka Date: Tue, 29 Sep 2026 14:23:16 -0500 Subject: [PATCH 3/3] docs: use latest release for Claude recipe Signed-off-by: Ryan Lempka --- docs/recipes/single_provider_coding_agents.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/recipes/single_provider_coding_agents.md b/docs/recipes/single_provider_coding_agents.md index b7e90510a..6ede23313 100644 --- a/docs/recipes/single_provider_coding_agents.md +++ b/docs/recipes/single_provider_coding_agents.md @@ -92,10 +92,10 @@ codex --profile switchyard Sign in to Claude Code with your Claude account. Haiku classifies, and Stage routes between Opus and Sonnet. -Install the released server: +Install the latest release: ```bash -cargo install --locked --version 0.3.0 switchyard-server +cargo install --locked switchyard-server ``` Save as `claude-routing.toml`: