How to Build Switchyard from Source: Complete Installation Guide

To build Switchyard from source, install Rust 1.96.1 and the uv Python package manager, clone the NVIDIA-NeMo/Switchyard repository, compile the Rust workspace with cargo build --release --workspace, and optionally install Python bindings using uv run maturin develop.

Switchyard is a Rust-native proxy that routes LLM traffic and translates between OpenAI and Anthropic APIs. This guide walks through building Switchyard from source using the exact toolchain requirements and build commands defined in the repository source files.

Prerequisites

Before you build Switchyard from source, install the following tools as specified in [docs/getting_started.md](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/docs/getting_started.md) (lines 15‑33):

• Rust 1.96.1 or later (includes rustc, cargo, and rustup)
• uv (the Python package manager)
• Git
• build-essential (Linux only)

Install Rust using the official installer:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Linux, install build essentials:

sudo apt-get install -y build-essential curl

Clone the Repository

Clone the Switchyard repository and navigate into the directory:

git clone https://github.com/NVIDIA-NeMo/Switchyard.git
cd Switchyard

If you plan to contribute, fork the repository first and configure an upstream remote as described in the project CONTRIBUTING guide.

Compile the Rust Workspace

Switchyard uses a Cargo workspace structure with crates such as switchyard-server, libsy, and protocol.

Build Debug Binaries

For development builds:

cargo build --workspace

Build Release Binaries (Recommended)

For optimized production builds:

cargo build --release --workspace

The compiled switchyard-server binary appears at target/release/switchyard-server.

Install the Server Binary Globally

To install directly from the source tree (as documented in [crates/switchyard-server/README.md](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/README.md), lines 56‑60):

cargo install --locked --path crates/switchyard-server

Install the Python Package (Optional)

Switchyard includes a thin Python integration layer in switchyard_rust that loads the native library at runtime. To set up the Python environment:

uv sync
source .venv/bin/activate

To build the PyO3 extension in-place so that import switchyard works:

uv run maturin develop

This workflow matches the development quick-start in [CONTRIBUTING.md](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/CONTRIBUTING.md).

Verify the Build

Run Rust Tests

Execute the full Rust test suite across all workspace crates:

cargo test --workspace

Run Python Tests

Execute Python tests using uv:

uv run pytest tests/ -v

All CI linting and type-checking commands are documented in [CONTRIBUTING.md](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/CONTRIBUTING.md) (lines 65‑81).

Run a Local Server

Create a TOML configuration file (the schema is documented in [docs/getting_started.md](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/docs/getting_started.md), lines 67‑92):

schema_version = 1

[llm_clients.openrouter]
format = "openai_chat"
base_url = "https://openrouter.ai/api/v1"
api_key_env = "OPENROUTER_API_KEY"

[targets.weak]
id = "openai/gpt-4o-mini"
llm_client = "openrouter"

[targets.strong]
id = "openai/gpt-4o"
llm_client = "openrouter"

[routes.smart]
id = "switchyard"
type = "llm_classifier"
mode = "capability"
classifier_target = "weak"
strong_target = "strong"
weak_target = "weak"
base_threshold = 0.5

Set your API key and start the server:

export OPENROUTER_API_KEY="your-openrouter-key"
switchyard-server --config routes.toml --host 127.0.0.1 --port 4000

The server exposes OpenAI-compatible endpoints (/v1/chat/completions, /v1/models, etc.) as detailed in [crates/switchyard-server/README.md](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/README.md) (lines 24‑38).

Summary

• Toolchain: Switchyard requires Rust 1.96.1, uv, and Git to build from source.
• Compilation: Use cargo build --release --workspace to compile the Rust-native proxy and routing algorithms.
• Installation: Install the server binary globally with cargo install --locked --path crates/switchyard-server.
• Python Integration: Run uv sync followed by uv run maturin develop to enable Python bindings.
• Verification: Execute cargo test --workspace and uv run pytest tests/ to validate the build.
• Configuration: Start the server with a TOML config file defining llm_clients, targets, and routes schemas.

Frequently Asked Questions

What is the minimum Rust version required to build Switchyard?

Switchyard requires Rust 1.96.1 or later. This version requirement ensures compatibility with the workspace crates including switchyard-server and libsy. The Getting Started documentation explicitly lists this minimum version to prevent compilation errors with older toolchains.

Do I need Python to run the Switchyard server?

No. The core switchyard-server binary is a standalone Rust executable. Python is only required if you want to use the optional switchyard_rust Python bindings for embedding the router in Python applications or running integration tests that use the Python wrapper.

How do I install the switchyard-server binary globally?

Run cargo install --locked --path crates/switchyard-server from the repository root. This compiles the release binary and copies it to your Cargo bin directory (usually ~/.cargo/bin), making the switchyard-server command available system-wide without manually managing the target/release/ path.

Where is the TOML configuration schema documented?

The TOML schema for routing configurations is documented in two locations: the Getting Started guide at [docs/getting_started.md](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/docs/getting_started.md) (lines 67‑92) provides a complete example with llm_clients, targets, and routes sections, while [crates/switchyard-server/README.md](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/README.md) details server-specific configuration options and endpoint mappings.

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