Switchyard Requirements: Rust Toolchain, Python Version, and System Prerequisites

To run Switchyard, you need Rust 1.96.1, Python 3.10 or higher, and standard system build tools including gcc, make, curl, and git.

Switchyard is a Rust-centric routing engine with a thin Python integration layer maintained in the NVIDIA-NeMo/Switchyard repository. The project enforces strict version pinning to ensure reproducible builds across its core algorithm crates, stand-alone server, and PyO3-based Python façade.

Core Switchyard Requirements

Rust Toolchain Version 1.96.1

The repository pins the exact Rust compiler version in rust-toolchain.toml. All crates in the workspace inherit rust-version = "1.96" via rust-version.workspace = true declarations in their respective Cargo.toml files.

You must install the specific channel to compile any component, including switchyard-libsy, switchyard-protocol, and switchyard-server. Using rustup ensures you match the exact bytecode generation and dependency resolution tested in CI.

# Install the exact required toolchain

rustup toolchain install 1.96.1
rustup default 1.96.1

# Verify installation

rustc --version  # Expected: 1.96.1

Python Runtime 3.10 or Higher

Although Switchyard’s performance-critical logic is native Rust, the optional Python bindings require CPython 3.10+. This is declared in pyproject.toml under requires-python = ">=3.10".

The switchyard_rust package uses PyO3 to expose the compiled library to Python. When importing the module, Python loads the native binary built by the Rust toolchain specified above.

python --version  # Must print 3.10.x or higher

System Build Tools

You need a standard Unix-like build environment to compile Rust and its native dependencies. According to docs/getting_started.md, the prerequisites include:

• Git for cloning the repository
• gcc or clang for linking native code
• make and curl for auxiliary build steps
• pkg-config (on Linux) for locating system libraries

These tools compile the aws-lc-rs cryptographic primitives and rustls TLS stack required by the server crate.

Optional but Recommended Dependencies

uv for Python Environment Management

While optional, the maintainers recommend installing uv to manage Python virtual environments and run repository tooling. The Getting Started guide explicitly mentions uv for linting and CI consistency.

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

TLS Libraries for Secure Connections

The stand-alone server (switchyard-server) declared in crates/switchyard-server/Cargo.toml links against rustls and aws-lc-rs for HTTPS support. These Rust crates bundle their own cryptographic implementations, but they require system OpenSSL headers only if you enable specific legacy features. For most deployments, the standard system TLS libraries suffice.

Architecture and Crate Structure

Understanding the dependency flow clarifies why the version requirements are strict:

• Core libraries: switchyard-libsy, switchyard-protocol, and switchyard-translation contain the routing algorithms. They all reference the workspace Rust version.
• Server binary: switchyard-server is a native executable using axum and axum-server for async HTTP handling. It depends on the core libraries and inherits the same compiler constraints.
• Python bindings: crates/switchyard-py/Cargo.toml defines the PyO3 bridge. The resulting wheel contains a shared library compiled against Rust 1.96.1, which Python loads at runtime.

Because the workspace uses a shared rust-toolchain.toml, any deviation from the pinned 1.96.1 channel risks compilation failures in dependencies like aws-lc-rs.

Step-by-Step Installation Guide

Installing the Rust Toolchain

Execute the standard rustup installation script, then activate the pinned toolchain:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustup toolchain install 1.96.1
rustup default 1.96.1

Setting Up Python

Ensure your environment meets the minimum version before installing the Python package:

# Using uv (recommended)

uv venv --python 3.10
source .venv/bin/activate

# Or using standard Python

python3.10 -m venv venv
source venv/bin/activate

Building the Switchyard Server

Compile and install the server binary directly from the workspace:

cargo install --locked switchyard-server
switchyard-server --help

The --locked flag respects the Cargo.lock file from the repository, ensuring you use the exact dependency versions validated against Rust 1.96.1.

Configuring Environment Variables

To run a functional server, export your API keys. The README and docs/getting_started.md specify OPENROUTER_API_KEY as a common requirement for routing to external providers:

export OPENROUTER_API_KEY="sk-or-v1-..."
switchyard-server --config routes.toml --host 127.0.0.1 --port 4000

Use the --dry-run flag to validate configuration without initiating network connections.

Summary

• Switchyard requires Rust 1.96.1 exactly, pinned in rust-toolchain.toml and enforced across all workspace crates.
• Python 3.10+ is required only if using the optional Python façade via PyO3.
• Standard system build tools (gcc, make, git) are necessary for compiling native dependencies.
• The optional uv tool streamlines Python environment management for repository tooling.
• Environment variables like OPENROUTER_API_KEY configure runtime routing behavior but are not build-time requirements.

Frequently Asked Questions

What Rust version does Switchyard require?

Switchyard requires Rust 1.96.1 exactly. The repository pins this version in rust-toolchain.toml to ensure consistent compilation of cryptographic libraries and async runtime code. Installing the latest stable Rust will not suffice; you must install the specific 1.96.1 channel via rustup.

Can I use Python 3.9 with Switchyard?

No. The pyproject.toml file explicitly declares requires-python = ">=3.10". The PyO3 bindings in crates/switchyard-py/Cargo.toml target the CPython 3.10 API, and earlier versions will fail to load the compiled extension module.

Is the Python interface required to run the Switchyard server?

No. The stand-alone server compiled from crates/switchyard-server is a pure Rust binary that requires no Python runtime. You only need Python if you intend to embed Switchyard as a library within a Python application using the switchyard_rust package.

What environment variables are mandatory to start the server?

No environment variables are strictly required for compilation, but runtime functionality requires API keys. The standard quick-start configuration expects OPENROUTER_API_KEY to authenticate requests to external LLM providers. Without this variable, the server will start but fail to route inference requests, logging authentication errors to stderr.

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