Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust
9.7 KB
Raw Blame

Experimental desktop installation

The desktop app, terminal app, and their installer are experimental. They are outside Switchyard release QA and have no support or compatibility guarantee. Run every cargo desktop command from experimental/switchyard-desktop, which pins its own Rust toolchain and builds as its own Cargo workspace.

Desktop installer

From this directory in a source checkout, run cargo desktop --help for the commands and cargo desktop install --dry-run to preview installation. Run cargo desktop install to build and install the app and server.

If you installed the app before it moved to experimental/switchyard-desktop, run cargo desktop install from this directory once after you update the checkout. Until then, Settings → Update from source fails: the installed updater still builds the app from the root Cargo.toml, which no longer includes it. The failed build stops before it changes installed files or services. Later updates from Settings work again.

The app opens setup on its first launch before creating app and server config files. Existing app settings or a default server config skip setup, including after reinstall. Settings lets you change the selected files or remove app preferences. On Linux, open the installed app with ~/.switchyard/bin/switchyard-desktop --tui. See Desktop setup for these steps. Uninstall keeps settings, history, and recovery copies.

Server Keys

In a server config, each LLM client and decision client names its API key variable with api_key_env. A server you start from a terminal reads those variables from your shell, as it always has. The installed server does not: on macOS launchd starts it, on Linux systemd, and on Windows Task Scheduler. None of them runs your shell, so the installed server never sees the variables that ~/.zshrc or ~/.bashrc exports.

The installed server reads each key from the system credential store instead: macOS Keychain, Windows Credential Manager, or the Linux Secret Service (GNOME Keyring on Ubuntu and GNOME, KDE Wallet on Plasma). A key is saved under its variable name, such as NVIDIA_API_KEY. Before each start, the installed helper reads the keys that the config names and passes them to the server. A saved key replaces any value the service manager passes. If a variable has no saved key, the server does not start, and the server log names the variable.

To save, replace, or remove a key in the desktop app, open Settings → Server keys. Type or paste the key, or choose Import from shell to read the variable once from your login shell. From a terminal on macOS or Linux, run the installed helper:

~/.switchyard/bin/switchyard-desktop-install key status --config ~/.switchyard/composite.toml
~/.switchyard/bin/switchyard-desktop-install key set NVIDIA_API_KEY      # prompts without echo
~/.switchyard/bin/switchyard-desktop-install key import NVIDIA_API_KEY   # reads it from your login shell
~/.switchyard/bin/switchyard-desktop-install key remove NVIDIA_API_KEY

On Windows, the installer puts the helper in %LOCALAPPDATA%\Programs\Switchyard, or %USERPROFILE%\AppData\Local\Programs\Switchyard when LOCALAPPDATA is unset. There key set reads the key from standard input without a prompt, and key import reads the variable from your Windows environment variables. From PowerShell:

$local = if ($env:LOCALAPPDATA) { $env:LOCALAPPDATA } else { "$env:USERPROFILE\AppData\Local" }
$helper = "$local\Programs\Switchyard\switchyard-desktop-install.exe"
& $helper key status --config "$env:USERPROFILE\.switchyard\composite.toml"
[Net.NetworkCredential]::new('', (Read-Host 'Key' -AsSecureString)).Password | & $helper key set NVIDIA_API_KEY
& $helper key import NVIDIA_API_KEY
& $helper key remove NVIDIA_API_KEY

Restart the server after you change a key. If you rename a variable in api_key_env, save a key under the new name. The old key stays saved until you remove it in Keychain Access, Credential Manager, or Seahorse.

cargo desktop install never saves, reads, or changes a key, even when your terminal sets the variable. It checks the config without keys, then lists each variable that has no saved key. On a first install, the server starts after you save those keys in Settings → Server keys and restart it. In the terminal app, press 7 to open the Settings page. There k lists the variables that the config names and whether each has a saved key, s saves a key, and i imports it from your login shell. Press b and then y to restart the server. Uninstalling keeps the saved keys, the config, and history. Switchyard never writes keys to app settings, service definitions, or logs. Model-list keys that you enter in Routes are stored separately.

