All your machines, one app. For you and your AI agents: agent sessions, desktops, files, logs and GitHub across your Macs, Linux and Windows machines, with an MCP server.
//! Boxes: one task each, worked on by an agent CLI in a container of its own
//! on one of the user's machines. The container is the agent's sandbox, so
//! the agent runs with its permission prompts off. A box pauses when its
//! agent has gone quiet (the container stops; its files stay) and picks up
//! where it left off when it's asked something again.
//!
//! Muxin makes a box here (`scripts/create.sh`: Muxin's image, a checkout,
//! the agent's home, the container) and hands it to the machine's agent,
//! which keeps it from then on (agent/src/boxes.rs): it starts the box's
//! agent in a session, pauses it when idle whether or not Muxin is open, and
//! deletes it.
//!
//! PUBLIC API — the UI, the MCP server and the CLI depend on these signatures.
use std::sync::Arc;
use std::time::Duration;
use base64::Engine as _;
use base64::engine::general_purpose::STANDARD as B64;
use chrono::{DateTime, TimeZone, Utc};
use serde::Serialize;
use serde_json::{Value, json};
use super::Engine;
use super::sessions::agent as agent_cli;
use super::sessions::git::GitStatus;
use super::workspaces::{self, Repo};
use crate::config::MachineSpec;
use crate::ops::remote::{self, Param, sh_quote, with_params};
use crate::probe::Shell;
const CREATE_SH: &str = include_str!("scripts/create.sh");
const DOCKERFILE: &str = include_str!("scripts/Dockerfile");
const CREATE_TIMEOUT: Duration = Duration::from_secs(45 * 60);
/// This long without output from its agent, a box pauses (0: never).
pub const IDLE_MINUTES: u32 = 15;
/// How an agent CLI runs in a box, in sh in the checkout, with what it's
/// asked in `$p` (maybe empty): `new` on its task, `resume` where it left off,
/// both after `prepare` (its first-run questions answered in the box's own
/// copy of its settings). `typed`: it takes no prompt on its command line, so
/// the prompt is typed in once it's up. `dirs`: its folders in the home, made
/// on the machine when missing so a sign-in in the box stays there.
struct Launch {
new: &'static str,
resume: &'static str,
prepare: &'static str,
typed: bool,
dirs: &'static [&'static str],
}
/// Claude Code: onboarding done, permission prompts off, this folder trusted
/// (and an API key from the machine's shell accepted), in the box's own
/// ~/.claude.json (a copy of the machine's).
const CLAUDE_PREPARE: &str = r#"node -e 'const fs=require("fs"),f=process.env.HOME+"/.claude.json";let c={};try{c=JSON.parse(fs.readFileSync(f,"utf8"))}catch(e){}
c.hasCompletedOnboarding=true;c.bypassPermissionsModeAccepted=true;c.projects=c.projects||{};const p=c.projects[process.cwd()]=c.projects[process.cwd()]||{};p.hasTrustDialogAccepted=true;p.hasCompletedProjectOnboarding=true;
const k=process.env.ANTHROPIC_API_KEY;if(k){const r=c.customApiKeyResponses=c.customApiKeyResponses||{};r.approved=r.approved||[];r.rejected=r.rejected||[];if(!r.approved.includes(k.slice(-20)))r.approved.push(k.slice(-20))}
fs.writeFileSync(f,JSON.stringify(c,null,2))'"#;
/// Codex: this folder trusted for this run. Its `-c` splits the key at dots
/// and takes no quotes, so a path with a dot in it is asked about once instead.
const CODEX_PREPARE: &str = r#"trust=
case "$PWD" in *.*) ;; *) trust="projects.$PWD.trust_level=trusted" ;; esac"#;
/// Amp: the machine's settings with every command allowed, in a file of the box's own.
const AMP_PREPARE: &str = r#"node -e 'const fs=require("fs"),h=process.env.HOME;let c={};try{c=JSON.parse(fs.readFileSync(h+"/.config/amp/settings.json","utf8"))}catch(e){}c["amp.dangerouslyAllowAll"]=true;fs.writeFileSync(h+"/.muxin/amp-settings.json",JSON.stringify(c,null,2))'
export AMP_SETTINGS_FILE="$HOME/.muxin/amp-settings.json""#;
fn launch(agent: &str) -> Option<Launch> {
Some(match agent {
"claude" => Launch {
new: r#"claude --dangerously-skip-permissions ${p:+"$p"}"#,
resume: r#"claude --dangerously-skip-permissions --continue ${p:+"$p"}"#,
prepare: CLAUDE_PREPARE,
typed: false,
dirs: &[".claude"],
},
// The folder trusted on its command line, not in the machine's config.toml.
"codex" => Launch {
new: r#"codex ${trust:+-c "$trust"} --dangerously-bypass-approvals-and-sandbox ${p:+"$p"}"#,
resume: r#"codex ${trust:+-c "$trust"} --dangerously-bypass-approvals-and-sandbox resume --last ${p:+"$p"}"#,
prepare: CODEX_PREPARE,
typed: false,
dirs: &[".codex"],
},
"amp" => Launch { new: "amp", resume: "amp threads continue --last", prepare: AMP_PREPARE, typed: true, dirs: &[".config/amp", ".local/share/amp"] },
"opencode" => Launch {
new: r#"opencode ${p:+--prompt "$p"}"#,
resume: r#"opencode --continue ${p:+--prompt "$p"}"#,
prepare: "",
typed: false,
dirs: &[".config/opencode", ".local/share/opencode"],
},
"gemini" => Launch { new: r#"gemini --yolo ${p:+-i "$p"}"#, resume: r#"gemini --yolo --resume latest ${p:+-i "$p"}"#, prepare: "", typed: false, dirs: &[".gemini"] },
"pi" => Launch { new: r#"pi ${p:+"$p"}"#, resume: r#"pi --continue ${p:+"$p"}"#, prepare: "", typed: false, dirs: &[".pi"] },
_ => return None,
})
}
/// A box's launcher (`~/.muxin/start`) for `agent`, and whether its prompt is
/// typed in: for a box changing agents (see sessions::handoff).
pub(crate) fn launcher(agent: &str) -> Option<(String, bool)> {
launch(agent).map(|l| (start_script(&l), l.typed))
}
/// The agent CLIs a box can run (ids from `sessions::AGENTS`).
pub const BOX_AGENTS: &[&str] = &["claude", "codex", "amp", "opencode", "gemini", "pi"];
/// Every agent CLI's folders in the home (sign-ins, settings, history): the
/// machine's are mounted into each box, so its agents are signed in as there.
const AGENT_DIRS: &[&str] = &[".claude", ".codex", ".gemini", ".pi", ".config/amp", ".local/share/amp", ".config/opencode", ".local/share/opencode"];
/// The agent folders with databases in them (SQLite). Where Docker runs in a
/// VM (a Mac), a container can't lock files in the machine's folders, so these
/// aren't shared there: the box gets a copy of their sign-in (`DB_COPY`).
const DB_DIRS: &[&str] = &[".codex", ".local/share/opencode"];
const DB_COPY: &[&str] = &[".codex/auth.json", ".codex/config.toml", ".local/share/opencode/auth.json"];
/// One box, as the snapshot lists it.
#[derive(Debug, Clone, Default, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct BoxInfo {
/// "box-ab12cd".
pub id: String,
pub machine_id: String,
pub name: String,
/// "owner/name", or the git URL it was cloned from.
pub repo: String,
pub branch: String,
pub agent: String,
pub agent_name: String,
/// "running", "starting" or "paused".
pub state: String,
/// Its agent printed something in the last few seconds: it's working.
pub busy: bool,
/// An unread notice from its agent ("waiting", "bell" or "exited").
pub attention: Option<String>,
/// Its agent's session (`<machine>/<box id>`) while it runs.
pub session_id: Option<String>,
/// What it was first asked.
pub task: String,
/// The checkout on its machine it was made from (a local project), if it was.
#[serde(skip_serializing_if = "Option::is_none")]
pub checkout: Option<String>,
/// The checkout on the machine.
pub path: String,
pub idle_minutes: u32,
pub created_at: Option<DateTime<Utc>>,
/// When it last started or paused.
pub state_at: Option<DateTime<Utc>>,
/// What its work changed: branch, files, commits, pull request.
#[serde(skip_serializing_if = "Option::is_none")]
pub git: Option<GitStatus>,
}
/// The box a session belongs to: its agent's (named as the box) or one of
/// its shells ("<box id>-sh-<n>").
pub(crate) fn box_of_session<'a>(name: &str, boxes: &'a [BoxInfo]) -> Option<&'a BoxInfo> {
boxes.iter().find(|b| name == b.id || name.strip_prefix(b.id.as_str()).and_then(|r| r.strip_prefix("-sh-")).is_some_and(|n| !n.is_empty() && n.chars().all(|c| c.is_ascii_digit())))
}
/// The boxes in a machine agent's `discover` reply (agents before 0.3 have none).
pub(crate) fn parse(machine_id: &str, reply: &Value) -> Vec<BoxInfo> {
let ts = |v: &Value| v.as_i64().filter(|t| *t > 0).and_then(|t| Utc.timestamp_opt(t, 0).single());
reply["boxes"]
.as_array()
.into_iter()
.flatten()
.filter_map(|b| {
let id = b["id"].as_str().filter(|i| i.starts_with("box-"))?.to_string();
let agent = b["agent"].as_str().unwrap_or("").to_string();
let str_of = |k: &str| b[k].as_str().unwrap_or("").to_string();
Some(BoxInfo {
machine_id: machine_id.to_string(),
name: b["name"].as_str().filter(|n| !n.is_empty()).map(str::to_string).unwrap_or_else(|| id.clone()),
repo: str_of("repo"),
branch: str_of("branch"),
agent_name: super::sessions::agent(&agent).map(|k| k.name.to_string()).unwrap_or_default(),
agent,
state: b["state"].as_str().unwrap_or("paused").to_string(),
task: str_of("task"),
checkout: b["checkout"].as_str().filter(|c| !c.is_empty()).map(str::to_string),
path: str_of("path"),
idle_minutes: b["idle_minutes"].as_u64().map(|m| m as u32).unwrap_or(IDLE_MINUTES),
created_at: ts(&b["created"]),
state_at: ts(&b["state_at"]),
id,
..Default::default()
})
})
.collect()
}
/// What `box_create` needs.
#[derive(Debug, Clone, Default)]
pub struct CreateBox {
/// "owner/name" on GitHub, or a git URL.
pub repo: String,
/// What the agent is asked to do.
pub prompt: String,
/// An agent CLI from `BOX_AGENTS`; Claude Code when empty.
pub agent: String,
/// The machine; else the one with Docker and the most free memory.
pub machine: Option<String>,
/// Its name; else from the task.
pub name: Option<String>,
/// The branch it works on; else "box/<name>".
pub branch: Option<String>,
/// What to start from: a branch, tag, commit or "pull/<n>/head"; else the default branch.
pub git_ref: Option<String>,
pub cpus: Option<u32>,
pub memory_gb: Option<u32>,
pub idle_minutes: Option<u32>,
}
/// A box about to be made: everything worked out but the machine's side.
struct Plan {
id: String,
name: String,
agent: String,
repo: Repo,
/// `repo` is a checkout on the box's machine (a local project): cloned
/// from there, with its uncommitted changes.
local: bool,
/// The GitHub repository it pushes to ("owner/name"): `repo`'s, or the checkout's origin's.
github: Option<String>,
git_ref: String,
branch: String,
task: String,
cpus: Option<u32>,
memory_gb: Option<u32>,
idle_minutes: u32,
}
impl Engine {
/// Every box on the user's machines, newest first.
pub fn boxes(&self) -> Vec<BoxInfo> {
self.current().boxes.clone()
}
/// A box by id ("box-ab12cd", or "<machine>/box-ab12cd").
pub fn find_box(&self, id: &str) -> Result<BoxInfo, String> {
let bare = id.trim().rsplit('/').next().unwrap_or("");
self.boxes().into_iter().find(|b| b.id == bare).ok_or_else(|| format!("No box called {bare}. See your boxes with box_list (`muxin box ls`)."))
}
/// Starts making a box (an operation) and returns the operation's id and
/// the new box's.
pub fn box_create(self: &Arc<Self>, req: CreateBox) -> Result<(u64, String), String> {
if self.demo_world().is_some() {
return Err("The demo doesn't make boxes.".into());
}
let agent = if req.agent.trim().is_empty() { "claude".to_string() } else { req.agent.trim().to_ascii_lowercase() };
if launch(&agent).is_none() {
return Err(format!("A box can't run \"{agent}\". It runs: {}.", BOX_AGENTS.join(", ")));
}
let task = req.prompt.trim().to_string();
let gh_host = workspaces::github_web_host(&self.settings().github.api_url);
let repo = workspaces::normalize_repo(&req.repo, &gh_host)?;
let git_ref = req.git_ref.map(|r| r.trim().to_string()).unwrap_or_default();
if !git_ref.is_empty() {
workspaces::validate_git_ref(&git_ref)?;
}
let name = match req.name.map(|n| n.trim().to_string()).filter(|n| !n.is_empty()) {
Some(n) if n.chars().count() > 80 || n.chars().any(char::is_control) => return Err("The box's name is too long or has odd characters.".into()),
Some(n) => n,
None => name_from(&task, &repo.short_name),
};
let branch = req.branch.map(|b| b.trim().to_string()).filter(|b| !b.is_empty()).unwrap_or_else(|| format!("box/{}", short_slug(&name)));
workspaces::validate_git_ref(&branch)?;
// A folder on a machine: a checkout there (a local project), so the box goes there too.
let local = repo.url.starts_with('/') || repo.url.starts_with("~/");
if local && req.machine.as_deref().is_none_or(|m| m.trim().is_empty()) {
return Err(format!("Say which machine {} is on.", repo.shown));
}
let spec = self.box_machine(req.machine.as_deref())?;
let github = match local {
true => self.checkouts_of(&spec.id).into_iter().find(|c| workspaces::same_folder(&c.path, &repo.url)).and_then(|c| c.repo),
false => repo.on_github.then(|| workspaces::github_full_name(&repo)).flatten(),
};
let taken: Vec<String> = self.boxes().into_iter().map(|b| b.id).collect();
let id = loop {
let id = format!("box-{}", workspaces::random_id(6));
if !taken.contains(&id) {
break id;
}
};
let plan = Plan { id: id.clone(), name, agent, repo, local, github, git_ref, branch, task, cpus: req.cpus, memory_gb: req.memory_gb, idle_minutes: req.idle_minutes.unwrap_or(IDLE_MINUTES) };
let op = self.begin_op("box", format!("Make box {} on {}", plan.name, spec.name), Some(spec.id.clone()), None);
let me = self.clone();
self.runtime().spawn(async move {
let result = me.run_box_create(op, &spec, &plan).await;
if let Err(e) = &result {
me.op_log(op, format!("error: {e}"));
// Whatever was made goes again.
let _ = agent_cli::ctl(&spec, &json!({ "op": "box_delete", "box_id": plan.id })).await;
}
me.op_finish(op, result);
let _ = me.refresh_sessions(&spec.id).await;
});
Ok((op, id))
}
/// The machine a box goes on: the one asked for, or the one with Docker and
/// the most free memory.
fn box_machine(&self, asked: Option<&str>) -> Result<MachineSpec, String> {
let snap = self.current();
let usable = |m: &crate::fleet::model::Machine| m.status == "online" && !m.platform.starts_with("windows") && !m.is_disconnected();
let has_docker = |m: &crate::fleet::model::Machine| m.probe.as_ref().is_some_and(|p| p.docker.is_some());
let m = match asked.map(str::trim).filter(|a| !a.is_empty()) {
Some(a) => {
let m = snap.machines.iter().find(|m| m.id == a || m.name.eq_ignore_ascii_case(a)).ok_or_else(|| format!("No machine called {a}."))?;
if m.platform.starts_with("windows") {
return Err(format!("Boxes don't run on Windows machines yet ({}). Pick a Linux machine or a Mac with Docker.", m.name));
}
if m.status != "online" {
return Err(format!("{} isn't online.", m.name));
}
m
}
None => snap
.machines
.iter()
.filter(|m| usable(m) && has_docker(m))
.max_by_key(|m| m.probe.as_ref().and_then(|p| p.mem_total.zip(p.mem_used)).map(|(t, u)| t.saturating_sub(u)).unwrap_or(0))
.ok_or("None of your machines can run a box: it needs one that's online with Docker (a Linux machine, or a Mac with Docker Desktop, OrbStack or Colima).")?,
};
self.machine(&m.id).map(|(s, _)| s).ok_or_else(|| format!("{} isn't in Muxin anymore.", m.name))
}
async fn run_box_create(self: &Arc<Self>, op: u64, spec: &MachineSpec, plan: &Plan) -> Result<(), String> {
self.op_log(op, format!("▸ Making {} ({}) on {} with {}", plan.id, plan.name, spec.name, plan.agent));
let probe = self.machine(&spec.id).and_then(|(_, p)| p);
// The box's agent keeps it from here on: it has to be this build's.
agent_cli::ensure(spec, probe.as_ref()).await?;
// GitHub: the token clones a private repo and lets the agent push and
// open pull requests; commits are the user's, with their noreply address.
let settings = self.settings().github;
// A checkout Muxin hasn't looked at yet: where it pushes, asked of it.
let github = match (&plan.github, plan.local) {
(None, true) => checkout_github(spec, &plan.repo.url, &workspaces::github_web_host(&settings.api_url)).await,
(g, _) => g.clone(),
};
// The GitHub host it pushes to: its URL's, or (a checkout) GitHub's when its origin is there.
let gh_host = match (plan.repo.on_github, &github) {
(true, _) => Some(plan.repo.host.clone()),
(false, Some(_)) => Some(workspaces::github_web_host(&settings.api_url)),
(false, None) => None,
};
let token = match &gh_host {
Some(h) => self.github().git_credentials(&settings).await.filter(|(host, _)| host == h).map(|(_, t)| t),
None => None,
};
let identity = match self.github().viewer(&settings).await {
Ok(v) => self.github().commit_identity(&settings, &v.login).await.ok(),
Err(_) => None,
};
if token.is_none() && gh_host.is_some() {
self.op_log(op, "! No GitHub token: the agent can't push or open pull requests from the box");
}
let gh_host = gh_host.unwrap_or_default();
let l = launch(&plan.agent).ok_or("That agent can't run in a box.")?;
let mut env: Vec<(String, String)> = vec![("MUXIN_BOX".into(), plan.id.clone())];
if let Some(t) = &token {
env.push(("GH_TOKEN".into(), t.clone()));
if gh_host != "github.com" {
env.push(("GH_HOST".into(), gh_host.clone()));
env.push(("GH_ENTERPRISE_TOKEN".into(), t.clone()));
}
}
let files = home_files(&l, &env, identity.as_ref(), token.as_ref().map(|_| gh_host.as_str()));
let encoded: Vec<String> = files.iter().map(|(path, mode, text)| format!("{path}\t{mode}\t{}", B64.encode(text))).collect();
// Signed in as on the machine: its agent folders mounted (the box's
// agent's made when missing, so a sign-in in the box stays), and a
// copy of Claude Code's ~/.claude.json (its MCP servers and the like).
let mounts: Vec<String> = AGENT_DIRS.iter().map(|d| d.to_string()).collect();
let ensure: Vec<String> = l.dirs.iter().map(|d| d.to_string()).collect();
let copy: Vec<String> = vec![".claude.json".into()];
let db_dirs: Vec<String> = DB_DIRS.iter().map(|d| d.to_string()).collect();
let db_copy: Vec<String> = DB_COPY.iter().map(|d| d.to_string()).collect();
// Only a clone from GitHub needs the token (a checkout is cloned from its folder).
let header = token.as_ref().filter(|_| !plan.local).map(|t| format!("AUTHORIZATION: basic {}", B64.encode(format!("x-access-token:{t}")))).unwrap_or_default();
let image = format!("muxen-box:{:08x}", fnv(DOCKERFILE.as_bytes()) as u32);
let container = format!("muxen-{}", plan.id);
let hostname = short_slug(&plan.name);
let cpus = plan.cpus.map(|c| c.clamp(1, 64).to_string()).unwrap_or_default();
let memory = plan.memory_gb.map(|m| format!("{}g", m.clamp(1, 512))).unwrap_or_default();
let files_param = encoded.join("\n");
let script = with_params(
Shell::Sh,
&[
("OR_ID", Param::Str(&plan.id)),
("OR_CONTAINER", Param::Str(&container)),
("OR_HOSTNAME", Param::Str(&hostname)),
("OR_IMAGE", Param::Str(&image)),
("OR_DOCKERFILE", Param::Str(DOCKERFILE)),
("OR_REPO", Param::Str(&plan.repo.url)),
("OR_LOCAL", Param::Bool(plan.local)),
("OR_REPO_SHOWN", Param::Str(&plan.repo.shown)),
("OR_REF", Param::Str(&plan.git_ref)),
("OR_BRANCH", Param::Str(&plan.branch)),
("OR_AUTH", Param::Str(&header)),
("OR_FILES", Param::Str(&files_param)),
("OR_COPY", Param::List(©)),
("OR_MOUNTS", Param::List(&mounts)),
("OR_ENSURE", Param::List(&ensure)),
("OR_DB_DIRS", Param::List(&db_dirs)),
("OR_DB_COPY", Param::List(&db_copy)),
("OR_CPUS", Param::Str(&cpus)),
("OR_MEM", Param::Str(&memory)),
],
CREATE_SH,
);
let mut secrets: Vec<String> = env.iter().filter(|(k, _)| k != "MUXIN_BOX" && k != "GH_HOST").map(|(_, v)| v.clone()).collect();
if !header.is_empty() {
secrets.push(header.clone());
secrets.push(header.trim_start_matches("AUTHORIZATION: basic ").to_string());
}
let printed = remote::run_lines(self, op, spec, Shell::Sh, script, &secrets, CREATE_TIMEOUT).await?;
let field = |key: &str| printed.iter().find_map(|l| l.strip_prefix(&format!("{key}="))).map(|v| v.trim().to_string());
let record = json!({
"id": plan.id,
"name": plan.name,
"repo": github.clone().unwrap_or_else(|| plan.repo.shown.clone()),
"checkout": plan.local.then(|| plan.repo.shown.clone()),
"branch": plan.branch,
"agent": plan.agent,
"task": plan.task,
"image": image,
"container": container,
"docker": field("docker").unwrap_or_default(),
"type_prompt": l.typed,
"idle_minutes": plan.idle_minutes,
"created": Utc::now().timestamp(),
});
agent_cli::ctl(spec, &json!({ "op": "box_save", "box": record })).await?;
self.op_log(op, format!("▸ Starting {} in the box", super::sessions::agent(&plan.agent).map(|k| k.name).unwrap_or(&plan.agent)));
let prompt = (!plan.task.is_empty()).then_some(plan.task.as_str());
agent_cli::ctl(spec, &json!({ "op": "box_resume", "box_id": plan.id, "prompt": prompt })).await?;
self.op_log(op, format!("✓ {} is working on it", plan.id));
Ok(())
}
/// Asks a box's agent something: typed in when it's running, else the box
/// starts again and its agent continues with it. No text just starts it.
pub async fn box_send(self: &Arc<Self>, id: &str, text: Option<&str>) -> Result<BoxInfo, String> {
let b = self.find_box(id)?;
if self.demo_world().is_some() {
return Err("The demo's boxes are only for show.".into());
}
let (spec, probe) = self.machine(&b.machine_id).ok_or_else(|| format!("{} isn't in Muxin anymore.", b.machine_id))?;
agent_cli::ensure(&spec, probe.as_ref()).await?;
let text = text.map(str::trim).filter(|t| !t.is_empty());
agent_cli::ctl(&spec, &json!({ "op": "box_resume", "box_id": b.id, "prompt": text })).await?;
let _ = self.refresh_sessions(&spec.id).await;
self.find_box(&b.id)
}
/// Opens a shell in a box, beside its agent: bash in its container and
/// checkout (a paused box starts again first). Pausing the box ends it.
pub async fn box_shell(self: &Arc<Self>, id: &str, cols: u16, rows: u16) -> Result<super::sessions::SessionInfo, String> {
let mut b = self.find_box(id)?;
if self.demo_world().is_some() {
return Err("The demo's boxes are only for show.".into());
}
if b.state != "running" {
b = self.box_send(&b.id, None).await?;
}
let (spec, probe) = self.machine(&b.machine_id).ok_or_else(|| format!("{} isn't in Muxin anymore.", b.machine_id))?;
agent_cli::ensure(&spec, probe.as_ref()).await?;
let reply = agent_cli::ctl(&spec, &json!({ "op": "box_shell", "box_id": b.id, "cols": cols, "rows": rows })).await?;
let name = reply["session"].as_str().ok_or("The machine's agent didn't name the shell.")?.to_string();
let found = self.refresh_sessions(&spec.id).await?;
found.sessions.into_iter().find(|s| s.name == name).ok_or_else(|| format!("The shell in {} ended right away.", b.id))
}
/// Pauses a box: its agent ends and its container stops; its files stay.
pub async fn box_pause(self: &Arc<Self>, id: &str) -> Result<BoxInfo, String> {
let b = self.find_box(id)?;
if self.demo_world().is_some() {
return Err("The demo's boxes are only for show.".into());
}
let (spec, probe) = self.machine(&b.machine_id).ok_or_else(|| format!("{} isn't in Muxin anymore.", b.machine_id))?;
agent_cli::ensure(&spec, probe.as_ref()).await?;
agent_cli::ctl(&spec, &json!({ "op": "box_pause", "box_id": b.id })).await?;
let _ = self.refresh_sessions(&spec.id).await;
self.find_box(&b.id)
}
/// Deletes a box: its container and its folder, with any work in it that
/// wasn't pushed. Its branch on GitHub stays.
pub async fn box_destroy(self: &Arc<Self>, id: &str) -> Result<BoxInfo, String> {
let b = self.find_box(id)?;
if self.demo_world().is_some() {
return Err("The demo's boxes are only for show.".into());
}
let (spec, probe) = self.machine(&b.machine_id).ok_or_else(|| format!("{} isn't in Muxin anymore.", b.machine_id))?;
agent_cli::ensure(&spec, probe.as_ref()).await?;
agent_cli::ctl(&spec, &json!({ "op": "box_delete", "box_id": b.id })).await?;
let _ = self.refresh_sessions(&spec.id).await;
Ok(b)
}
}
/// The GitHub repository ("owner/name") a checkout on a machine pushes to: its origin's.
async fn checkout_github(spec: &MachineSpec, path: &str, gh_host: &str) -> Option<String> {
let folder = match path.strip_prefix("~/") {
Some(rest) => format!("\"$HOME\"/{}", sh_quote(rest)),
None => sh_quote(path),
};
let url = remote::output(spec, Shell::Sh, format!("git -C {folder} remote get-url origin\n"), Duration::from_secs(30)).await.ok()?;
github_name(url.trim(), gh_host)
}
/// "owner/name" of a git URL on the GitHub host: https, or ssh (git@host:owner/name).
pub(crate) fn github_name(url: &str, gh_host: &str) -> Option<String> {
let ssh = [format!("git@{gh_host}:"), format!("ssh://git@{gh_host}/")];
let https = match ssh.iter().find_map(|p| url.strip_prefix(p.as_str())) {
Some(path) => format!("https://{gh_host}/{path}"),
None => url.to_string(),
};
let repo = workspaces::normalize_repo(&https, gh_host).ok()?;
repo.on_github.then(|| workspaces::github_full_name(&repo)).flatten()
}
/// The files of a box's home Muxin writes: path (under /home/box), mode and contents.
fn home_files(l: &Launch, env: &[(String, String)], identity: Option<&(String, String)>, git_host: Option<&str>) -> Vec<(String, &'static str, String)> {
let mut files: Vec<(String, &'static str, String)> = Vec::new();
files.push((".muxin/start".into(), "755", start_script(l)));
let env_text: String = env.iter().map(|(k, v)| format!("{k}={}\n", sh_quote(v))).collect();
files.push((".muxin/env".into(), "600", env_text));
files.push((".bashrc".into(), "644", BASHRC.into()));
files.push((".profile".into(), "644", ". \"$HOME/.bashrc\"\n".into()));
let mut gitconfig = String::new();
if let Some((name, email)) = identity {
gitconfig.push_str(&format!("[user]\n\tname = {}\n\temail = {}\n", git_value(name), git_value(email)));
}
if let Some(host) = git_host {
files.push((".muxin/git-credential".into(), "755", GIT_CREDENTIAL.into()));
gitconfig.push_str(&format!("[credential \"https://{host}\"]\n\thelper = /home/box/.muxin/git-credential\n"));
// A box has no ssh keys: ssh remotes (a checkout's, say) go over https, with the token.
gitconfig.push_str(&format!("[url \"https://{host}/\"]\n\tinsteadOf = git@{host}:\n\tinsteadOf = ssh://git@{host}/\n"));
}
gitconfig.push_str("[init]\n\tdefaultBranch = main\n[push]\n\tautoSetupRemote = true\n");
files.push((".gitconfig".into(), "644", gitconfig));
files
}
/// `~/.muxin/start` in a box: what its session runs.
fn start_script(l: &Launch) -> String {
format!(
r#"# Starts this box's agent (Muxin wrote this; the box's session runs it):
# the first time on its task, after that where it left off, asked what's in
# ~/.muxin/next.
cd "${{MUXIN_WORKDIR:-$PWD}}" || exit 1
if [ -f "$HOME/.muxin/env" ]; then set -a; . "$HOME/.muxin/env"; set +a; fi
p=
if [ -f "$HOME/.muxin/next" ]; then p=$(cat "$HOME/.muxin/next"); rm -f "$HOME/.muxin/next"; fi
{prepare}
if [ -f "$HOME/.muxin/started" ]; then
if [ -f .agents/resume ]; then
echo "▸ Running .agents/resume"
if [ -x .agents/resume ]; then ./.agents/resume; else sh .agents/resume; fi
fi
exec {resume}
fi
touch "$HOME/.muxin/started"
exec {new}
"#,
resume = l.resume,
new = l.new,
prepare = l.prepare
)
}
const BASHRC: &str = r#"# A Muxin box: its GitHub token, and the agent CLIs on the PATH, for shells too.
if [ -f "$HOME/.muxin/env" ]; then set -a; . "$HOME/.muxin/env"; set +a; fi
case ":$PATH:" in *:/opt/agents/bin:*) ;; *) PATH="/opt/agents/bin:$PATH" ;; esac
PS1='\u@\h:\w\$ '
"#;
const GIT_CREDENTIAL: &str = r#"#!/bin/sh
# Git's credentials in this box: the GitHub token Muxin gave it.
[ "$1" = get ] || exit 0
[ -f "$HOME/.muxin/env" ] && . "$HOME/.muxin/env"
[ -n "${GH_TOKEN:-}" ] || exit 0
echo username=x-access-token
echo "password=$GH_TOKEN"
"#;
/// A value for .gitconfig: quoted, with its quotes and backslashes escaped.
fn git_value(s: &str) -> String {
format!("\"{}\"", s.replace('\\', "\\\\").replace('"', "\\\""))
}
/// A box's name from its task: its first words.
fn name_from(task: &str, repo: &str) -> String {
let words: Vec<&str> = task.split_whitespace().take(6).collect();
if words.is_empty() {
return repo.to_string();
}
let mut name = words.join(" ");
if name.chars().count() > 48 {
name = name.chars().take(48).collect::<String>().trim_end().to_string();
}
name.trim_end_matches(['.', ',', ':', ';']).to_string()
}
/// A slug short enough for a branch or a hostname ("box" for one without letters).
fn short_slug(s: &str) -> String {
if !s.chars().any(|c| c.is_ascii_alphanumeric()) {
return "box".into();
}
let mut out: String = crate::util::slug(s).chars().take(40).collect();
while out.ends_with('-') {
out.pop();
}
out
}
fn fnv(bytes: &[u8]) -> u64 {
let mut h: u64 = 0xcbf2_9ce4_8422_2325;
for b in bytes {
h ^= *b as u64;
h = h.wrapping_mul(0x0000_0100_0000_01b3);
}
h
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn every_box_agent_launches() {
for a in BOX_AGENTS {
assert!(launch(a).is_some(), "{a}");
assert!(super::super::sessions::agent(a).is_some(), "{a} is a session agent");
}
assert!(launch("shell").is_none());
}
#[test]
fn the_start_script_continues_after_the_first_time() {
let s = start_script(&launch("codex").unwrap());
let resume = s.find("resume --last").unwrap();
let started = s.find("touch \"$HOME/.muxin/started\"").unwrap();
assert!(resume < started, "resume is the path once started");
// Trusted on its command line: the machine's own config.toml stays as it is.
assert!(s.contains(r#"trust="projects.$PWD.trust_level=trusted""#));
assert!(s.find("trust=").unwrap() < s.find(r#"exec codex ${trust:+-c "$trust"} --dangerously-bypass-approvals-and-sandbox ${p:+"$p"}"#).unwrap());
// Claude Code's first-run answers go in the box's own ~/.claude.json, before it starts.
let claude = start_script(&launch("claude").unwrap());
assert!(claude.find("hasTrustDialogAccepted").unwrap() < claude.find("exec claude").unwrap());
}
#[test]
fn names_and_branches_from_the_task() {
assert_eq!(name_from("Fix the login redirect loop when the session expires.", "api"), "Fix the login redirect loop when");
assert_eq!(name_from(" ", "api"), "api");
assert_eq!(short_slug("Fix the login redirect loop when"), "fix-the-login-redirect-loop-when");
assert_eq!(short_slug("!!!"), "box");
}
#[test]
fn home_files_carry_the_github_token_and_identity_only() {
let env = vec![("GH_TOKEN".to_string(), "ghp_x".to_string())];
let files = home_files(&launch("claude").unwrap(), &env, Some(&("Ada \"L\"".into(), "[email protected]".into())), Some("github.com"));
let get = |p: &str| files.iter().find(|(path, _, _)| path == p).map(|(_, mode, text)| (*mode, text.clone()));
let (mode, env_text) = get(".muxin/env").unwrap();
assert_eq!(mode, "600");
assert!(env_text.contains("GH_TOKEN='ghp_x'"));
let (_, git) = get(".gitconfig").unwrap();
assert!(git.contains(r#"name = "Ada \"L\"""#));
assert!(git.contains("[credential \"https://github.com\"]"));
// The agents' own folders come from the machine, not from Muxin.
assert!(files.iter().all(|(p, _, _)| !p.starts_with(".claude") && !p.starts_with(".codex") && !p.starts_with(".config")));
}
#[test]
fn each_agent_keeps_its_folders_on_the_machine() {
for a in BOX_AGENTS {
let l = launch(a).unwrap();
assert!(!l.dirs.is_empty(), "{a}");
assert!(l.dirs.iter().all(|d| AGENT_DIRS.contains(d)), "{a}'s folders are mounted");
}
}
#[test]
fn a_checkouts_origin_names_its_github_repo() {
assert_eq!(github_name("https://github.com/acme/api.git", "github.com").as_deref(), Some("acme/api"));
assert_eq!(github_name("[email protected]:acme/api.git", "github.com").as_deref(), Some("acme/api"));
assert_eq!(github_name("ssh://[email protected]/acme/api", "github.com").as_deref(), Some("acme/api"));
assert_eq!(github_name("[email protected]:acme/api.git", "github.com"), None);
assert_eq!(github_name("/srv/git/api.git", "github.com"), None);
}
#[test]
fn sessions_belong_to_their_box() {
let boxes = vec![BoxInfo { id: "box-ab12cd".into(), ..Default::default() }];
assert_eq!(box_of_session("box-ab12cd", &boxes).map(|b| b.id.as_str()), Some("box-ab12cd"));
assert_eq!(box_of_session("box-ab12cd-sh-2", &boxes).map(|b| b.id.as_str()), Some("box-ab12cd"));
assert!(box_of_session("box-ab12cd-sh-", &boxes).is_none());
assert!(box_of_session("claude-3f9a", &boxes).is_none());
}
#[test]
fn parses_the_agents_boxes() {
let reply = json!({ "boxes": [
{ "id": "box-ab12cd", "name": "Fix login", "repo": "acme/api", "branch": "box/fix-login", "agent": "codex", "state": "running", "task": "Fix login", "path": "/home/a/muxen/boxes/box-ab12cd/repo", "created": 1_700_000_000, "state_at": 1_700_000_100 },
{ "id": "not-a-box" },
] });
let found = parse("beelink", &reply);
assert_eq!(found.len(), 1);
assert_eq!(found[0].agent_name, "Codex");
assert_eq!(found[0].idle_minutes, IDLE_MINUTES);
assert_eq!(found[0].machine_id, "beelink");
assert!(parse("beelink", &json!({})).is_empty());
}
}