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
//! This module installs and restores user settings for the supported harnesses.
use serde_json::{Value, json};
use std::io::Write;
use std::path::{Path, PathBuf};
use toml_edit::{DocumentMut, value};
pub type ReviewedFile = (PathBuf, Option<std::sync::Arc<[u8]>>);
#[derive(
Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, serde::Deserialize, serde::Serialize,
)]
#[serde(rename_all = "snake_case")]
pub enum Harness {
CodexCli,
CodexApp,
Claude,
Pi,
}
pub const HARNESSES: &[(Harness, &str)] = &[
(Harness::CodexCli, "Codex CLI profile"),
(Harness::CodexApp, "Codex app and CLI defaults"),
(Harness::Claude, "Claude Code"),
(Harness::Pi, "Pi"),
];
/// This function uses the selected harness's environment variable when it is set and not empty.
/// This function resolves the home directory only when that variable is absent or empty.
pub fn paths(tool: Harness) -> Result<Vec<PathBuf>, String> {
let (variable, default, files): (&str, &str, &[&str]) = match tool {
Harness::CodexCli => ("CODEX_HOME", "~/.codex", &["sy.config.toml"]),
Harness::CodexApp => ("CODEX_HOME", "~/.codex", &["config.toml"]),
Harness::Claude => ("CLAUDE_CONFIG_DIR", "~/.claude", &["settings.json"]),
Harness::Pi => (
"PI_CODING_AGENT_DIR",
"~/.pi/agent",
&["models.json", "settings.json"],
),
};
let directory = match std::env::var_os(variable).filter(|path| !path.is_empty()) {
// A relative directory would make Install and Restore write next to the app's working
// directory instead of the harness's settings.
Some(path) if Path::new(&path).is_absolute() => PathBuf::from(path),
Some(_) => return Err(format!("{variable} must be an absolute path.")),
None => crate::config::expand_home(Path::new(default))?,
};
Ok(files.iter().map(|file| directory.join(file)).collect())
}
pub fn inspect(tool: Harness, files: &[PathBuf]) -> Result<String, String> {
let texts = files
.iter()
.map(|path| read(path))
.collect::<Result<Vec<_>, _>>()?;
inspect_settings(tool, files, &texts)
}
fn inspect_settings(tool: Harness, files: &[PathBuf], texts: &[String]) -> Result<String, String> {
let text = &texts[0];
let model;
let endpoint;
let default_endpoint;
match tool {
Harness::CodexCli | Harness::CodexApp => {
let doc = text
.parse::<DocumentMut>()
.map_err(|e| e.message().to_owned())?;
model = doc
.get("model")
.and_then(|v| v.as_str())
.unwrap_or("Default")
.to_string();
let provider = doc
.get("model_provider")
.and_then(|v| v.as_str())
.unwrap_or("openai");
endpoint = doc
.get("model_providers")
.and_then(|v| v.get(provider))
.and_then(|v| v.get("base_url"))
.and_then(|v| v.as_str())
.map(str::to_owned);
default_endpoint = "Provider default";
}
Harness::Claude => {
let doc = object(text)?;
model = doc
.pointer("/env/ANTHROPIC_MODEL")
.and_then(Value::as_str)
.or_else(|| doc.get("model").and_then(Value::as_str))
.unwrap_or("Default")
.to_string();
endpoint = doc
.pointer("/env/ANTHROPIC_BASE_URL")
.and_then(Value::as_str)
.map(str::to_owned);
default_endpoint = "Anthropic default";
}
Harness::Pi => {
let doc = object(&texts[1])?;
model = doc
.get("defaultModel")
.and_then(Value::as_str)
.unwrap_or("Default")
.to_string();
let provider = doc
.get("defaultProvider")
.and_then(Value::as_str)
.unwrap_or("Default");
let models = object(text)?;
endpoint = models
.get("providers")
.and_then(|v| v.get(provider))
.and_then(|v| v.get("baseUrl"))
.and_then(Value::as_str)
.map(str::to_owned);
default_endpoint = "Provider default";
}
}
// The display keeps the URL scheme, host, and port to omit credentials and queries.
let endpoint = match endpoint {
None => default_endpoint.to_owned(),
Some(raw) => url::Url::parse(&raw)
.ok()
.and_then(|u| {
let host = u.host_str()?;
Some(format!(
"{}://{host}{}",
u.scheme(),
u.port().map(|p| format!(":{p}")).unwrap_or_default()
))
})
.unwrap_or_else(|| "Not a valid URL".into()),
};
Ok(format!(
"Model: {model}\nEndpoint: {endpoint}\nSettings: {}",
files
.iter()
.map(|file| file.display().to_string())
.collect::<Vec<_>>()
.join("\n ")
))
}
fn read_file(path: &Path) -> Result<Option<String>, String> {
match std::fs::symlink_metadata(path) {
Ok(meta) if meta.file_type().is_symlink() => {
return Err(format!(
"{} is a symlink. Edit its target yourself.",
path.display()
));
}
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(e) => return Err(e.to_string()),
_ => {}
}
std::fs::read_to_string(path)
.map(Some)
.map_err(|e| format!("Read {}: {e}", path.display()))
}
fn read(path: &Path) -> Result<String, String> {
Ok(read_file(path)?.unwrap_or_default())
}
fn object(text: &str) -> Result<Value, String> {
let doc: Value = if text.is_empty() {
json!({})
} else {
serde_json::from_str(text).map_err(|e| e.to_string())?
};
if !doc.is_object() {
return Err("Settings must be a JSON object.".into());
}
Ok(doc)
}
fn map<'a>(doc: &'a mut Value, key: &str) -> Result<&'a mut Value, String> {
if doc.get(key).is_none() {
doc[key] = json!({});
}
if !doc[key].is_object() {
return Err(format!("{key} must be a JSON object."));
}
Ok(&mut doc[key])
}
pub fn validate(tool: Harness, root: &str, model: &str, login: bool) -> Result<String, String> {
let url = url::Url::parse(root).map_err(|e| e.to_string())?;
if url.scheme() != "http"
|| !matches!(url.host_str(), Some("localhost" | "127.0.0.1" | "[::1]"))
|| !url.username().is_empty()
|| url.password().is_some()
|| url.query().is_some()
|| url.fragment().is_some()
|| url.path() != "/"
{
return Err(
"Install requires a local HTTP server URL, such as http://127.0.0.1:4123.".into(),
);
}
if model.trim().is_empty() {
return Err("Pick a route first.".into());
}
if tool == Harness::Pi && login {
return Err(
"Pi's custom provider needs a route with server API credentials. \
Use Codex or Claude for subscription login forwarding."
.into(),
);
}
// validate returns the parsed URL without a trailing slash so callers can append API paths.
Ok(url.to_string().trim_end_matches('/').to_owned())
}
fn codex_settings(
text: &str,
root: &str,
model: &str,
context_window: Option<u64>,
login: bool,
) -> Result<String, String> {
let mut doc = text
.parse::<DocumentMut>()
.map_err(|e| e.message().to_owned())?;
if doc
.get("model_providers")
.is_some_and(|item| item.as_table_like().is_none())
{
return Err("model_providers must be a TOML table.".into());
}
if doc
.get("model_providers")
.and_then(|v| v.get("sy"))
.is_some_and(|item| item.as_table_like().is_none())
{
return Err("sy must be a TOML provider table.".into());
}
doc["model"] = value(model);
doc["model_provider"] = value("sy");
// Codex does not know a route ID, so it compacts only when the settings name the
// route's window. A window kept from another route would compact at the wrong size.
match context_window.and_then(|window| i64::try_from(window).ok()) {
Some(window) => doc["model_context_window"] = value(window),
None => {
doc.remove("model_context_window");
}
}
doc["model_providers"]["sy"]["name"] = value("Switchyard");
doc["model_providers"]["sy"]["base_url"] = value(format!("{root}/v1"));
doc["model_providers"]["sy"]["wire_api"] = value("responses");
doc["model_providers"]["sy"]["requires_openai_auth"] = value(login);
// A stale env_key would make Codex require a local API key even when the
// server owns the credentials or forwards the harness’s subscription login.
doc["model_providers"]["sy"]
.as_table_like_mut()
.ok_or("sy must be a provider table")?
.remove("env_key");
Ok(doc.to_string())
}
fn claude_settings(text: &str, root: &str, model: &str, login: bool) -> Result<String, String> {
let mut doc = object(text)?;
let env = map(&mut doc, "env")?;
let role_models = [
"ANTHROPIC_DEFAULT_OPUS_MODEL",
"ANTHROPIC_DEFAULT_SONNET_MODEL",
"ANTHROPIC_DEFAULT_HAIKU_MODEL",
];
// The complete installation signature distinguishes our placeholder from a user credential.
let prior_switchyard = env["ANTHROPIC_BASE_URL"].as_str() == Some(root)
&& env["ANTHROPIC_AUTH_TOKEN"].as_str() == Some("switchyard-local")
&& env["ANTHROPIC_API_KEY"].as_str() == Some("")
&& env["ANTHROPIC_MODEL"]
.as_str()
.is_some_and(|model| !model.is_empty())
&& role_models
.iter()
.all(|key| env[*key] == env["ANTHROPIC_MODEL"]);
env["ANTHROPIC_BASE_URL"] = json!(root);
env["ANTHROPIC_MODEL"] = json!(model);
// All model roles use the selected public route, including subagents.
for key in role_models {
env[key] = json!(model);
}
if login {
if prior_switchyard {
let values = env.as_object_mut().ok_or("env must be a JSON object.")?;
values.remove("ANTHROPIC_AUTH_TOKEN");
values.remove("ANTHROPIC_API_KEY");
}
for key in ["ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_API_KEY"] {
if env.get(key).is_some_and(|value| value.as_str() != Some("")) {
return Err(format!(
"{key} overrides subscription login. \
Remove it from Claude settings before installing this route."
));
}
}
} else {
env["ANTHROPIC_AUTH_TOKEN"] = json!("switchyard-local");
env["ANTHROPIC_API_KEY"] = json!("");
}
Ok(serde_json::to_string_pretty(&doc).map_err(|e| e.to_string())? + "\n")
}
// The preview uses the installation transformations without creating files or backups.
pub fn preview(
tool: Harness,
files: &[PathBuf],
root: &str,
model: &str,
context_window: Option<u64>,
login: bool,
) -> Result<Value, String> {
let root = validate(tool, root, model, login)?;
for path in files {
if read_file(&restore_pending_path(path))?.is_some() {
return Err("A previous restore still needs backup cleanup. \
Retry Restore before connecting another route."
.into());
}
}
let originals = files
.iter()
.map(|path| read_file(path))
.collect::<Result<Vec<_>, _>>()?;
let incoming = configured(tool, &originals, &root, model, context_window, login)?;
let current = originals
.iter()
.map(|text| text.clone().unwrap_or_default())
.collect::<Vec<_>>();
Ok(json!({
"changes": settings_changes(tool, files, ¤t, &incoming)?,
"current": inspect_settings(tool, files, ¤t)?,
"proposed": inspect_settings(tool, files, &incoming)?,
"authentication": if login {
"This route uses the harness’s subscription login."
} else {
"This route uses the API credentials configured on the Switchyard server."
},
"files": files.iter().map(|path| path.display().to_string()).collect::<Vec<_>>(),
"file_actions": files.iter().zip(originals.iter().zip(&incoming)).map(|(path,(before,after))|json!({"file":path,"action":if before.as_deref()==Some(after.as_str()) {"preserve"} else if before.is_none() {"create"} else {"update"}})).collect::<Vec<_>>()
}))
}
// PreviewModel and its nested types omit unknown fields that could contain credentials.
#[derive(serde::Deserialize, serde::Serialize)]
#[serde(rename_all = "camelCase")]
struct PreviewModel {
id: Option<String>,
name: Option<String>,
reasoning: Option<bool>,
input: Option<Vec<PreviewInput>>,
context_window: Option<u64>,
max_tokens: Option<u64>,
cost: Option<PreviewCosts>,
}
#[derive(serde::Deserialize, serde::Serialize)]
#[serde(rename_all = "lowercase")]
enum PreviewInput {
Text,
Image,
}
#[derive(serde::Deserialize, serde::Serialize)]
#[serde(rename_all = "camelCase")]
struct PreviewCosts {
input: Option<f64>,
output: Option<f64>,
cache_read: Option<f64>,
cache_write: Option<f64>,
}
// settings_changes compares supported routing fields and hides credential values before display.
fn settings_changes(
tool: Harness,
files: &[PathBuf],
before: &[String],
after: &[String],
) -> Result<Vec<Value>, String> {
let mut changes = Vec::new();
for (index, file) in files.iter().enumerate() {
let decode = |text: &str| -> Result<Value, String> {
if matches!(tool, Harness::CodexCli | Harness::CodexApp) {
let doc: toml::Value = toml::from_str(text).map_err(|e| e.to_string())?;
serde_json::to_value(doc).map_err(|e| e.to_string())
} else {
object(text)
}
};
let old = decode(&before[index])?;
let new = decode(&after[index])?;
let keys: &[&str] = match tool {
Harness::CodexCli | Harness::CodexApp => &[
"/model",
"/model_provider",
"/model_context_window",
"/model_providers/sy/name",
"/model_providers/sy/env_key",
"/model_providers/sy/base_url",
"/model_providers/sy/requires_openai_auth",
"/model_providers/sy/wire_api",
],
Harness::Claude => &[
"/model",
"/env/ANTHROPIC_MODEL",
"/env/ANTHROPIC_DEFAULT_OPUS_MODEL",
"/env/ANTHROPIC_DEFAULT_SONNET_MODEL",
"/env/ANTHROPIC_DEFAULT_HAIKU_MODEL",
"/env/ANTHROPIC_BASE_URL",
"/env/ANTHROPIC_AUTH_TOKEN",
"/env/ANTHROPIC_API_KEY",
],
Harness::Pi if index == 0 => &[
"/providers/switchyard/baseUrl",
"/providers/switchyard/api",
"/providers/switchyard/apiKey",
"/providers/switchyard/headers",
"/providers/switchyard/models",
],
Harness::Pi => &["/defaultModel", "/defaultProvider"],
};
for key in keys {
let left = old.pointer(key);
let right = new.pointer(key);
if left == right {
continue;
}
let display = |value: Option<&Value>| -> String {
let Some(value) = value else {
return "(unset)".into();
};
match *key {
"/env/ANTHROPIC_AUTH_TOKEN"
| "/env/ANTHROPIC_API_KEY"
| "/providers/switchyard/apiKey" => if value.as_str() == Some("") {
"(empty)"
} else {
"(set; hidden)"
}
.into(),
"/providers/switchyard/headers" => value
.as_object()
.map(|headers| {
headers
.keys()
.map(|name| format!("{name}: (set; hidden)"))
.collect::<Vec<_>>()
.join(", ")
})
.unwrap_or_else(|| "(configured headers; values hidden)".into()),
"/providers/switchyard/models" => value
.as_array()
.map(|models| {
models
.iter()
.map(|model| {
serde_json::from_value::<PreviewModel>(model.clone())
.and_then(serde_json::to_value)
.unwrap_or_else(|_| {
json!("(unsupported model metadata; hidden)")
})
})
.collect::<Vec<_>>()
})
.map(|models| Value::Array(models).to_string())
.unwrap_or_default(),
"/env/ANTHROPIC_BASE_URL"
| "/model_providers/sy/base_url"
| "/providers/switchyard/baseUrl" => value
.as_str()
.and_then(|v| url::Url::parse(v).ok())
.map(|mut url| {
let _ = url.set_username("");
let _ = url.set_password(None);
url.set_query(None);
url.set_fragment(None);
url.to_string()
})
.unwrap_or_else(|| "(configured endpoint)".into()),
_ => match value {
Value::String(value) => value.clone(),
Value::Bool(value) => value.to_string(),
Value::Number(value) => value.to_string(),
_ => "(set; hidden)".into(),
},
}
};
changes.push(json!({"file":file.display().to_string(),"key":key.trim_start_matches('/').replace('/',"."),"before":display(left),"after":display(right)}));
}
}
Ok(changes)
}
// Both preview and installation use these transformations so the proposed settings match the saved settings.
fn configured(
tool: Harness,
originals: &[Option<String>],
root: &str,
model: &str,
context_window: Option<u64>,
login: bool,
) -> Result<Vec<String>, String> {
let mut incoming = Vec::new();
match tool {
Harness::CodexCli | Harness::CodexApp => incoming.push(codex_settings(
originals[0].as_deref().unwrap_or_default(),
root,
model,
context_window,
login,
)?),
Harness::Claude => incoming.push(claude_settings(
originals[0].as_deref().unwrap_or_default(),
root,
model,
login,
)?),
Harness::Pi => {
let mut doc = object(originals[0].as_deref().unwrap_or_default())?;
let providers = map(&mut doc, "providers")?;
// Only the fields shown in the preview change; other keys on the provider stay.
let provider = map(providers, "switchyard")?;
provider["baseUrl"] = json!(format!("{root}/v1"));
provider["api"] = json!("openai-completions");
provider["apiKey"] = json!("switchyard-local");
provider["headers"] = json!({"x-switchyard-origin":"pi"});
provider["models"] = json!([{"id":model,"name":model,"reasoning":true,"input":["text"],"contextWindow":context_window.unwrap_or(128000),"maxTokens":16384,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0}}]);
incoming.push(serde_json::to_string_pretty(&doc).map_err(|e| e.to_string())? + "\n");
let mut settings = object(originals[1].as_deref().unwrap_or_default())?;
settings["defaultProvider"] = json!("switchyard");
settings["defaultModel"] = json!(model);
incoming
.push(serde_json::to_string_pretty(&settings).map_err(|e| e.to_string())? + "\n");
}
}
Ok(incoming)
}
pub fn install(
tool: Harness,
files: &[PathBuf],
root: &str,
model: &str,
context_window: Option<u64>,
login: bool,
) -> Result<String, String> {
install_reviewed(tool, files, root, model, context_window, login, None)
}
pub fn install_reviewed(
tool: Harness,
files: &[PathBuf],
root: &str,
model: &str,
context_window: Option<u64>,
login: bool,
expected: Option<&[ReviewedFile]>,
) -> Result<String, String> {
let root = validate(tool, root, model, login)?;
for path in files {
if read_file(&restore_pending_path(path))?.is_some() {
return Err("A previous restore did not finish retiring its backups. \
Retry Restore before installing another route."
.into());
}
}
let originals = files
.iter()
.map(|p| read_file(p))
.collect::<Result<Vec<_>, _>>()?;
check_review(expected)?;
let incoming = configured(tool, &originals, &root, model, context_window, login)?;
let incoming: Vec<_> = incoming.into_iter().map(Some).collect();
for (path, original) in files.iter().zip(&originals) {
if let Some(expected) = expected
.and_then(|files| files.iter().find(|(file, _)| file == path))
.map(|(_, bytes)| bytes)
&& original.as_ref().map(|text| text.as_bytes()) != expected.as_deref()
{
return Err("Harness settings changed after the preview. Review them again.".into());
}
}
for (path, before) in files.iter().zip(&originals) {
let backup = backup_path(path);
let absent = absent_path(path);
if read_file(&backup)?.is_some() || read_file(&absent)?.is_some() {
continue;
}
let (destination, text) = match before {
Some(text) => (&backup, text.as_str()),
None => (&absent, ""),
};
prepare(destination, text)?
.persist_noclobber(destination)
.map_err(|e| e.to_string())?;
}
replace(files, &originals, &incoming)?;
let next = match tool {
Harness::CodexCli => {
let profile = files[0]
.file_name()
.and_then(|name| name.to_str())
.and_then(|name| name.strip_suffix(".config.toml"));
profile
.map(|name| format!(" Start Codex CLI with codex -p {name}."))
.unwrap_or_else(|| " Restart Codex CLI.".into())
}
Harness::Pi => " Reload Pi models with /model.".into(),
Harness::CodexApp => " Restart Codex app.".into(),
Harness::Claude => " Restart Claude Code.".into(),
};
Ok(format!(
"Connected route {model}. Changed {}.{next}",
files
.iter()
.map(|path| path.display().to_string())
.collect::<Vec<_>>()
.join(", ")
))
}
fn backup_path(path: &Path) -> PathBuf {
path.with_file_name(format!(
"{}.switchyard-original",
path.file_name().unwrap_or_default().to_string_lossy()
))
}
// The marker distinguishes an originally missing file from an empty file.
// Restore removes installed settings only when the original file was missing.
fn absent_path(path: &Path) -> PathBuf {
backup_path(path).with_extension("switchyard-original-missing")
}
fn restore_pending_path(path: &Path) -> PathBuf {
backup_path(path).with_extension("switchyard-restore-pending")
}
pub fn review_files(files: &[PathBuf]) -> Vec<PathBuf> {
files
.iter()
.flat_map(|path| {
[
path.clone(),
backup_path(path),
absent_path(path),
restore_pending_path(path),
]
})
.collect()
}
pub fn preview_restore(tool: Harness, files: &[PathBuf]) -> Result<Value, String> {
let resuming = files.iter().any(|path| restore_pending_path(path).exists());
let mut plan = Vec::new();
let mut before = Vec::new();
let mut after = Vec::new();
for path in files {
let current = read_file(path)?;
let pending = read_file(&restore_pending_path(path))?;
let original = match pending {
Some(text) => {
serde_json::from_str::<Option<String>>(&text).map_err(|error| error.to_string())?
}
None => match read_file(&backup_path(path))? {
Some(text) => Some(text),
None if read_file(&absent_path(path))?.is_some() => None,
None if resuming => current.clone(),
None => return Err("No original backup is available for this destination.".into()),
},
};
let action = if current == original {
"unchanged"
} else {
match (¤t, &original) {
(_, None) => "remove",
(None, _) => "create",
_ => "replace",
}
};
before.push(current.unwrap_or_default());
after.push(original.unwrap_or_default());
plan.push(json!({"file":path,"action":action,"backup":backup_path(path)}));
}
Ok(json!({
"files": plan,
"changes": settings_changes(tool, files, &before, &after).ok(),
"warning": "Restore replaces each listed file with its original version. \
Later edits are kept in a recovery copy before replacement."
}))
}
// Restore receipts keep the original contents or absence available until backup cleanup finishes.
#[cfg(test)]
pub fn restore(files: &[PathBuf]) -> Result<String, String> {
restore_reviewed(files, None)
}
pub fn restore_reviewed(
files: &[PathBuf],
expected: Option<&[ReviewedFile]>,
) -> Result<String, String> {
let pending = files
.iter()
.map(|path| read_file(&restore_pending_path(path)))
.collect::<Result<Vec<_>, _>>()?;
let resuming = pending.iter().any(Option::is_some);
let mut restored = Vec::new();
for (path, pending) in files.iter().zip(pending) {
let original = read_file(&backup_path(path))?;
let absent = read_file(&absent_path(path))?.is_some();
let original = match pending {
Some(text) => serde_json::from_str::<Option<String>>(&text)
.map_err(|e| format!("Read pending restore: {e}"))?,
None if original.is_none() && !absent => {
if !resuming {
return Err("No original backup is available for this installation.".into());
}
// A cleared receipt means this file finished restoring, so a retry preserves later edits.
read_file(path)?
}
None => original,
};
restored.push(original);
}
let current = files
.iter()
.map(|p| read_file(p))
.collect::<Result<Vec<_>, _>>()?;
check_review(expected)?;
for (path, original) in files.iter().zip(¤t) {
if let Some(expected) = expected
.and_then(|files| files.iter().find(|(file, _)| file == path))
.map(|(_, bytes)| bytes)
&& original.as_ref().map(|text| text.as_bytes()) != expected.as_deref()
{
return Err(
"Harness settings changed after the restore preview. Review them again.".into(),
);
}
}
let mut kept_paths = Vec::new();
for (path, before) in files.iter().zip(¤t) {
let Some(before) = before else {
continue;
};
let mut recovery = tempfile::Builder::new()
.prefix("switchyard-before-restore-")
.tempfile_in(path.parent().ok_or("Settings need a parent directory")?)
.map_err(|e| e.to_string())?;
recovery
.write_all(before.as_bytes())
.map_err(|e| e.to_string())?;
let (_, kept) = recovery.keep().map_err(|e| e.to_string())?;
kept_paths.push(kept.display().to_string());
}
// Each private receipt stores the original contents or absence and blocks installation during cleanup.
for (path, original) in files.iter().zip(&restored) {
let pending = restore_pending_path(path);
if read_file(&pending)?.is_none() {
let text = serde_json::to_string(original).map_err(|e| e.to_string())?;
prepare(&pending, &text)?
.persist_noclobber(&pending)
.map_err(|e| e.to_string())?;
}
}
let recovery = format!("Previous settings: {}", kept_paths.join(", "));
replace(files, ¤t, &restored).map_err(|error| format!("{error}. {recovery}"))?;
for path in files {
for retired in [backup_path(path), absent_path(path)] {
match std::fs::remove_file(&retired) {
Ok(()) => {}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => {
return Err(format!(
"Restored settings, but could not retire {}: {error}. \
Retry Restore before installing another route. {recovery}",
retired.display()
));
}
}
}
}
for path in files {
let pending = restore_pending_path(path);
std::fs::remove_file(&pending).map_err(|error| {
format!(
"Restored settings, but could not clear {}: {error}. {recovery}",
pending.display()
)
})?;
}
Ok(format!(
"Restored original settings. Restart the harness. {recovery}"
))
}
fn check_review(expected: Option<&[ReviewedFile]>) -> Result<(), String> {
if let Some(files) = expected {
for (path, expected) in files {
let current = match std::fs::read(path) {
Ok(bytes) => Some(std::sync::Arc::<[u8]>::from(bytes)),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => None,
Err(error) => return Err(error.to_string()),
};
if ¤t != expected {
return Err(format!(
"{} changed after the preview. Review it again.",
path.display()
));
}
}
}
Ok(())
}
fn prepare(path: &Path, text: &str) -> Result<tempfile::NamedTempFile, String> {
let parent = path.parent().ok_or("Settings need a parent directory")?;
std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
let mut temp = tempfile::NamedTempFile::new_in(parent).map_err(|e| e.to_string())?;
temp.write_all(text.as_bytes())
.and_then(|_| temp.as_file().sync_all())
.map_err(|e| e.to_string())?;
Ok(temp)
}
// Each file replacement is atomic, but the set of replacements is not.
// A later failure triggers an attempt to restore files already replaced.
fn replace(
files: &[PathBuf],
before: &[Option<String>],
after: &[Option<String>],
) -> Result<(), String> {
let staged = files
.iter()
.zip(after)
.map(|(path, text)| text.as_deref().map(|text| prepare(path, text)).transpose())
.collect::<Result<Vec<_>, _>>()?;
for (path, expected) in files.iter().zip(before) {
if read_file(path)? != *expected {
return Err(format!(
"{} changed while installing. Refresh and try again.",
path.display()
));
}
}
for (index, (path, temp)) in files.iter().zip(staged).enumerate() {
let result = match temp {
Some(temp) => temp.persist(path).map(|_| ()).map_err(|e| e.to_string()),
None if before[index].is_some() => {
std::fs::remove_file(path).map_err(|e| e.to_string())
}
None => Ok(()),
};
if let Err(error) = result {
// The rollback tries every replaced file and keeps the error that stopped the install.
let mut failures = Vec::new();
for (path, original) in files[..index].iter().zip(before) {
let undone = match original {
Some(text) => prepare(path, text)
.and_then(|temp| temp.persist(path).map(|_| ()).map_err(|e| e.to_string())),
None => match std::fs::remove_file(path) {
Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
other => other.map_err(|e| e.to_string()),
},
};
if let Err(e) = undone {
failures.push(format!("{}: {e}", path.display()));
}
}
return Err(if failures.is_empty() {
error
} else {
format!("{error}. Could not undo: {}", failures.join("; "))
});
}
}
Ok(())
}
pub fn binary(tool: Harness) -> Option<PathBuf> {
if tool == Harness::CodexApp {
#[cfg(windows)]
return crate::windows::codex_app();
#[cfg(not(windows))]
{
#[cfg(target_os = "macos")]
if let Some(path) = objc2_app_kit::NSWorkspace::sharedWorkspace()
.URLForApplicationWithBundleIdentifier(&objc2_foundation::NSString::from_str(
"com.openai.codex",
))
.and_then(|url| url.path())
.map(|path| PathBuf::from(path.to_string()))
.filter(|path| path.is_dir())
{
return Some(path);
}
return [
Some(PathBuf::from("/Applications/Codex.app")),
crate::config::expand_home(Path::new("~/Applications/Codex.app")).ok(),
]
.into_iter()
.flatten()
.find(|p| p.exists());
}
}
let name = match tool {
Harness::CodexCli => "codex",
Harness::Claude => "claude",
Harness::Pi => "pi",
Harness::CodexApp => return None,
};
let mut dirs: Vec<_> = std::env::var_os("PATH")
.map(|s| std::env::split_paths(&s).collect())
.unwrap_or_default();
dirs.extend([
PathBuf::from("/opt/homebrew/bin"),
PathBuf::from("/usr/local/bin"),
]);
dirs.extend(
[
crate::config::expand_home(Path::new("~/.local/bin")).ok(),
crate::config::expand_home(Path::new("~/.npm-global/bin")).ok(),
]
.into_iter()
.flatten(),
);
#[cfg(windows)]
{
dirs.extend(
[
crate::config::expand_home(Path::new("~/AppData/Roaming/npm")).ok(),
crate::config::expand_home(Path::new("~/.cargo/bin")).ok(),
crate::config::expand_home(Path::new("~/.local/bin")).ok(),
]
.into_iter()
.flatten(),
);
dirs.into_iter()
.flat_map(|p| [p.join(format!("{name}.exe")), p.join(format!("{name}.cmd"))])
.find(|p| p.is_file())
}
#[cfg(not(windows))]
dirs.into_iter().map(|p| p.join(name)).find(|p| p.is_file())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
// Preview must match the installed settings without creating files or backups.
fn preview_matches_installation_without_writes() {
for (tool, _) in HARNESSES {
let dir = tempfile::tempdir().expect("directory");
let files = if *tool == Harness::Pi {
vec![
dir.path().join("models.json"),
dir.path().join("settings.json"),
]
} else {
vec![dir.path().join("config")]
};
let original = if matches!(tool, Harness::CodexCli | Harness::CodexApp) {
"# user comment\nmodel='before'\nsandbox_mode='workspace-write'\n"
} else {
"{\"custom\":true}"
};
std::fs::write(&files[0], original).expect("settings");
let result = preview(
*tool,
&files,
"http://localhost:4123",
"new-route",
None,
false,
)
.expect("preview");
assert!(
result["changes"]
.as_array()
.expect("diff")
.iter()
.any(|change| change["after"]
.as_str()
.is_some_and(|value| value.contains("new-route")))
);
assert_eq!(read(&files[0]).expect("unchanged"), original);
assert_eq!(std::fs::read_dir(dir.path()).expect("files").count(), 1);
install(
*tool,
&files,
"http://localhost:4123",
"new-route",
None,
false,
)
.expect("install");
assert_eq!(
result["proposed"],
inspect(*tool, &files).expect("installed")
);
install(
*tool,
&files,
"http://localhost:4123",
"refreshed-route",
None,
false,
)
.expect("refresh");
let installed = read(&files[0]).expect("settings");
assert!(installed.contains("refreshed-route"));
assert!(
installed.contains(if matches!(tool, Harness::CodexCli | Harness::CodexApp) {
"sandbox_mode"
} else {
"custom"
})
);
assert_eq!(read(&backup_path(&files[0])).expect("backup"), original);
restore(&files).expect("restore");
assert_eq!(read(&files[0]).expect("original"), original);
if *tool == Harness::Pi {
assert!(!files[1].exists());
}
std::fs::write(&files[0], original.replace("before", "new-user-model"))
.expect("user edit");
install(*tool, &files, "http://localhost:4123", "again", None, false)
.expect("reinstall");
restore(&files).expect("restore again");
assert_eq!(
read(&files[0]).expect("new original"),
original.replace("before", "new-user-model")
);
assert!(
result["authentication"]
.as_str()
.expect("authentication")
.contains("API credentials")
);
}
let dir = tempfile::tempdir().expect("directory");
let files = vec![dir.path().join("settings.json")];
let original =
r#"{"env":{"ANTHROPIC_API_KEY":"SECRET","ANTHROPIC_MODEL":{"key":"SECRET"}}}"#;
std::fs::write(&files[0], original).expect("settings");
assert!(
preview(
Harness::Claude,
&files,
"http://localhost:4123",
"route",
None,
true
)
.is_err()
);
assert_eq!(read(&files[0]).expect("unchanged"), original);
assert_eq!(std::fs::read_dir(dir.path()).expect("files").count(), 1);
let safe = preview(
Harness::Claude,
&files,
"http://localhost:4123",
"route",
None,
false,
)
.expect("API preview");
assert!(!safe.to_string().contains("SECRET"));
assert!(
safe["changes"]
.as_array()
.expect("diff")
.iter()
.any(|change| change["key"] == "env.ANTHROPIC_API_KEY"
&& change["before"] == "(set; hidden)")
);
std::fs::write(&files[0], "{}").expect("settings");
let result = preview(
Harness::Claude,
&files,
"http://localhost:4123",
"route",
None,
true,
)
.expect("login preview");
assert!(
result["authentication"]
.as_str()
.expect("authentication")
.contains("subscription login")
);
}
#[test]
fn a_pending_restore_blocks_install_and_retires_stale_backups_on_retry() {
let dir = tempfile::tempdir().expect("directory");
let path = dir.path().join("settings.json");
let files = std::slice::from_ref(&path);
std::fs::write(&path, "{}").expect("settings");
install(
Harness::Claude,
files,
"http://localhost:4123",
"api",
None,
false,
)
.expect("install");
let pending = restore_pending_path(&path);
std::fs::write(
&pending,
serde_json::to_string(&Some("{}".to_string())).expect("receipt"),
)
.expect("pending retirement");
let installed = read(&path).expect("installed");
assert!(
install(
Harness::Claude,
files,
"http://localhost:4123",
"another",
None,
false
)
.is_err()
);
assert_eq!(read(&path).expect("unchanged"), installed);
// The backup was already retired, so retry uses the saved restoration receipt.
std::fs::remove_file(backup_path(&path)).expect("retired backup");
restore(files).expect("retry restore");
assert_eq!(read(&path).expect("restored"), "{}");
assert!(!pending.exists());
}
#[test]
fn subscription_install_removes_only_switchyard_credentials() {
let dir = tempfile::tempdir().expect("directory");
let path = dir.path().join("settings.json");
let files = std::slice::from_ref(&path);
std::fs::write(&path, "{}").expect("settings");
install(
Harness::Claude,
files,
"http://localhost:4123",
"api-route",
None,
false,
)
.expect("API install");
install(
Harness::Claude,
files,
"http://localhost:4123",
"subscription",
None,
true,
)
.expect("subscription install");
let doc = object(&read(&path).expect("settings")).expect("JSON");
assert!(doc["env"].get("ANTHROPIC_AUTH_TOKEN").is_none());
assert!(doc["env"].get("ANTHROPIC_API_KEY").is_none());
assert_eq!(doc["env"]["ANTHROPIC_MODEL"], "subscription");
for key in ["ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_API_KEY"] {
for value in [
json!("user-secret"),
json!("switchyard-local"),
json!(null),
json!(false),
json!(123),
json!([]),
json!({}),
] {
let original = json!({"env":{key:value}}).to_string();
std::fs::write(&path, &original).expect("settings");
let before = std::fs::read_dir(dir.path()).expect("files").count();
assert!(
install(
Harness::Claude,
files,
"http://localhost:4123",
"subscription",
None,
true
)
.is_err()
);
assert_eq!(read(&path).expect("unchanged"), original);
assert_eq!(
std::fs::read_dir(dir.path()).expect("files").count(),
before
);
}
}
}
#[test]
fn replacement_prepares_every_file_and_rejects_changed_inputs() {
let dir = tempfile::tempdir().expect("directory");
let first = dir.path().join("first");
let blocked = dir.path().join("blocked");
std::fs::write(&first, "original").expect("first");
std::fs::write(&blocked, "not a directory").expect("blocked");
let files = vec![first.clone(), blocked.join("second")];
assert!(
replace(
&files,
&[Some("original".into()), None],
&[Some("new".into()), Some("new".into())]
)
.is_err()
);
assert_eq!(read(&first).expect("read"), "original");
assert!(
replace(
std::slice::from_ref(&first),
&[Some("stale".into())],
&[Some("new".into())]
)
.is_err()
);
assert_eq!(read(&first).expect("read"), "original");
}
}