On macOS, Keychain ties each key to the helper that saved it. Keychain treats a rebuilt helper as a new program, so after cargo desktop install macOS may ask once per key whether to allow switchyard-desktop-install. Choose Always Allow.

On Linux, the login keyring must be unlocked. A desktop login normally unlocks it. When the server service starts after login, it waits up to a minute for the keyring to unlock. Over SSH without a desktop session, or with a window manager that does not unlock the keyring, the server does not start and its log says the keyring is locked.

Linux Codex Service

This setup is for single-user Linux machines. It requires a systemd user session, the Rust toolchain that this directory pins, and Codex CLI 0.134.0 or newer logged in with a ChatGPT account. Another user's process could take the local port while the service is stopped and receive your login and prompts.

From this directory in a checkout, preview or install the service:

cargo desktop install --dry-run
cargo desktop install
systemctl --user status switchyard
codex -p sy

The installer builds and installs ~/.switchyard/bin/switchyard-server and ~/.switchyard/bin/switchyard-desktop. Run the same command to reinstall from the current checkout; update the checkout first to install newer code. Run ~/.switchyard/bin/switchyard-desktop --tui to open the terminal app. It creates ~/.switchyard/composite.toml if missing and keeps existing edits. It replaces ~/.config/systemd/user/switchyard.service and restarts the service. It writes ~/.codex/sy.config.toml, backing up a changed profile first. It leaves shell rc files unchanged. Use codex -p sy to select the profile; codex login and other management commands still work as usual. The profile format requires Codex 0.134.0 or newer. Remove any old [profiles.sy] table from ~/.codex/config.toml before using it.

Set SY_HOME or SY_PORT to change the server directory or port (default 4123). SY_HOME must be an absolute UTF-8 path without ASCII control characters. SY_PORT must be a number from 1 to 65535. XDG_CONFIG_HOME and CODEX_HOME set the systemd and Codex config directories.

Read server logs with journalctl --user -u switchyard. Routing records are stored in ~/.switchyard/routing.jsonl. Use systemctl --user edit switchyard for service changes that survive reinstalling.

Remove the service and profile with cargo desktop uninstall. This also removes marked Codex aliases left by older installs from existing .bashrc and .zshrc files. If upgrading an older install, uninstall first and run unalias codex in any open shell. The server directory, routing records, profile backups, and systemd drop-in files stay in place. Uninstall uses the recorded installation. Conflicting environment overrides require cargo desktop uninstall --settings FILE to select it explicitly.

Windows Desktop App

From PowerShell in this directory, run:

cargo desktop install --dry-run
cargo desktop install

Windows needs the Rust MSVC toolchain, Visual Studio C++ build tools, and WebView2. The installer uses Task Scheduler for the current logged-in user. It installs executables in %LOCALAPPDATA%\Programs\Switchyard, falling back to %USERPROFILE%\AppData\Local\Programs\Switchyard when LOCALAPPDATA is unset. It saves that location and adds a Start menu shortcut. Two independent tasks start the server and desktop app after login with ordinary user privileges. Quitting the app leaves the server running.

Run cargo desktop install again to build and install the current checkout. This Cargo command waits for installation to finish. The app's source update uses the saved checkout and runs from a temporary Rust executable so Windows can release and replace the installed files; read SY_HOME\logs\update.log for its progress and errors. The installed installer cannot install, update, or uninstall its own installation, because Windows keeps a running program from being replaced. Use cargo desktop from this directory in the source checkout instead. The installer builds and validates before stopping the tasks. If a binary replacement fails, it tries to restore the previous binaries. If restoration also fails, the error names the directory containing recovery files. Rerun installation if a later task or settings operation fails; the complete installation is not one transaction.

Settings, server config, and routing history stay in SY_HOME, which defaults to %USERPROFILE%\.switchyard. Named accounts stay in %USERPROFILE%\.switchyard\accounts whatever SY_HOME is. Server and app logs are in SY_HOME\logs. Model-list keys entered in Routes are saved in the current user's Windows Credential Manager. Coding tools keep their own login files.

Use cargo desktop uninstall to stop and remove both tasks, the shortcut, and the installed executables. Uninstall preserves settings, accounts, and history, and makes a recovery copy of the Codex profile before removing it.