How to Use the Switchyard Launch Command with Claude Code, Codex, and OpenClaw

switchyard launch is the unified CLI entry point that spins up a native Switchyard server and routes Claude Code, Codex, or OpenClaw through a local HTTP proxy defined by a TOML deployment configuration.

The switchyard launch command in NVIDIA-NeMo/Switchyard lets you run three popular coding agents against a configurable backend without modifying each tool's global settings. Whether you're benchmarking models or switching between providers, this single command handles server startup, environment injection, and agent execution in one workflow.

Supported Agents and Launch Syntax

Switchyard supports three agents through dedicated subcommands:

Agent	Subcommand	Binary Required
Claude Code	claude	claude
Codex	codex	codex
OpenClaw	openclaw	openclaw

All three share the same core flags: --model (required route name), --config (optional TOML path), and agent-specific passthrough arguments.

The Three-Stage Launch Pipeline

Every switchyard launch invocation follows an identical pipeline implemented in launch_command.py. Here is how each stage works according to the Switchyard source code.

Stage 1: Resolve the Deployment Configuration

If you omit --config, the CLI falls back to the packaged openrouter.toml. The helper _config_path in switchyard/cli/launch_command.py handles this resolution:

# From launch_command.py lines 11-20

def _config_path(config: Optional[str]) -> str:
    if config is None:
        # Fallback to packaged OpenRouter config

        return str(files("switchyard.configs").joinpath("openrouter.toml"))
    return config

Best practice: Pin your deployment with --config routes.toml for reproducible team environments.

Stage 2: Start the Native Switchyard Server

Each launcher calls NativeServer(config) from native_server.py. This spins up the Rust server in-process, registers routes from your TOML file, and binds to a free local port. The server tracks runtime statistics for the live footer displayed during agent execution.

The server runs until the agent exits, then cleans up automatically.

Stage 3: Prepare Agent-Specific Transport

Each agent requires different environment overrides or CLI flags to redirect traffic through the Switchyard proxy.

Claude Code Launcher

Located in switchyard/cli/launchers/claude_code_launcher.py, this launcher:

1. Discovers the claude binary in your $PATH
2. Builds environment overrides (ANTHROPIC_BASE_URL, ANTHROPIC_MODEL, etc.) pointing to the local proxy
3. Runs interactive TUI (ShellTUI) for TTY sessions or plain subprocess for non-TTY

# From claude_code_launcher.py lines 63-90

env_overrides = {
    "ANTHROPIC_BASE_URL": f"http://localhost:{proxy_port}",
    "ANTHROPIC_MODEL": model_route,
    # ... additional auth headers

}

Codex Launcher

The codex_cli_launcher.py launcher builds temporary provider-override flags instead of environment variables:

# From codex_cli_launcher.py lines 62-94

provider_overrides = {
    "model_provider": "switchyard",
    "base_url": f"http://localhost:{proxy_port}",
    "auth": {"type": "none"},  # Switchyard handles auth

    # Optional: model_catalog_json for custom routing

}

Pass extra Codex flags with --codex-args.

OpenClaw Launcher

The openclaw_launcher.py launcher creates a transient workspace (openclaw.json) describing the model catalog and proxy URL:

# From openclaw_launcher.py lines 43-51, 43-54

workspace = {
    "models": [{"id": model_route, "provider": "switchyard"}],
    "default_model": model_route,
    "proxy_url": f"http://localhost:{proxy_port}"
}

# Injected via OPENCLAW_STATE_DIR, OPENCLAW_HOME environment variables

Then it runs openclaw chat with your specified model.

Shared Runtime Utilities

All three launchers import from launcher_runtime.py, which provides:

• wait_for_proxy_ready – Polls /health until HTTP 200 or timeout
• configure_debug_file_logging – Writes switchyard-debug.log for troubleshooting
• print_ready_banner / print_startup_failure – User-friendly console messages
• LiveStatsFooter – Real-time request/response statistics during agent sessions

Practical Usage Examples

Run Claude Code against the default OpenRouter deployment:

switchyard launch claude --model switchyard

Use a custom deployment with Claude Code:

switchyard launch claude --model my-route --config routes.toml

Run Codex with default settings:

switchyard launch codex --model switchyard

Disable streaming and add Codex-specific flags:

switchyard launch codex --model switchyard --codex-args "--no-stream"

Launch OpenClaw with a custom model:

switchyard launch openclaw --model my-openclaw-model --config routes.toml

Pass temperature and other OpenClaw arguments:

switchyard launch openclaw --model switchyard --openclaw-args "--temperature 0.7"

Each command dispatches to cmd_launch_claude, cmd_launch_codex, or cmd_launch_openclaw defined in launch_command.py lines 22-58.

Key Source Files

File	Purpose
switchyard/cli/launch_command.py	CLI entry point, argument parsing, dispatcher
switchyard/cli/launchers/claude_code_launcher.py	Claude Code workflow, env var injection
switchyard/cli/launchers/codex_cli_launcher.py	Codex workflow, provider flag construction
switchyard/cli/launchers/openclaw_launcher.py	OpenClaw workspace creation and execution
switchyard/cli/launchers/native_server.py	In-process Rust server startup
switchyard/cli/launchers/launcher_runtime.py	Health checks, logging, live statistics UI

Summary

• switchyard launch unifies Claude Code, Codex, and OpenClaw behind a single command with consistent TOML-based configuration
• The pipeline resolves config → starts NativeServer → builds agent-specific transport → launches binary with TUI or subprocess fallback
• Each agent uses different override mechanisms: Claude Code (environment variables), Codex (provider flags), OpenClaw (transient workspace JSON)
• Shared runtime utilities in launcher_runtime.py handle health checks, debug logging, and live session statistics
• Use --config for reproducible deployments and --*-args flags to pass through agent-specific options

Frequently Asked Questions

What happens if I don't specify a --config flag?

The launcher calls _config_path() which returns the packaged openrouter.toml from the Switchyard installation. This default connects to OpenRouter's API with Switchyard's routing layer.

How does Switchyard redirect each agent's traffic without changing global settings?

Each launcher builds isolated, ephemeral configuration: Claude Code gets environment variable overrides (ANTHROPIC_BASE_URL), Codex receives temporary provider flags (--model_provider switchyard), and OpenClaw runs from a generated workspace directory. These changes exist only for the subprocess lifetime.

Can I run switchyard launch in CI or non-interactive environments?

Yes. The launchers detect TTY status automatically. In non-TTY mode, they fall back to plain subprocess execution without the ShellTUI interface, making them suitable for automated testing and CI pipelines.

Where can I find debug logs if a launch fails?

The launcher_runtime.py utility configure_debug_file_logging() writes to switchyard-debug.log in your working directory. Additionally, print_startup_failure() surfaces the most common configuration errors to stderr with actionable fixes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}