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

> Master the switchyard launch command to integrate Claude Code, Codex, and OpenClaw. This guide explains how to spin up a native Switchyard server and route LLM requests efficiently.

- Repository: [NVIDIA-NeMo/Switchyard](https://github.com/NVIDIA-NeMo/Switchyard)
- Tags: how-to-guide
- Published: 2026-08-15

---

**`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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/openrouter.toml). The helper `_config_path` in [`switchyard/cli/launch_command.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/switchyard/cli/launch_command.py) handles this resolution:

```python

# 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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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

```python

# 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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/codex_cli_launcher.py) launcher builds temporary provider-override flags instead of environment variables:

```python

# 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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/openclaw_launcher.py) launcher creates a transient workspace ([`openclaw.json`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/openclaw.json)) describing the model catalog and proxy URL:

```python

# 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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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:

```bash
switchyard launch claude --model switchyard

```

Use a custom deployment with Claude Code:

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

```

Run Codex with default settings:

```bash
switchyard launch codex --model switchyard

```

Disable streaming and add Codex-specific flags:

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

```

Launch OpenClaw with a custom model:

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

```

Pass temperature and other OpenClaw arguments:

```bash
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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/launch_command.py) lines 22-58.

## Key Source Files

| File | Purpose |
|------|---------|
| [`switchyard/cli/launch_command.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/switchyard/cli/launch_command.py) | CLI entry point, argument parsing, dispatcher |
| [`switchyard/cli/launchers/claude_code_launcher.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/switchyard/cli/launchers/claude_code_launcher.py) | Claude Code workflow, env var injection |
| [`switchyard/cli/launchers/codex_cli_launcher.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/switchyard/cli/launchers/codex_cli_launcher.py) | Codex workflow, provider flag construction |
| [`switchyard/cli/launchers/openclaw_launcher.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/switchyard/cli/launchers/openclaw_launcher.py) | OpenClaw workspace creation and execution |
| [`switchyard/cli/launchers/native_server.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/switchyard/cli/launchers/native_server.py) | In-process Rust server startup |
| [`switchyard/cli/launchers/launcher_runtime.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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.