# How to Set Up TLS Encryption for the Switchyard Server

> Secure your Switchyard server with TLS encryption. Learn how to set up TLS using the cert and key flags for robust server security. Easy to follow guide.

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

---

**To enable TLS encryption for the Switchyard server, provide the `--tls-cert` and `--tls-key` flags pointing to PEM-encoded certificate files when starting the server, which activates the built-in `axum-server` TLS backend.**

The NVIDIA-NeMo/Switchyard repository provides a high-performance routing layer for AI model inference, and securing client-to-server communication is critical for production deployments. Setting up TLS encryption for the Switchyard server requires only two additional CLI arguments, but understanding the underlying implementation in [`crates/switchyard-server/src/lib.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/lib.rs) ensures proper certificate management and troubleshooting.

## How TLS Works in Switchyard

Switchyard's TLS support is implemented directly in the **switchyard-server** binary using the `axum-server` crate with the **`tls-rustls`** feature enabled. When TLS options are supplied, the server constructs a `RustlsConfig` using `RustlsConfig::from_pem_file` and wraps the TCP listener with `axum_server::from_tcp_rustls` to serve HTTPS traffic.

The core logic resides in [`crates/switchyard-server/src/lib.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/lib.rs) within the `serve_tls` function (lines 302-391). Here, the server checks for the `ServerRunOptions.tls` field, which contains a `TlsOptions` struct holding the certificate and key paths. If TLS configuration is present, the server invokes the asynchronous `serve_tls` function; otherwise, it falls back to plain HTTP via the standard `serve` function.

## Prerequisites for TLS Encryption

Before configuring the server, you must obtain or generate a PEM-encoded certificate and private key pair. Switchyard requires:

- A **PEM-encoded X.509 certificate** (commonly `cert.pem` or `server.crt`)
- A **PEM-encoded private key** (commonly `key.pem` or `server.key`)
- Both files must be readable by the user running the `switchyard-server` process

For development environments, you can generate a self-signed certificate. Production deployments should use certificates issued by a trusted Certificate Authority (CA).

## Step-by-Step TLS Configuration

### Generate a Self-Signed Certificate

For testing purposes, use OpenSSL to create a 2048-bit RSA key pair valid for 365 days:

```bash
openssl req -newkey rsa:2048 -nodes -keyout key.pem \
    -x509 -days 365 -out cert.pem \
    -subj "/CN=my-switchyard"

```

Move these files to a secure directory with restricted permissions:

```bash
sudo mkdir -p /etc/switchyard
sudo cp cert.pem /etc/switchyard/cert.pem
sudo cp key.pem /etc/switchyard/key.pem
sudo chmod 600 /etc/switchyard/key.pem

```

### Launch the Server with TLS Flags

The command-line interface defined in [`crates/switchyard-server/src/cli.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/cli.rs) exposes two mutually required flags: `--tls-cert` and `--tls-key`. You must provide both arguments simultaneously; the parser enforces this dependency via `requires = "tls_key"` and `requires = "tls_cert"` constraints.

Start the server with TLS enabled on port 443:

```bash
switchyard-server \
    --addr 0.0.0.0:443 \
    --tls-cert /etc/switchyard/cert.pem \
    --tls-key /etc/switchyard/key.pem \
    --config /etc/switchyard/config.toml

```

The server initializes the TLS context by calling `RustlsConfig::from_pem_file` with the provided paths, then binds the Axum router to the encrypted listener.

## Systemd Deployment with TLS

The repository includes a sample systemd unit file at `dev-server/switchyard.service` that demonstrates production deployment with TLS enabled. The file already includes placeholder flags for certificate paths (lines 5-6).

Copy and customize the service file:

```bash
sudo cp dev-server/switchyard.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now switchyard.service

```

Ensure the `ExecStart` line in your service file includes the full paths to your certificate and key:

```ini
ExecStart=/usr/local/bin/switchyard-server \
    --addr 0.0.0.0:443 \
    --tls-cert /etc/switchyard/cert.pem \
    --tls-key /etc/switchyard/key.pem \
    --config /etc/switchyard/config.toml

```

## Summary

- Switchyard implements TLS via the `axum-server` crate with Rustls, requiring only `--tls-cert` and `--tls-key` flags to enable HTTPS.
- The TLS logic lives in [`crates/switchyard-server/src/lib.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/lib.rs), specifically within the `serve_tls` function and `TlsOptions` struct.
- Certificate and key files must be in PEM format and readable by the server process.
- The CLI enforces mutual dependency between `--tls-cert` and `--tls-key` to prevent partial TLS configuration.
- Production deployments can use the sample systemd unit at `dev-server/switchyard.service` for persistent encrypted service.

## Frequently Asked Questions

### What certificate formats does Switchyard support?

Switchyard accepts standard PEM-encoded X.509 certificates and PKCS#8 or RSA private keys. The server uses `RustlsConfig::from_pem_file` internally, which parses the certificate chain and key files according to Rustls specifications. Ensure your certificate file includes the full chain if using an intermediate CA.

### What happens if I provide only one TLS flag?

The command-line parser will exit with an error before the server starts. Because the flags are configured with mutual requirements in [`crates/switchyard-server/src/cli.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/cli.rs), providing only `--tls-cert` without `--tls-key` (or vice versa) triggers a Clap validation error indicating that the missing argument is required.

### Can I use Let's Encrypt certificates with Switchyard?

Yes. Switchyard accepts any PEM-encoded certificate, including those from Let's Encrypt. Ensure your certificate file contains the full chain (certificate plus intermediate) and the key file contains the unencrypted private key. Reference these files using the `--tls-cert` and `--tls-key` flags when starting the server.

### Where are the TLS CLI flags defined?

The `--tls-cert` and `--tls-key` arguments are defined in [`crates/switchyard-server/src/cli.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/cli.rs). They are marked as mutually required using Clap's `requires` attribute, ensuring the parser rejects invocations that specify only one flag.