Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust

docs(configure): require api key in route-bundle setup (#30)

sabhatinas88cbc24b810d
diff --git a/README.md b/README.md
index b5307e402..40a389115 100644
--- a/README.md
+++ b/README.md
@@ -140,9 +140,14 @@ routes:
```bash
switchyard --routing-profiles routes.yaml -- launch claude
-switchyard --routing-profiles routes.yaml -- configure
+switchyard --routing-profiles routes.yaml -- configure --target provider \
+ --provider openrouter --api-key "$OPENROUTER_API_KEY" \
+ --base-url https://openrouter.ai/api/v1 --no-tui --no-model-discovery
```
+Non-interactive `configure` does not read provider credentials from the routing
+bundle; pass `--api-key` explicitly when persisting the bundle for CI.
+
For profile selection and full configuration examples, start with
[Routing Overview](docs/routing_algorithms/overview.md), then open the
strategy-specific page:
diff --git a/docs/cli_reference.md b/docs/cli_reference.md
index 61137b3f5..840125623 100644
--- a/docs/cli_reference.md
+++ b/docs/cli_reference.md
@@ -252,8 +252,10 @@ curl localhost:4000/v1/chat/completions \
# Legacy route bundle on port 4000
switchyard --routing-profiles routes.yaml -- serve --port 4000
-# Use the bundle previously persisted by `switchyard --routing-profiles ... -- configure`
-switchyard --routing-profiles routes.yaml -- configure
+# Persist a bundle for later runs; no-TTY configure requires explicit provider credentials
+switchyard --routing-profiles routes.yaml -- configure --target provider \
+ --provider openrouter --api-key "$OPENROUTER_API_KEY" \
+ --base-url https://openrouter.ai/api/v1 --no-tui --no-model-discovery
switchyard serve --port 4000
# Multi-worker uvicorn (route-bundle path)
@@ -467,7 +469,9 @@ The top-level key is omitted when skill distillation is not configured. `namespa
switchyard configure
# Save a routing bundle as the default for serve + launchers
-switchyard --routing-profiles routes.yaml -- configure
+switchyard --routing-profiles routes.yaml -- configure --target provider \
+ --provider openrouter --api-key "$OPENROUTER_API_KEY" \
+ --base-url https://openrouter.ai/api/v1 --no-tui --no-model-discovery
# Inspect what's stored, plus resolved provider / key source / harness paths
switchyard configure --show
diff --git a/docs/getting_started.md b/docs/getting_started.md
index 94665a07c..d0b645f3c 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -45,9 +45,16 @@ routes:
fallback_target_on_evict: strong
EOF
-switchyard --routing-profiles routes.yaml -- configure
+switchyard --routing-profiles routes.yaml -- configure --target provider \
+ --provider openrouter --api-key "$OPENROUTER_API_KEY" \
+ --base-url https://openrouter.ai/api/v1 --no-tui --no-model-discovery
```
+`api_key` inside the route bundle is used when Switchyard serves or launches the
+bundle. `configure --no-tui` still requires provider credentials as explicit
+flags, so CI setup should pass `--api-key` even when the YAML contains
+`${OPENROUTER_API_KEY}`.
+
> **Format default and caching.** Omitting `format:` from a tier silently defaults to `OPENAI` (Chat Completions) — not `AUTO`. For Claude/Anthropic/Bedrock tiers this is wrong: set `format: anthropic` explicitly. The native `/v1/messages` path preserves `cache_control`, which is what enables prompt caching. `format: openai` routes Claude through OpenAI-format translation that strips `cache_control`: the request still succeeds, but caching silently never engages and you pay full input price. Always use `format: openai` for NIM/non-Claude models and `format: anthropic` for Claude and Bedrock models. Use `format: auto` only when the upstream is genuinely unknown.
Inspect what was saved:
@@ -76,9 +83,17 @@ curl http://localhost:4000/v1/chat/completions \
-d '{"model": "smart", "messages": [{"role": "user", "content": "hello"}]}'
```
-**CI pattern:** run `switchyard --routing-profiles routes.yaml -- configure` in
-your environment setup, then `switchyard serve` in your service start step. No
-flags needed at serve time.
+**CI pattern:** run configure in your environment setup with explicit provider
+credentials:
+
+```bash
+switchyard --routing-profiles routes.yaml -- configure --target provider \
+ --provider openrouter --api-key "$OPENROUTER_API_KEY" \
+ --base-url https://openrouter.ai/api/v1 --no-tui --no-model-discovery
+```
+
+Then run `switchyard serve` in your service start step. No flags needed at serve
+time.
> **Override (dev / one-off work):** pass `--routing-profiles` to use a different
> bundle for a session without overwriting your saved config:
@@ -117,8 +132,8 @@ aliasing.
## Routing profiles
All route types work with both [Path A](#path-a-server-mode) and
-[Path B](#path-b-agent-launcher). Declare a type in your YAML, run
-`switchyard --routing-profiles routes.yaml -- configure`, then `serve` or `launch` as above.
+[Path B](#path-b-agent-launcher). Declare a type in your YAML, run the
+non-interactive configure command above, then `serve` or `launch` as above.
### Choose a route type
diff --git a/docs/index.md b/docs/index.md
index c15f5a4ed..fd07e2210 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -120,9 +120,14 @@ legacy bundles and saved bundle paths:
```bash
switchyard --routing-profiles routes.yaml -- launch claude
-switchyard --routing-profiles routes.yaml -- configure
+switchyard --routing-profiles routes.yaml -- configure --target provider \
+ --provider openrouter --api-key "$OPENROUTER_API_KEY" \
+ --base-url https://openrouter.ai/api/v1 --no-tui --no-model-discovery
```
+Non-interactive `configure` does not read provider credentials from the routing
+bundle; pass `--api-key` explicitly when persisting the bundle for CI.
+
Profile ids, direct targets, legacy launcher compatibility, and persistence are
covered in [Routing Overview](routing_algorithms/overview.md).