# How to Build Switchyard from Source: Complete Installation Guide

> Build Switchyard from source with our complete guide. Install Rust and uv, clone the repo, and compile the Rust workspace for a seamless setup.

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

---

**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)](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:

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

```

Install uv:

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

```

On Linux, install build essentials:

```bash
sudo apt-get install -y build-essential curl

```

## Clone the Repository

Clone the Switchyard repository and navigate into the directory:

```bash
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:

```bash
cargo build --workspace

```

### Build Release Binaries (Recommended)

For optimized production builds:

```bash
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)](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/README.md), lines 56‑60):

```bash
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:

```bash
uv sync
source .venv/bin/activate

```

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

```bash
uv run maturin develop

```

This workflow matches the development quick-start in [[`CONTRIBUTING.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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:

```bash
cargo test --workspace

```

### Run Python Tests

Execute Python tests using uv:

```bash
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)](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)](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/docs/getting_started.md), lines 67‑92):

```toml
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:

```bash
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)](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)](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)](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/README.md) details server-specific configuration options and endpoint mappings.