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
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0
//! The source installer owns app bundles, service definitions, and installation metadata.
use serde::{Deserialize, Serialize};
use std::{
fs,
io::{Read, Write},
net::{SocketAddr, TcpStream},
path::{Path, PathBuf},
process::{Command, Stdio},
thread,
time::{Duration, Instant, SystemTime, UNIX_EPOCH},
};
use switchyard_costs::Pricing;
use crate::config::{
self, Config, DEFAULT_PORT, DESKTOP_CONFIG, HOME_DIR, PRICES_FILE, ROUTING_LOG, SERVER_CONFIG,
};
pub mod credentials;
// Linux and any other system without launchd or Task Scheduler use systemd; execute rejects
// unsupported systems before they change anything.
#[cfg(not(any(target_os = "macos", windows)))]
mod linux;
#[cfg(not(any(target_os = "macos", windows)))]
use linux as platform;
#[cfg(target_os = "macos")]
mod macos;
#[cfg(target_os = "macos")]
use macos as platform;
#[cfg(windows)]
pub mod windows;
#[cfg(windows)]
use windows as platform;
pub fn executable_name(name: &str) -> String {
format!("{name}{}", std::env::consts::EXE_SUFFIX)
}
pub const BUNDLED_CONFIG: &str = include_str!("../../../scripts/config/composite.toml");
const UPDATE_LOCK: &str = ".switchyard-desktop-update.lock";
const PORT_ERROR: &str = "SY_PORT must be a number from 1 to 65535.";
#[derive(Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Settings {
pub home: PathBuf,
pub sy_home: PathBuf,
pub codex_home: PathBuf,
pub service_dir: PathBuf,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub app_dir: Option<PathBuf>,
pub source: PathBuf,
pub cargo: PathBuf,
pub port: u16,
pub profile: String,
pub model: String,
}
impl Settings {
pub fn for_uninstall() -> Result<Self, String> {
let defaults = Self::from_env()?;
let recorded = defaults.install_record();
if !present(&recorded)? {
return Ok(defaults);
}
let selected = Self::load(&recorded)?;
for (name, differs) in [
(
"SY_HOME",
defaults.sy_home.as_os_str() != selected.sy_home.as_os_str(),
),
(
"CODEX_HOME",
defaults.codex_home.as_os_str() != selected.codex_home.as_os_str(),
),
("SY_PROFILE", defaults.profile != selected.profile),
] {
if differs && std::env::var_os(name).is_some() {
return Err(format!(
"{name} differs from the recorded installation at {}. \
Use uninstall --settings FILE to choose a different installation.",
recorded.display()
));
}
}
Ok(selected)
}
pub fn from_env() -> Result<Self, String> {
let home = config::home_dir()?;
let path = |name, default| std::env::var_os(name).map(PathBuf::from).unwrap_or(default);
let value = |name: &str, default: &str| {
std::env::var(name).or_else(|error| match error {
std::env::VarError::NotPresent => Ok(default.to_owned()),
std::env::VarError::NotUnicode(_) => Err(format!("{name} must be UTF-8.")),
})
};
let port = value("SY_PORT", &DEFAULT_PORT.to_string())?;
if !port.bytes().all(|b| b.is_ascii_digit()) {
return Err(PORT_ERROR.into());
}
let settings = Self {
sy_home: path("SY_HOME", home.join(HOME_DIR)),
codex_home: path("CODEX_HOME", home.join(".codex")),
service_dir: if cfg!(target_os = "macos") {
home.join("Library/LaunchAgents")
} else if cfg!(windows) {
path("APPDATA", home.join("AppData/Roaming"))
.join("Microsoft/Windows/Start Menu/Programs")
} else {
path("XDG_CONFIG_HOME", home.join(".config")).join("systemd/user")
},
app_dir: cfg!(windows).then(|| {
path("LOCALAPPDATA", home.join("AppData/Local")).join("Programs/Switchyard")
}),
home,
source: Path::new(env!("CARGO_MANIFEST_DIR"))
.parent()
.and_then(Path::parent)
.ok_or("Could not find the source checkout.")?
.to_path_buf(),
cargo: PathBuf::from(env!("CARGO")),
port: port.parse().map_err(|_| PORT_ERROR)?,
profile: value("SY_PROFILE", "sy")?,
model: value("SY_MODEL", "composite-gpt-6-sol-gpt-6-luna")?,
};
settings.validate()?;
Ok(settings)
}
pub fn load(file: &Path) -> Result<Self, String> {
let text = fs::read_to_string(file).map_err(|e| format!("Read {}: {e}", file.display()))?;
let settings: Self =
toml::from_str(&text).map_err(|e| format!("Parse {}: {e}", file.display()))?;
settings.validate()?;
Ok(settings)
}
pub fn validate(&self) -> Result<(), String> {
let profile = self.profile.as_bytes();
if !profile.first().is_some_and(u8::is_ascii_alphanumeric)
|| profile.len() > 128
|| !profile
.iter()
.all(|&b| b.is_ascii_alphanumeric() || b == b'_' || b == b'-')
{
return Err(
"SY_PROFILE must start with an ASCII letter or digit and contain only ASCII \
letters, digits, underscores, or hyphens, up to 128 characters."
.into(),
);
}
if self.model.is_empty() || self.model.bytes().any(|b| b.is_ascii_control()) {
return Err(
"SY_MODEL must be a nonempty public route ID without ASCII control characters."
.into(),
);
}
if self.port == 0 {
return Err(PORT_ERROR.into());
}
for (name, path) in [
("HOME", &self.home),
("SY_HOME", &self.sy_home),
("CODEX_HOME", &self.codex_home),
("service directory", &self.service_dir),
("source checkout", &self.source),
("Cargo executable", &self.cargo),
]
.into_iter()
.chain(self.app_dir.as_ref().map(|path| ("LOCALAPPDATA", path)))
{
if !path.is_absolute()
|| path
.to_str()
.is_none_or(|s| s.bytes().any(|b| b.is_ascii_control()))
{
return Err(format!(
"{name} must be an absolute UTF-8 path without ASCII control characters."
));
}
}
Ok(())
}
pub fn app(&self) -> PathBuf {
self.home.join("Applications/Switchyard.app")
}
pub fn bin_dir(&self) -> PathBuf {
if cfg!(windows) {
self.app_dir
.clone()
.unwrap_or_else(|| self.home.join("AppData/Local/Programs/Switchyard"))
} else {
self.sy_home.join("bin")
}
}
pub fn binary(&self, name: &str) -> PathBuf {
self.bin_dir().join(executable_name(name))
}
pub fn desktop_settings(&self) -> PathBuf {
self.sy_home.join(DESKTOP_CONFIG)
}
/// This optional file overrides bundled rates for the server and app baseline.
pub fn prices_file(&self) -> PathBuf {
self.sy_home.join(PRICES_FILE)
}
/// This method builds the installed server command with any existing price override.
/// The caller configures and starts the process.
pub fn server_command(&self) -> Result<Command, String> {
let config = Config::load(&self.desktop_settings())?;
let mut command = Command::new(self.binary("switchyard-server"));
command.arg("--config").arg(&config.config_file);
let url = crate::health::validate_url(&config.server_url)?;
command.args(["--host", "127.0.0.1"]);
command.arg("--port").arg(
url.port_or_known_default()
.ok_or("Missing server port.")?
.to_string(),
);
command.arg("--routing-log-file").arg(&config.routing_log);
if let Some(prices) = &config.prices_file {
command.arg("--pricing-file").arg(prices);
}
Ok(command)
}
fn profile_file(&self) -> PathBuf {
self.codex_home
.join(format!("{}.config.toml", self.profile))
}
fn release(&self, binary: &str) -> PathBuf {
self.source
.join("target/release")
.join(executable_name(binary))
}
/// Uninstall reads this copy of the settings to find the installation.
fn install_record(&self) -> PathBuf {
self.home.join(".switchyard-desktop-install.toml")
}
}
/// The app reads this metadata to retain a custom SY_HOME when Finder or a Windows shortcut starts it.
pub fn bundle_metadata(executable: &Path) -> PathBuf {
// Windows keeps the metadata beside the executable; macOS keeps it in the bundle's Resources.
let (levels, file) = if cfg!(windows) {
(1, "install.toml")
} else {
(2, "Resources/install.toml")
};
executable
.ancestors()
.nth(levels)
.unwrap_or(Path::new("."))
.join(file)
}
/// The updater runs separately because installation restarts the app that requested it.
pub fn start_update(settings_file: &Path) -> Result<PathBuf, String> {
let settings = Settings::load(settings_file)?;
let guard = update_lock(&settings)?;
if update_starting(&update_status(settings_file)?) {
return Err(
"A Switchyard update is already starting. View its progress in Settings.".into(),
);
}
set_update_state(
&settings,
"starting",
"start",
"Starting the source update.",
)?;
let log_path = settings.sy_home.join("logs/update.log");
let log = fs::OpenOptions::new()
.create(true)
.append(true)
.open(&log_path)
.map_err(err)?;
let error_log = log.try_clone().map_err(err)?;
#[cfg(windows)]
let updater_path = windows::temporary_updater(&settings.binary("switchyard-desktop-install"))?;
#[cfg(not(windows))]
let updater_path = settings.binary("switchyard-desktop-install");
let mut updater = Command::new(&updater_path);
#[cfg(windows)]
windows::hide_console(&mut updater);
#[cfg(unix)]
{
use std::os::unix::process::CommandExt;
// A separate process group keeps launchd from stopping the updater with the app.
updater.process_group(0);
}
// The child must acquire the update lock, so the parent releases it before spawning.
drop(guard);
let mut child = updater
.args(["update", "--settings"])
.arg(settings_file)
.stdin(Stdio::null())
.stdout(log)
.stderr(error_log)
.spawn()
.map_err(|e| {
let message = format!("Could not start the source update: {e}");
let _ = set_update_state(&settings, "failed", "start", &message);
message
})?;
#[cfg(windows)]
updater_path.keep().map_err(err)?;
// This thread reaps the updater if it exits before installation stops the app.
thread::spawn(move || {
let _ = child.wait();
});
Ok(log_path)
}
pub fn execute(settings: &Settings, action: &str, dry_run: bool) -> Result<(), String> {
settings.validate()?;
if !matches!(action, "install" | "uninstall" | "update") {
return Err("Choose install, update, or uninstall.".into());
}
if !cfg!(any(target_os = "macos", target_os = "linux", windows)) {
return Err("Installation supports macOS, Linux, and Windows.".into());
}
if dry_run {
println!("{}", installation_plan(settings, action));
return Ok(());
}
if action == "uninstall" {
return uninstall(settings);
}
let _job = update_lock(settings)?;
if action == "update" {
set_update_state(settings, "running", "build", "Building the app and server.")?;
}
match install(settings, action == "update") {
Ok(None) => set_update_state(
settings,
"completed",
"completed",
"Installed the app and server. Switchyard is ready.",
),
Ok(Some(warning)) => set_update_state(settings, "warning", "readiness", &warning),
Err(error) => {
// The failure keeps the stage that the install last recorded.
if settings.sy_home.exists() {
let stage = update_status(&settings.sy_home.join("install.toml"))
.ok()
.and_then(|s| s["stage"].as_str().map(str::to_owned))
.unwrap_or_else(|| "installation".into());
let _ = set_update_state(settings, "failed", &stage, &error);
}
Err(error)
}
}
}
// The persistent file keeps concurrent commands locking the same inode; exit releases the lock.
fn lock(path: &Path, busy: impl FnOnce(fs::TryLockError) -> String) -> Result<fs::File, String> {
let file = fs::OpenOptions::new()
.create(true)
.truncate(false)
.read(true)
.write(true)
.open(path)
.map_err(err)?;
file.try_lock().map_err(busy)?;
Ok(file)
}
fn update_lock(settings: &Settings) -> Result<fs::File, String> {
lock(&settings.home.join(UPDATE_LOCK), |_| {
"A Switchyard update is already running. Open Settings to view its progress.".into()
})
}
fn lock_installation(s: &Settings) -> Result<fs::File, String> {
lock(&s.home.join(".switchyard-desktop-install.lock"), |e| {
format!("Could not lock the desktop installation: {e}")
})
}
fn set_update_state(
settings: &Settings,
state: &str,
stage: &str,
message: &str,
) -> Result<(), String> {
let updated_at = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map_err(err)?
.as_secs();
let record = serde_json::json!({"state": state, "stage": stage, "message": message,
"source": settings.source, "updated_at": updated_at});
write(
&settings.sy_home.join("update-status.toml"),
toml::to_string(&record).map_err(err)?.as_bytes(),
false,
)
}
// A marker under 10 seconds old marks the child as starting before it acquires the lock.
fn update_starting(record: &serde_json::Value) -> bool {
record["state"] == "starting"
&& record["updated_at"].as_u64().is_some_and(|stamp| {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.is_ok_and(|now| now.as_secs().saturating_sub(stamp) < 10)
})
}
pub fn update_status(settings_file: &Path) -> Result<serde_json::Value, String> {
let settings = Settings::load(settings_file)?;
let Some(text) = read_optional(&settings.sy_home.join("update-status.toml")).map_err(err)?
else {
return Ok(serde_json::json!({"state":"idle"}));
};
let value: toml::Value = toml::from_str(&text).map_err(err)?;
let mut record = serde_json::to_value(value).map_err(err)?;
if !update_starting(&record)
&& matches!(record["state"].as_str(), Some("starting" | "running"))
&& let Ok(lock) = fs::OpenOptions::new()
.read(true)
.write(true)
.open(settings.home.join(UPDATE_LOCK))
&& lock.try_lock().is_ok()
{
record["state"] = serde_json::json!("interrupted");
record["message"] = serde_json::json!(
"The update stopped before recording completion. Open the update log, then retry."
);
}
Ok(record)
}
pub fn preview_update(settings_file: &Path) -> Result<serde_json::Value, String> {
let settings = Settings::load(settings_file)?;
let git = |args: &[&str]| -> String {
let mut command = Command::new("git");
#[cfg(windows)]
windows::hide_console(&mut command);
command
.arg("-C")
.arg(&settings.source)
.args(args)
.output()
.ok()
.filter(|o| o.status.success())
.map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
.unwrap_or_else(|| "Unavailable".into())
};
Ok(
serde_json::json!({"source":settings.source,"revision":git(&["rev-parse","HEAD"]),"branch":git(&["branch","--show-current"]),"changes":git(&["status","--short"]),"plan":installation_plan(&settings,"update"),"status":update_status(settings_file)?}),
)
}
fn installation_plan(s: &Settings, action: &str) -> String {
let removing = action == "uninstall";
let needs_setup = !removing && matches!(config::needs_setup(&s.desktop_settings()), Ok(true));
let pick = |remove, install| if removing { remove } else { install };
let app = if cfg!(target_os = "macos") {
"macOS desktop app"
} else if cfg!(windows) {
"Windows desktop app"
} else {
"Linux terminal app"
};
let profile = s.profile_file();
let profile_action = if removing {
"Preserve recovery copy, then remove"
} else if needs_setup {
"Defer until after setup:"
} else if !profile.exists() {
"Create"
} else if action == "update" {
"Preserve"
} else {
"Back up, then update"
};
let binaries = if !removing {
"Replace"
} else if cfg!(windows) {
"Remove"
} else {
"Preserve"
};
let mut rows = vec![
format!(
"{} {app} and local server from {}",
pick("Remove", "Build and install"),
s.source.display()
),
format!("Route: {} · Server: http://127.0.0.1:{}", s.model, s.port),
format!(
"{} service definitions in {}. The server {}.",
pick("Remove", "Replace"),
s.service_dir.display(),
if needs_setup {
"will wait for setup before starting"
} else {
pick("will stop", "will restart after build and validation")
}
),
];
for (path, label) in [
(s.desktop_settings(), "app settings"),
(s.sy_home.join(SERVER_CONFIG), "server config"),
(s.sy_home.join(ROUTING_LOG), "usage history"),
] {
let verb = if needs_setup {
"Defer until setup"
} else if removing || path.exists() {
"Preserve"
} else {
"Create"
};
rows.push(format!("{verb} {label}: {}", path.display()));
}
if s.prices_file().exists() {
rows.push(format!(
"Preserve model price override: {}",
s.prices_file().display()
));
}
rows.push(format!(
"{profile_action} Codex profile: {}",
profile.display()
));
rows.push(format!("{binaries} binaries: {}", s.bin_dir().display()));
rows.push(format!(
"Preserve accounts and logs: {}",
s.sy_home.display()
));
if cfg!(target_os = "macos") {
rows.push(format!(
"{} app bundle: {}",
pick("Remove", "Replace"),
s.app().display()
));
}
rows.push(
"Preview changes no files. Build prerequisites, full server config validation, \
and readiness are checked during installation."
.into(),
);
if removing {
rows.extend(removal_notes(s));
}
rows.join("\n")
}
/// Lists the coding-tool files that uninstall leaves in place for the user to review.
fn removal_notes(s: &Settings) -> Vec<String> {
let mut destinations = vec![
s.codex_home.join("sy.config.toml"),
s.codex_home.join("config.toml"),
s.home.join(".claude/settings.json"),
s.home.join(".pi/agent/models.json"),
s.home.join(".pi/agent/settings.json"),
];
for (tool, file) in [("codex", "config.toml"), ("claude", "settings.json")] {
let root = s.home.join(".switchyard/accounts").join(tool);
// symlink_metadata does not follow a symlink, so a linked accounts directory is skipped.
if fs::symlink_metadata(&root).is_ok_and(|m| m.is_dir())
&& let Ok(accounts) = fs::read_dir(&root)
{
let accounts = accounts
.flatten()
.filter(|a| a.file_type().is_ok_and(|t| t.is_dir()));
destinations.extend(accounts.map(|account| account.path().join(file)));
}
}
let mut notes = Vec::new();
for destination in destinations {
let saved = ["switchyard-original", "switchyard-original-missing"]
.iter()
.any(|suffix| PathBuf::from(format!("{}.{suffix}", destination.display())).exists());
if saved {
notes.push(format!(
"Preserve coding-tool destination with a Switchyard backup: {}. \
Restore it in Connect tools before removal.",
destination.display()
));
}
}
notes.push("Custom destinations outside these known locations are not inventoried.".into());
notes.push(
"Restore routing from Connect tools before uninstalling. \
Custom and account tool settings are preserved and may still point at this server."
.into(),
);
notes
}
fn wait_for_health(port: u16) -> bool {
let deadline = Instant::now() + Duration::from_secs(10);
let address: SocketAddr = ([127, 0, 0, 1], port).into();
while Instant::now() < deadline {
if let Ok(mut stream) = TcpStream::connect_timeout(&address, Duration::from_millis(250)) {
let _ = stream.set_read_timeout(Some(Duration::from_millis(300)));
let _ = stream.set_write_timeout(Some(Duration::from_millis(300)));
if write!(
stream,
"GET /health HTTP/1.1\r\nHost: 127.0.0.1:{port}\r\nConnection: close\r\n\r\n"
)
.is_ok()
{
let mut bytes = [0; 8192];
let mut used = 0;
let mut complete = false;
while used < bytes.len() {
let Some(remaining) = deadline.checked_duration_since(Instant::now()) else {
break;
};
if remaining.is_zero()
|| stream
.set_read_timeout(Some(remaining.min(Duration::from_millis(300))))
.is_err()
{
break;
}
match stream.read(&mut bytes[used..]) {
Ok(0) => {
complete = true;
break;
}
Ok(count) => used += count,
Err(error) if error.kind() == std::io::ErrorKind::Interrupted => continue,
Err(_) => break,
}
}
if (complete || used == bytes.len())
&& let Ok(response) = std::str::from_utf8(&bytes[..used])
&& let Some((headers, body)) = response.split_once("\r\n\r\n")
&& headers
.lines()
.next()
.and_then(|line| line.split_whitespace().nth(1))
== Some("200")
&& serde_json::from_str::<serde_json::Value>(body)
.is_ok_and(|v| v["status"] == "ok")
{
return true;
}
}
}
thread::sleep(Duration::from_millis(200));
}
false
}
fn run(command: &mut Command) -> Result<(), String> {
#[cfg(windows)]
windows::hide_console(command);
let invocation = format!(
"{:?} {:?}",
command.get_program(),
command.get_args().collect::<Vec<_>>()
);
println!("Running {invocation}");
let status = command
.status()
.map_err(|e| format!("Could not run {invocation}: {e}"))?;
if status.success() {
Ok(())
} else {
Err(format!("{invocation} exited with {status}"))
}
}
fn err(error: impl std::fmt::Display) -> String {
error.to_string()
}
fn present(path: &Path) -> Result<bool, String> {
path.try_exists().map_err(err)
}
/// Reads a text file; a missing file is `None`.
fn read_optional(path: &Path) -> std::io::Result<Option<String>> {
match fs::read_to_string(path) {
Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
result => result.map(Some),
}
}
// Atomic replacement keeps existing executables readable while an update is staged.
fn write(path: &Path, bytes: &[u8], executable: bool) -> Result<(), String> {
let parent = path
.parent()
.ok_or("The destination has no parent directory.")?;
fs::create_dir_all(parent).map_err(err)?;
let mut temp = tempfile::NamedTempFile::new_in(parent).map_err(err)?;
temp.write_all(bytes).map_err(err)?;
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
let mode = if executable { 0o755 } else { 0o600 };
temp.as_file()
.set_permissions(fs::Permissions::from_mode(mode))
.map_err(err)?;
}
#[cfg(not(unix))]
let _ = executable;
temp.as_file().sync_all().map_err(err)?;
temp.persist(path)
.map_err(|e| format!("Write {}: {e}", path.display()))?;
Ok(())
}
fn write_once(path: &Path, text: &str) -> Result<(), String> {
if present(path)? {
return Ok(());
}
write(path, text.as_bytes(), false)
}
fn backup(path: &Path, label: &str) -> Result<(), String> {
let name = path.file_name().ok_or("Missing file name.")?;
let parent = path.parent().ok_or("Missing parent directory.")?;
let mut copy = tempfile::Builder::new()
.prefix(&format!("{}.{label}.", name.to_string_lossy()))
.tempfile_in(parent)
.map_err(err)?;
copy.write_all(&fs::read(path).map_err(err)?).map_err(err)?;
copy.as_file().sync_all().map_err(err)?;
let (_, saved) = copy.keep().map_err(err)?;
println!("Preserved {} at {}", path.display(), saved.display());
Ok(())
}
fn remove(path: &Path) -> Result<(), String> {
match fs::remove_file(path) {
Ok(()) => Ok(()),
Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
Err(e) => Err(format!("Remove {}: {e}", path.display())),
}
}
/// What an install gathers and checks before it changes the installation.
struct Prepared {
needs_setup: bool,
/// The Codex profile to save.
profile: String,
/// App settings rewritten for a new port, when the port changes.
desktop_settings: Option<String>,
/// API key variables in the server config that have no saved key.
missing_keys: Vec<String>,
}
// Every check and the build run before services stop, so a failure leaves the current
// installation running.
fn install(s: &Settings, preserve_profile: bool) -> Result<Option<String>, String> {
let prepared = prepare(s, preserve_profile)?;
let _lock = lock_installation(s)?;
set_update_state(
s,
"running",
"install",
"Build and config validation passed. Replacing the installation.",
)?;
replace_installation(
s,
prepared.desktop_settings.as_deref(),
prepared.needs_setup,
)?;
platform::install(s, !prepared.needs_setup && prepared.missing_keys.is_empty())?;
if prepared.needs_setup {
let message = "Installed. Open Switchyard to choose your configuration. Existing files will skip setup on later installs.".to_string();
println!("{message}");
return Ok(Some(message));
}
if !preserve_profile || !present(&s.profile_file())? {
save_profile(s, &prepared.profile)?;
}
report_readiness(s, &prepared.missing_keys)
}
fn prepare(s: &Settings, preserve_profile: bool) -> Result<Prepared, String> {
let needs_setup = config::needs_setup(&s.desktop_settings())?;
let profile = s.profile_file();
let desktop_settings = reconcile_desktop_port(s)?;
let server_url = if desktop_settings.is_some() || !present(&s.desktop_settings())? {
config::server_url(s.port)
} else {
Config::load(&s.desktop_settings())?.server_url
};
let profile_text = if needs_setup {
String::new()
} else {
let context_window = route_context_window(s)?;
if profile.exists() && !preserve_profile {
let current = fs::read_to_string(&profile).map_err(err)?;
merge_codex_profile(s, ¤t, context_window, &server_url)?
} else {
codex_profile(s, context_window, &server_url)
}
};
#[cfg(not(windows))]
platform::preflight()?;
let prices = if needs_setup {
None
} else {
Config::load(&s.desktop_settings())?
.prices_file
.or_else(|| {
// An installation with only a server config still imports its adjacent price override.
(!s.desktop_settings().exists() && s.prices_file().exists())
.then(|| s.prices_file())
})
};
if let Some(prices) = prices {
Pricing::load(&prices).map_err(|e| format!("{e}. Fix this file before installing."))?;
}
build(s)?;
let missing_keys = if needs_setup {
Vec::new()
} else {
check_server_config(s, !preserve_profile || !profile.exists())?
};
Ok(Prepared {
needs_setup,
profile: profile_text,
desktop_settings,
missing_keys,
})
}
/// This function builds the server from the main workspace and the app from its own
/// experimental workspace before it installs binaries or changes services.
fn build(s: &Settings) -> Result<(), String> {
println!(
"Building the desktop app and server from {}",
s.source.display()
);
// Cargo and rustc must come from the same toolchain, including GUI-triggered updates.
let cargo_dir = s.cargo.parent().ok_or("Cargo has no parent directory.")?;
let mut paths = vec![cargo_dir.to_path_buf()];
if let Some(path) = std::env::var_os("PATH") {
paths.extend(std::env::split_paths(&path));
}
let path = std::env::join_paths(paths).map_err(err)?;
for (manifest, package) in [
("Cargo.toml", "switchyard-server"),
(
"experimental/switchyard-desktop/Cargo.toml",
"switchyard-desktop",
),
] {
run(Command::new(&s.cargo)
.current_dir(&s.source)
.args(["build", "--locked", "--release", "--manifest-path"])
.arg(s.source.join(manifest))
.arg("--target-dir")
.arg(s.source.join("target"))
.args(["-p", package])
.env("PATH", &path))?;
}
Ok(())
}
/// Checks the server config that the install keeps, or the bundled one on a first install, and
/// returns the API key variables that have no saved key.
fn check_server_config(s: &Settings, require_route: bool) -> Result<Vec<String>, String> {
let config = Config::load(&s.desktop_settings())?.config_file;
let existing = present(&config)?;
let staged = tempfile::NamedTempFile::new().map_err(err)?;
let checked = if existing {
config.as_path()
} else {
fs::write(staged.path(), BUNDLED_CONFIG).map_err(err)?;
staged.path()
};
// Install never saves keys; the app's Settings → Server keys does. Placeholder values let the
// dry run check the config without reading any key.
let mut checker = Command::new(s.release("switchyard-server"));
for name in credentials::variables(checked)? {
checker.env(name, "placeholder-for-config-check");
}
run(checker.arg("--config").arg(checked).arg("--dry-run"))?;
// Finding an item does not read its key, so this check never asks for Keychain access.
let missing = credentials::status(checked)?
.into_iter()
.filter(|key| !key.saved)
.map(|key| key.name)
.collect();
if require_route {
check_public_route(checked, &s.model)?;
}
Ok(missing)
}
/// Stops the services and replaces the app files. The macOS app bundle is staged and signed
/// before the services stop.
fn replace_installation(
s: &Settings,
desktop_settings: Option<&str>,
needs_setup: bool,
) -> Result<(), String> {
let metadata = toml::to_string(s).map_err(err)?;
#[cfg(target_os = "macos")]
let bundle = platform::stage_bundle(s, &metadata)?;
fs::create_dir_all(&s.sy_home).map_err(err)?;
set_update_state(
s,
"running",
"services",
"Stopping services and replacing app files. Existing config and history are retained.",
)?;
platform::stop(s)?;
fs::create_dir_all(s.sy_home.join("logs")).map_err(err)?;
#[cfg(windows)]
windows::replace_binaries(s)?;
#[cfg(not(windows))]
for binary in [
"switchyard-server",
"switchyard-desktop",
"switchyard-desktop-install",
] {
let bytes = fs::read(s.release(binary)).map_err(err)?;
write(&s.binary(binary), &bytes, true)?;
}
if !needs_setup {
if let Some(text) = desktop_settings {
write(&s.desktop_settings(), text.as_bytes(), false)?;
} else {
write_once(&s.desktop_settings(), &desktop_config(s)?)?;
}
}
for record in [s.sy_home.join("install.toml"), s.install_record()] {
write(&record, metadata.as_bytes(), false)?;
}
#[cfg(target_os = "macos")]
platform::replace_app(s, bundle)?;
Ok(())
}
fn save_profile(s: &Settings, text: &str) -> Result<(), String> {
set_update_state(
s,
"running",
"profile",
"Saving the selected Codex profile.",
)?;
let profile = s.profile_file();
if present(&profile)? && fs::read(&profile).map_err(err)? != text.as_bytes() {
backup(&profile, "switchyard-backup")?;
}
write(&profile, text.as_bytes(), false)
}
/// Returns the warning to record when the server cannot start yet or does not answer /health.
fn report_readiness(s: &Settings, missing_keys: &[String]) -> Result<Option<String>, String> {
let config = Config::load(&s.desktop_settings())?;
println!(
"Installed. Server: {}\nSettings: {}\nUse: codex -p {}",
config.server_url,
s.desktop_settings().display(),
s.profile
);
set_update_state(
s,
"running",
"readiness",
"Installed. Waiting for the server to answer /health.",
)?;
if !missing_keys.is_empty() {
let next = if cfg!(any(target_os = "macos", windows)) {
"Open Switchyard, go to Settings → Server keys, save each key, \
and restart the server."
.to_string()
} else {
format!(
"Save each key with {} key set NAME, \
then run systemctl --user restart switchyard.",
s.binary("switchyard-desktop-install").display()
)
};
let message = format!(
"Installed the app and server. The server starts after you save a key for {}. {next}",
missing_keys.join(", ")
);
println!("{message}");
return Ok(Some(message));
}
let port = crate::health::validate_url(&config.server_url)?
.port_or_known_default()
.ok_or("Missing server port.")?;
if wait_for_health(port) {
return Ok(None);
}
let message = format!(
"Installed the app and server, but Switchyard did not answer /health. \
Check logs at {} and restart the server.",
s.sy_home.join("logs").display()
);
println!("Warning: {message}");
Ok(Some(message))
}
fn routes(config: &toml::Value) -> impl Iterator<Item = &toml::Value> {
config
.get("routes")
.and_then(toml::Value::as_table)
.into_iter()
.flat_map(|routes| routes.values())
}
fn check_public_route(config: &Path, model: &str) -> Result<(), String> {
let text = fs::read_to_string(config).map_err(err)?;
let document: toml::Value = toml::from_str(&text).map_err(err)?;
let ids: Vec<&str> = routes(&document)
.filter_map(|route| route.get("id")?.as_str())
.collect();
if ids.contains(&model) {
return Ok(());
}
Err(format!(
"Route {model:?} is not in {}. Choose SY_MODEL from: {}. \
No services or coding-tool settings were changed.",
config.display(),
ids.join(", ")
))
}
fn reconcile_desktop_port(s: &Settings) -> Result<Option<String>, String> {
let path = s.desktop_settings();
let Some(text) = read_optional(&path).map_err(|e| format!("Read {}: {e}", path.display()))?
else {
return Ok(None);
};
let mut document: toml_edit::DocumentMut = text.parse().map_err(|e| {
format!(
"Parse {}: {e}. Fix this file before installing.",
path.display()
)
})?;
let previous = s.sy_home.join("install.toml");
let old_port = if previous.exists() {
Settings::load(&previous)?.port
} else {
DEFAULT_PORT
};
let expected = config::server_url(old_port);
let current = document
.get("server_url")
.map(|value| {
value.as_str().ok_or_else(|| {
format!(
"The server_url value in {} must be a string: invalid data. \
Fix this file before installing.",
path.display()
)
})
})
.transpose()?;
if s.port != old_port && current.is_some_and(|url| url != expected) {
return Err(format!(
"{} uses a custom server_url, but SY_PORT changes from {old_port} to {}. \
Review the app URL and port together before reinstalling. No services were stopped.",
path.display(),
s.port
));
}
// Unchanged and custom URLs must retain the original TOML bytes, including quotes and line endings.
if current.is_some_and(|url| url != expected || s.port == old_port) {
return Ok(None);
}
document["server_url"] = toml_edit::value(config::server_url(s.port));
let updated = document.to_string();
Ok((updated != text).then_some(updated))
}
// Returns the `context_window` of the route that SY_MODEL names, from the existing server
// config or, on a new install, the bundled one. A missing route returns `None` here;
// check_public_route rejects it later with the list of valid route IDs.
fn route_context_window(s: &Settings) -> Result<Option<i64>, String> {
let path = Config::load(&s.desktop_settings())?.config_file;
let text = read_optional(&path).map_err(|e| format!("Read {}: {e}", path.display()))?;
let document: toml::Value = toml::from_str(text.as_deref().unwrap_or(BUNDLED_CONFIG))
.map_err(|e| format!("Parse {}: {e}", path.display()))?;
Ok(routes(&document)
.find(|route| route.get("id").and_then(toml::Value::as_str) == Some(&s.model))
.and_then(|route| route.get("context_window")?.as_integer()))
}
// Codex compacts a thread when its usage nears the model's context window. Codex does not
// know a Switchyard route ID, so the profile names the route's window. Without it, Codex
// never compacts on the route, and a long thread fails when the upstream rejects it.
fn codex_profile(s: &Settings, context_window: Option<i64>, server_url: &str) -> String {
let mut value: toml::Value = toml::from_str(
include_str!("../../../scripts/config/codex.sy.toml")
.replace("@SY_PORT@", &s.port.to_string())
.as_str(),
)
.expect("bundled profile is valid TOML");
value["model"] = s.model.clone().into();
value["model_providers"]["sy"]["base_url"] =
format!("{}/v1", server_url.trim_end_matches('/')).into();
if let (Some(window), Some(table)) = (context_window, value.as_table_mut()) {
table.insert("model_context_window".into(), window.into());
}
toml::to_string(&value).expect("profile values serialize")
}
fn merge_codex_profile(
s: &Settings,
current: &str,
context_window: Option<i64>,
server_url: &str,
) -> Result<String, String> {
let mut document: toml_edit::DocumentMut = current
.parse()
.map_err(|e| format!("Read Codex profile: {e}"))?;
let template: toml_edit::DocumentMut = codex_profile(s, context_window, server_url)
.parse()
.expect("generated profile is valid TOML");
for key in ["model", "model_provider"] {
document[key] = template[key].clone();
}
// A window kept from an earlier route would make Codex compact at the wrong size.
match template.get("model_context_window") {
Some(window) => document["model_context_window"] = window.clone(),
None => {
document.remove("model_context_window");
}
}
if document.get("model_providers").is_none() {
document["model_providers"] = toml_edit::table();
}
let providers = &mut document["model_providers"];
if !providers.is_table_like() {
return Err(
"Codex model_providers must be a table. No services or profiles were changed.".into(),
);
}
let sy = providers.get("sy");
if sy.is_some_and(|item| !item.is_table_like()) {
return Err(
"Codex model_providers.sy must be a table. No services or profiles were changed."
.into(),
);
}
if sy.is_none() {
providers["sy"] = toml_edit::table();
}
for key in ["name", "base_url", "wire_api", "requires_openai_auth"] {
providers["sy"][key] = template["model_providers"]["sy"][key].clone();
}
Ok(document.to_string())
}
// The installer and app share defaults so generated settings keep the selected directory and port.
fn desktop_config(s: &Settings) -> Result<String, String> {
let mut config = Config::for_directory(&s.sy_home, s.port);
let prices = s.prices_file();
if prices.exists() {
config.prices_file = Some(prices);
}
toml::to_string(&config).map_err(err)
}
#[cfg(any(target_os = "macos", windows))]
fn xml(value: &str) -> String {
value
.replace('&', "&")
.replace('<', "<")
.replace('>', ">")
}
fn uninstall(s: &Settings) -> Result<(), String> {
let _lock = lock_installation(s)?;
println!("{}", installation_plan(s, "uninstall"));
let profile = s.profile_file();
if profile.exists() {
backup(&profile, "switchyard-uninstall-recovery")?;
}
platform::stop(s)?;
platform::uninstall(s)?;
remove(&profile)?;
println!(
"Removed services, app, and profile. Kept settings, accounts, {}and history at {}.",
if cfg!(windows) { "" } else { "binaries, " },
s.sy_home.display()
);
let recorded = s.install_record();
if recorded.exists() && Settings::load(&recorded)?.sy_home == s.sy_home {
remove(&recorded)?;
}
Ok(())
}