Add a shared sandbox launcher for Linux and macOS (#62353)

## Why

Running each helper through `codex sandbox` keeps a separate Codex
supervisor process alive for each helper. A shared launcher lets one
supervisor manage multiple helpers concurrently.

## What changed

Add a launcher mode that multiplexes helper I/O and exit status over a
newline-delimited JSON protocol on stdin and stdout. Each helper uses
the host sandbox setup with its own configuration and network proxy.
The launcher applies backpressure to helper I/O, drains buffered output
on exit, and stops tracked helpers when the controller disconnects.

## Testing

Add integration coverage for per-helper filesystem isolation, stdin
backpressure, buffered output after helper exit, and controller
disconnect while output is blocked.

GitOrigin-RevId: a7f75fdedbe0928ff5b93a412c7223371d0f321a
This commit is contained in:
Charlie Marsh
2026-11-18 20:14:05 +00:00
committed by copyberry
parent 60fcb1649f
commit 097a8a7439
7 changed files with 939 additions and 1 deletions
+1
View File
@@ -2577,6 +2577,7 @@ dependencies = [
"app_test_support",
"assert_cmd",
"assert_matches",
"base64 0.22.1",
"chrono",
"clap",
"clap_complete",
+2
View File
@@ -27,6 +27,7 @@ doctest = false
workspace = true
[dependencies]
base64 = { workspace = true }
codex-utils-process = { workspace = true }
anyhow = { workspace = true }
chrono = { workspace = true }
@@ -104,6 +105,7 @@ tokio = { workspace = true, features = [
"process",
"rt-multi-thread",
"signal",
"sync",
"time",
] }
toml = { workspace = true }
+19 -1
View File
@@ -121,6 +121,23 @@ pub async fn run_command_under_linux_sandbox(
codex_linux_sandbox_exe: Option<PathBuf>,
loader_overrides: LoaderOverrides,
) -> anyhow::Result<()> {
let mut launch = start_command_under_linux_sandbox(
command,
codex_linux_sandbox_exe,
loader_overrides,
/*piped*/ false,
)
.await?;
launch.wait_and_exit().await
}
/// Start a Linux sandbox child while retaining the resources required for its lifetime.
pub async fn start_command_under_linux_sandbox(
command: LinuxSandboxCommand,
codex_linux_sandbox_exe: Option<PathBuf>,
loader_overrides: LoaderOverrides,
piped: bool,
) -> anyhow::Result<StartedSandboxChild> {
let LinuxSandboxCommand {
transparent_tcp,
sandbox_state,
@@ -135,7 +152,7 @@ pub async fn run_command_under_linux_sandbox(
&permissions_profile,
include_managed_config,
);
run_command_under_sandbox(
start_command_under_sandbox(
DebugSandboxConfigOptions {
sandbox_state,
permissions_profile,
@@ -149,6 +166,7 @@ pub async fn run_command_under_linux_sandbox(
SandboxType::Linux { transparent_tcp },
/*log_denials*/ false,
&[],
piped,
)
.await
}
+2
View File
@@ -3,6 +3,8 @@ pub(crate) mod debug_sandbox;
mod exit_status;
mod git_credential;
pub(crate) mod login;
#[cfg(any(target_os = "linux", target_os = "macos"))]
pub mod shared_sandbox_launcher;
use clap::Args;
use clap::Parser;
+22
View File
@@ -1047,6 +1047,17 @@ fn main() -> anyhow::Result<()> {
codex_build_info::initialize!();
let remote_control_disabled = codex_app_server::take_remote_control_disabled_env();
arg0_dispatch_or_else(move |arg0_paths: Arg0DispatchPaths| async move {
#[cfg(any(target_os = "linux", target_os = "macos"))]
if std::env::args_os().nth(1).as_deref()
== Some(std::ffi::OsStr::new("--codex-run-as-sandbox-launcher"))
{
anyhow::ensure!(
std::env::args_os().len() == 2,
"--codex-run-as-sandbox-launcher does not accept additional arguments"
);
return codex_cli::shared_sandbox_launcher::run(arg0_paths.codex_linux_sandbox_exe)
.await;
}
// Finish polling the large subcommand dispatcher before polling interactive TUI events.
if let Some(tui) = Box::pin(dispatch_cli(arg0_paths, remote_control_disabled)).await? {
tui.await?;
@@ -3646,6 +3657,17 @@ enabled = true
);
}
#[test]
fn sandbox_runs_launcher_executable() {
let cli = MultitoolCli::try_parse_from(["codex", "sandbox", "launcher", "--help"])
.expect("parse sandbox executable");
let Some(Subcommand::Sandbox(command)) = cli.subcommand else {
panic!("expected sandbox command");
};
assert!(command.subcommand.is_none());
assert_eq!(command.host.command, vec!["launcher", "--help"]);
}
#[test]
fn sandbox_uninstall_respects_command_separator() {
let cli = MultitoolCli::try_parse_from(["codex", "sandbox", "uninstall"]).expect("parse");
+461
View File
@@ -0,0 +1,461 @@
//! Private stdio supervisor for helpers that would otherwise each retain a `codex sandbox` process.
//!
//! Each launch goes through the ordinary host sandbox configuration and gets its own proxy. The caller
//! must start the supervisor with the same environment that it would give `codex sandbox`.
use std::collections::HashMap;
use std::ops::ControlFlow;
use std::os::fd::AsFd;
use std::os::fd::AsRawFd;
use std::os::fd::OwnedFd;
use std::os::unix::fs::FileTypeExt;
use std::os::unix::process::ExitStatusExt;
use std::path::PathBuf;
use std::sync::Arc;
use anyhow::Context;
use base64::Engine;
use base64::engine::general_purpose::STANDARD as BASE64;
use codex_config::LoaderOverrides;
use codex_utils_absolute_path::AbsolutePathBuf;
use codex_utils_cli::CliConfigOverrides;
use serde::Deserialize;
use serde::Serialize;
use serde_json::Value;
use serde_json::json;
use tokio::io::AsyncBufReadExt;
use tokio::io::AsyncRead;
use tokio::io::AsyncReadExt;
use tokio::io::AsyncWrite;
use tokio::io::AsyncWriteExt;
use tokio::io::BufReader;
use tokio::io::Interest;
use tokio::io::unix::AsyncFd;
use tokio::sync::Semaphore;
use tokio::sync::mpsc;
use tokio::sync::watch;
#[cfg(target_os = "linux")]
use crate::LinuxSandboxCommand as HostSandboxCommand;
use crate::SandboxStateArgs;
#[cfg(target_os = "macos")]
use crate::SeatbeltCommand as HostSandboxCommand;
#[cfg(target_os = "linux")]
use crate::debug_sandbox::start_command_under_linux_sandbox as start_command_under_host_sandbox;
#[cfg(target_os = "macos")]
use crate::debug_sandbox::start_command_under_seatbelt as start_command_under_host_sandbox;
const MAX_MESSAGE_BYTES: usize = 16 * 1024 * 1024;
const OUTPUT_WINDOW: usize = 64;
#[derive(Deserialize)]
#[serde(tag = "method", content = "params", rename_all = "camelCase")]
enum Request {
Start(Start),
Write { id: String, data: String },
CloseStdin { id: String },
Terminate { id: String },
OutputConsumed { id: String },
}
#[derive(Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
struct Start {
id: String,
cwd: PathBuf,
command: Vec<String>,
#[serde(default)]
config_overrides: Vec<String>,
#[serde(default)]
allow_unix_sockets: Vec<AbsolutePathBuf>,
}
struct Process {
stdin: mpsc::Sender<Option<Vec<u8>>>,
stop: mpsc::Sender<()>,
output: Arc<Semaphore>,
}
#[derive(Serialize)]
#[serde(
tag = "type",
rename_all = "camelCase",
rename_all_fields = "camelCase"
)]
enum ProcessExitStatus {
Exit { code: u32 },
Signal { signal: i32, core_dumped: bool },
}
struct Finished {
id: String,
status: Result<ProcessExitStatus, String>,
}
/// Run a sandbox launcher on private stdin/stdout until the controlling connection closes.
pub async fn run(codex_linux_sandbox_exe: Option<PathBuf>) -> anyhow::Result<()> {
let (out_tx, mut out_rx) = mpsc::channel::<Value>(32);
let stdin = controller_stdin()?;
let disconnect = AsyncFd::with_interest(
std::io::stdin().as_fd().try_clone_to_owned()?,
Interest::READABLE,
)?;
let mut stdout = controller_stdout()?;
let writer = tokio::spawn(async move {
while let Some(value) = out_rx.recv().await {
let mut bytes = serde_json::to_vec(&value)?;
bytes.push(b'\n');
stdout.write_all(&bytes).await?;
stdout.flush().await?;
}
Ok::<_, anyhow::Error>(())
});
let (done_tx, mut done_rx) = mpsc::unbounded_channel::<Finished>();
let mut processes = HashMap::<String, Process>::new();
let mut input = BufReader::new(stdin).lines();
send(
&out_tx,
json!({"method":"ready","params":{"protocolVersion":4,"outputWindow":OUTPUT_WINDOW,"stdinWindow":1}}),
)
.await;
let result = loop {
let dispatch = async {
tokio::select! {
line = input.next_line() => {
let Some(line) = line? else {
return Ok(ControlFlow::Break(()));
};
anyhow::ensure!(line.len() <= MAX_MESSAGE_BYTES, "sandbox launcher message too large");
let request: Request = serde_json::from_str(&line).context("invalid sandbox launcher request")?;
match request {
Request::Start(start) => {
let id = start.id.clone();
if id.is_empty() || id.len() > 256 || processes.contains_key(&id) {
send(&out_tx, json!({"method":"error","params":{"id":id,"message":"invalid or duplicate process id"}})).await;
return Ok(ControlFlow::Continue(()));
}
match start_process(start, &out_tx, &done_tx, codex_linux_sandbox_exe.clone()).await {
Ok(process) => { processes.insert(id, process); }
Err(error) => send(&out_tx, json!({"method":"error","params":{"id":id,"message":error.to_string()}})).await,
}
}
Request::Write { id, data } => {
if let Some(process) = processes.get(&id) {
let data = BASE64.decode(data).context("invalid stdin data")?;
if process.stdin.try_send(Some(data)).is_err() {
send(&out_tx, json!({"method":"error","params":{"id":id,"message":"helper stdin window exceeded or closed"}})).await;
}
}
}
Request::CloseStdin { id } => {
if let Some(process) = processes.get(&id) && process.stdin.try_send(None).is_err() {
send(&out_tx, json!({"method":"error","params":{"id":id,"message":"helper stdin window exceeded or closed"}})).await;
}
}
Request::Terminate { id } => {
if let Some(process) = processes.get(&id) { process.output.close(); let _ = process.stop.try_send(()); }
}
Request::OutputConsumed { id } => {
if let Some(process) = processes.get(&id) && process.output.available_permits() < OUTPUT_WINDOW { process.output.add_permits(1); }
}
}
}
Some(finished) = done_rx.recv() => {
processes.remove(&finished.id);
match finished.status {
Ok(status) => send(&out_tx, json!({"method":"exited","params":{"id":finished.id,"status":status}})).await,
Err(message) => send(&out_tx, json!({"method":"error","params":{"id":finished.id,"message":message}})).await,
}
}
}
Ok::<_, anyhow::Error>(ControlFlow::Continue(()))
};
tokio::select! {
result = controller_eof(&disconnect) => break result.map_err(Into::into),
result = dispatch => match result {
Ok(ControlFlow::Continue(())) => {},
Ok(ControlFlow::Break(())) => break Ok(()),
Err(error) => break Err(error),
},
}
};
// Losing the private controller must not leave helpers or their proxies resident.
writer.abort();
for process in processes.values() {
process.output.close();
let _ = process.stop.try_send(());
}
while !processes.is_empty() {
if let Some(finished) = done_rx.recv().await {
processes.remove(&finished.id);
} else {
break;
}
}
drop(out_tx);
let _ = writer.await;
result
}
/// Observe a controller hangup even when unread requests remain in stdin.
async fn controller_eof(fd: &AsyncFd<OwnedFd>) -> std::io::Result<()> {
loop {
let mut event = fd.readable().await?;
if event.ready().is_read_closed() {
return Ok(());
}
event.clear_ready();
}
}
/// Read controller stdin without leaving an uncancellable blocking read during shutdown.
fn controller_stdin() -> std::io::Result<Box<dyn AsyncRead + Unpin + Send>> {
let fd = std::io::stdin().as_fd().try_clone_to_owned()?;
let file = std::fs::File::from(fd);
let ty = file.metadata()?.file_type();
if ty.is_fifo() {
Ok(Box::new(tokio::net::unix::pipe::Receiver::from_owned_fd(
file.into(),
)?))
} else if ty.is_socket() {
let socket = std::os::unix::net::UnixStream::from(std::os::fd::OwnedFd::from(file));
socket.set_nonblocking(true)?;
Ok(Box::new(tokio::net::UnixStream::from_std(socket)?))
} else {
Err(std::io::Error::other(
"sandbox launcher stdin must be a pipe or Unix socket",
))
}
}
/// Use nonblocking controller stdout so disconnect can cancel a stalled write on pipes or sockets.
fn controller_stdout() -> std::io::Result<Box<dyn AsyncWrite + Unpin + Send>> {
let fd = std::io::stdout().as_fd().try_clone_to_owned()?;
let file = std::fs::File::from(fd);
let ty = file.metadata()?.file_type();
if ty.is_fifo() {
Ok(Box::new(tokio::net::unix::pipe::Sender::from_owned_fd(
file.into(),
)?))
} else if ty.is_socket() {
let socket = std::os::unix::net::UnixStream::from(std::os::fd::OwnedFd::from(file));
socket.set_nonblocking(true)?;
Ok(Box::new(tokio::net::UnixStream::from_std(socket)?))
} else {
Err(std::io::Error::other(
"sandbox launcher stdout must be a pipe or Unix socket",
))
}
}
/// Launch one helper with the same config, sandbox transform and proxy as `codex sandbox`.
async fn start_process(
start: Start,
output: &mpsc::Sender<Value>,
done: &mpsc::UnboundedSender<Finished>,
codex_linux_sandbox_exe: Option<PathBuf>,
) -> anyhow::Result<Process> {
anyhow::ensure!(start.cwd.is_absolute(), "helper cwd must be absolute");
let cwd = std::fs::canonicalize(&start.cwd).context("resolve helper cwd")?;
anyhow::ensure!(
!start.command.is_empty(),
"helper command must not be empty"
);
#[cfg(target_os = "linux")]
anyhow::ensure!(
start.allow_unix_sockets.is_empty(),
"Unix socket allowances are only supported on macOS"
);
let command = HostSandboxCommand {
#[cfg(target_os = "linux")]
transparent_tcp: false,
sandbox_state: SandboxStateArgs::default(),
permissions_profile: None,
config_profile: None,
cwd: Some(cwd),
include_managed_config: false,
#[cfg(target_os = "macos")]
allow_unix_sockets: start.allow_unix_sockets,
#[cfg(target_os = "macos")]
log_denials: false,
config_overrides: CliConfigOverrides {
raw_overrides: start.config_overrides,
},
command: start.command,
};
let mut launch = start_command_under_host_sandbox(
command,
codex_linux_sandbox_exe,
LoaderOverrides::default(),
/*piped*/ true,
)
.await?;
let pid = launch
.child_mut()
.id()
.context("helper has no process id")?;
let mut child_stdin = launch
.child_mut()
.stdin
.take()
.context("helper stdin missing")?;
let (stdin, mut input) = mpsc::channel::<Option<Vec<u8>>>(1);
let input_output = output.clone();
let input_id = start.id.clone();
let stdin_task = tokio::spawn(async move {
while let Some(Some(data)) = input.recv().await {
if child_stdin.write_all(&data).await.is_err() {
send(
&input_output,
json!({"method":"stdinClosed","params":{"id":input_id}}),
)
.await;
break;
}
send(
&input_output,
json!({"method":"stdinConsumed","params":{"id":input_id}}),
)
.await;
}
});
let stdout = launch
.child_mut()
.stdout
.take()
.context("helper stdout missing")?;
let stderr = launch
.child_mut()
.stderr
.take()
.context("helper stderr missing")?;
let id = start.id;
send(
output,
json!({"method":"started","params":{"id":id,"pid":pid}}),
)
.await;
let (exit_tx, exit_rx) = watch::channel(false);
let credits = Arc::new(Semaphore::new(OUTPUT_WINDOW));
let stdout_task = tokio::spawn(copy_output(
stdout,
id.clone(),
"stdout",
output.clone(),
Arc::clone(&credits),
exit_rx.clone(),
));
let stderr_task = tokio::spawn(copy_output(
stderr,
id.clone(),
"stderr",
output.clone(),
Arc::clone(&credits),
exit_rx,
));
let (stop_tx, mut stop_rx) = mpsc::channel(1);
let done = done.clone();
tokio::spawn(async move {
let status = tokio::select! {
status = launch.child_mut().wait() => status,
_ = stop_rx.recv() => {
let _ = launch.child_mut().start_kill();
launch.child_mut().wait().await
}
};
stdin_task.abort();
let _ = stdin_task.await;
// The ordinary CLI drops its proxy when this process exits, even if a descendant kept a
// pipe open. Retain that lifetime instead of tying the proxy to output-stream closure.
drop(launch);
exit_tx.send_replace(true);
let (stdout, stderr) = tokio::join!(stdout_task, stderr_task);
let error = [stdout, stderr]
.into_iter()
.find_map(|result| match result {
Ok(Ok(())) => None,
Ok(Err(error)) => Some(error.to_string()),
Err(error) => Some(error.to_string()),
});
let status = match (error, status) {
(Some(error), _) => Err(error),
(None, Err(error)) => Err(error.to_string()),
(None, Ok(status)) => match status.code() {
Some(code) => Ok(ProcessExitStatus::Exit { code: code as u32 }),
None => status
.signal()
.map(|signal| ProcessExitStatus::Signal {
signal,
core_dumped: status.core_dumped(),
})
.ok_or_else(|| "unknown helper exit status".to_string()),
},
};
let _ = done.send(Finished { id, status });
});
Ok(Process {
stdin,
stop: stop_tx,
output: credits,
})
}
/// Forward one child stream without letting it access the supervisor's private control stream.
async fn copy_output(
mut stream: impl AsyncRead + AsRawFd + Unpin,
id: String,
name: &'static str,
output: mpsc::Sender<Value>,
credits: Arc<Semaphore>,
mut exited: watch::Receiver<bool>,
) -> anyhow::Result<()> {
let mut buffer = vec![0; 16 * 1024];
let mut remaining = None;
loop {
// Snapshot the bytes already buffered when we observe direct-child exit. A descendant
// may keep writing, but it cannot make this finite drain budget grow.
if remaining.is_none() && *exited.borrow() {
remaining = Some(buffered_bytes(stream.as_raw_fd())?);
}
let capacity = remaining.unwrap_or(buffer.len()).min(buffer.len());
if capacity == 0 {
break;
}
let read = if remaining.is_some() {
stream.read(&mut buffer[..capacity]).await
} else {
tokio::select! {
result = stream.read(&mut buffer[..capacity]) => result,
_ = exited.changed() => continue,
}
};
let count = read?;
if count == 0 {
break;
}
if let Some(remaining) = remaining.as_mut() {
*remaining -= count;
}
let Ok(permit) = credits.acquire().await else {
break;
};
if output.send(json!({"method":"output","params":{"id":id,"stream":name,"data":BASE64.encode(&buffer[..count])}})).await.is_err() { break; }
permit.forget();
}
Ok(())
}
/// Return the bytes currently buffered on a helper pipe without waiting for descendants.
fn buffered_bytes(fd: std::os::fd::RawFd) -> std::io::Result<usize> {
let mut bytes: libc::c_int = 0;
// SAFETY: `fd` belongs to the live stream and FIONREAD writes one integer to `bytes`.
if unsafe { libc::ioctl(fd, libc::FIONREAD, &mut bytes) } < 0 {
return Err(std::io::Error::last_os_error());
}
usize::try_from(bytes).map_err(std::io::Error::other)
}
/// Queue a protocol event; a closed controller will stop the supervisor on stdin EOF.
async fn send(output: &mpsc::Sender<Value>, event: Value) {
let _ = output.send(event).await;
}
@@ -0,0 +1,432 @@
//! A shared supervisor must preserve helper isolation and clean up when its controller exits.
#![cfg(any(target_os = "linux", target_os = "macos"))]
use anyhow::Context;
use anyhow::Result;
use base64::Engine;
use base64::engine::general_purpose::STANDARD as BASE64;
use pretty_assertions::assert_eq;
use serde_json::Value;
use serde_json::json;
use std::process::Stdio;
use tempfile::TempDir;
use tokio::io::AsyncBufReadExt;
use tokio::io::AsyncRead;
use tokio::io::AsyncWriteExt;
use tokio::io::BufReader;
use tokio::io::Lines;
use tokio::process::Child;
use tokio::process::ChildStdin;
use tokio::process::ChildStdout;
use tokio::process::Command;
use tokio::time::Duration;
use tokio::time::timeout;
type Output = Lines<BufReader<ChildStdout>>;
/// Skip only the macOS environment that cannot apply a nested Seatbelt profile.
#[cfg(target_os = "macos")]
fn sandbox_available() -> Result<bool> {
let probe = std::process::Command::new("/usr/bin/sandbox-exec")
.args(["-p", "(version 1)(allow default)", "/usr/bin/true"])
.output()?;
if !probe.status.success()
&& String::from_utf8_lossy(&probe.stderr)
.contains("sandbox-exec: sandbox_apply: Operation not permitted")
{
eprintln!("skipping helper test: nested Seatbelt is unavailable");
return Ok(false);
}
anyhow::ensure!(probe.status.success(), "Seatbelt probe failed: {probe:?}");
Ok(true)
}
/// Skip Linux hosts that cannot create the sandbox's required user namespace.
#[cfg(target_os = "linux")]
fn sandbox_available() -> Result<bool> {
let home = TempDir::new()?;
std::fs::write(
home.path().join("config.toml"),
"default_permissions = \"p\"\n[permissions.p.filesystem]\n\"/\" = \"read\"\n[permissions.p.network]\nenabled = false\n",
)?;
let probe = std::process::Command::new(codex_utils_cargo_bin::cargo_bin("codex")?)
.args(["sandbox", "--", "/usr/bin/true"])
.env("CODEX_HOME", home.path())
.output()?;
if !probe.status.success()
&& String::from_utf8_lossy(&probe.stderr).contains("Operation not permitted")
{
eprintln!(
"skipping helper test: Linux sandbox is unavailable: {}",
String::from_utf8_lossy(&probe.stderr)
);
return Ok(false);
}
anyhow::ensure!(
probe.status.success(),
"Linux sandbox probe failed: {probe:?}"
);
Ok(true)
}
/// Spawn a launcher with a minimal read-only, network-disabled sandbox profile.
fn spawn_launcher(home: &TempDir, stdin: Stdio, stdout: Stdio) -> Result<Child> {
std::fs::write(
home.path().join("config.toml"),
"default_permissions = \"p\"\n[permissions.p.filesystem]\n\"/\" = \"read\"\n[permissions.p.network]\nenabled = false\n",
)?;
Ok(Command::new(codex_utils_cargo_bin::cargo_bin("codex")?)
.arg("--codex-run-as-sandbox-launcher")
.env("CODEX_HOME", home.path())
.stdin(stdin)
.stdout(stdout)
.stderr(Stdio::inherit())
.kill_on_drop(true)
.spawn()?)
}
/// Start a launcher with standard pipe-backed controller streams.
async fn start_launcher(home: &TempDir) -> Result<(Child, ChildStdin, Output)> {
let mut child = spawn_launcher(home, Stdio::piped(), Stdio::piped())?;
let input = child.stdin.take().context("launcher stdin")?;
let mut output = BufReader::new(child.stdout.take().context("launcher stdout")?).lines();
assert_eq!(next_event(&mut output).await?["method"], "ready");
Ok((child, input, output))
}
/// Read one event, failing on a launcher error or a stalled connection.
async fn next_event<R: AsyncRead + Unpin>(output: &mut Lines<BufReader<R>>) -> Result<Value> {
let line = timeout(Duration::from_secs(45), output.next_line())
.await??
.context("launcher disconnected")?;
let event: Value = serde_json::from_str(&line)?;
assert_ne!(event["method"], "error", "{event}");
Ok(event)
}
#[tokio::test]
async fn launcher_accepts_socket_backed_controller_stdio() -> Result<()> {
let home = TempDir::new()?;
let (controller_input, launcher_input) = std::os::unix::net::UnixStream::pair()?;
let (controller_output, launcher_output) = std::os::unix::net::UnixStream::pair()?;
controller_input.set_nonblocking(true)?;
controller_output.set_nonblocking(true)?;
let mut child = spawn_launcher(
&home,
Stdio::from(std::os::fd::OwnedFd::from(launcher_input)),
Stdio::from(std::os::fd::OwnedFd::from(launcher_output)),
)?;
let mut input = tokio::net::UnixStream::from_std(controller_input)?;
let mut output = BufReader::new(tokio::net::UnixStream::from_std(controller_output)?).lines();
assert_eq!(next_event(&mut output).await?["method"], "ready");
let start =
json!({"method":"start","params":{"id":"","cwd":home.path(),"command":["/usr/bin/true"]}});
input.write_all(format!("{start}\n").as_bytes()).await?;
let line = timeout(Duration::from_secs(10), output.next_line())
.await??
.context("launcher error event")?;
let event: Value = serde_json::from_str(&line)?;
assert_eq!(event["method"], "error");
assert_eq!(
event["params"]["message"],
"invalid or duplicate process id"
);
stop_launcher(&mut child, input).await
}
/// Close the controller and require the launcher to exit promptly.
async fn stop_launcher<T>(child: &mut Child, input: T) -> Result<()> {
drop(input);
assert!(
timeout(Duration::from_secs(10), child.wait())
.await??
.success()
);
Ok(())
}
#[tokio::test]
async fn helper_cwd_symlinks_do_not_skip_project_config() -> Result<()> {
let home = TempDir::new()?;
let project = std::fs::canonicalize(home.path())?.join("project");
std::fs::create_dir_all(project.join("nested"))?;
std::fs::create_dir(project.join(".codex"))?;
anyhow::ensure!(
std::process::Command::new("git")
.args(["init", "--quiet"])
.current_dir(&project)
.status()?
.success(),
"git init failed"
);
std::fs::write(project.join(".codex/config.toml"), "invalid = [toml")?;
let alias = home.path().join("alias");
std::os::unix::fs::symlink(project.join("nested"), &alias)?;
let (mut child, mut input, mut output) = start_launcher(&home).await?;
let config = home.path().join("config.toml");
let mut content = std::fs::read_to_string(&config)?;
content.push_str(&format!(
"\n[projects.{}]\ntrust_level = \"trusted\"\n",
serde_json::to_string(&project)?
));
std::fs::write(config, content)?;
let start =
json!({"method":"start","params":{"id":"config","cwd":alias,"command":["/usr/bin/true"]}});
input.write_all(format!("{start}\n").as_bytes()).await?;
let line = timeout(Duration::from_secs(45), output.next_line())
.await??
.context("launcher error")?;
let event: Value = serde_json::from_str(&line)?;
assert_eq!(event["method"], "error");
assert!(
event["params"]["message"]
.as_str()
.is_some_and(|message| message.contains("config.toml")),
"{event}"
);
stop_launcher(&mut child, input).await
}
#[tokio::test]
async fn helpers_cannot_write_to_each_others_roots() -> Result<()> {
if !sandbox_available()? {
return Ok(());
}
let home = TempDir::new()?;
let (mut child, mut input, mut output) = start_launcher(&home).await?;
let a = home.path().join("a");
let b = home.path().join("b");
std::fs::create_dir(&a)?;
std::fs::create_dir(&b)?;
for (id, own, other) in [("a", &a, &b), ("b", &b, &a)] {
let override_arg = format!(
"permissions.p={{filesystem={{\"/\"=\"read\",\"{}\"=\"write\"}},network={{enabled=false}}}}",
own.display()
);
let script = format!(
"touch '{}' && ! touch '{}'",
own.join("allowed").display(),
other.join(format!("forbidden-{id}")).display()
);
let message = json!({"method":"start","params":{"id":id,"cwd":own,"command":["/bin/sh","-c",script],"configOverrides":[override_arg]}});
input.write_all(format!("{message}\n").as_bytes()).await?;
}
input.flush().await?;
let mut exited = 0;
while exited < 2 {
let event = next_event(&mut output).await?;
if event["method"] == "exited" {
assert_eq!(
event["params"]["status"],
json!({"type":"exit","code":0}),
"{event}"
);
exited += 1;
}
}
assert!(a.join("allowed").exists() && b.join("allowed").exists());
assert!(!a.join("forbidden-b").exists() && !b.join("forbidden-a").exists());
stop_launcher(&mut child, input).await
}
#[tokio::test]
async fn stdin_backpressure_preserves_input() -> Result<()> {
if !sandbox_available()? {
return Ok(());
}
let home = TempDir::new()?;
let (mut child, mut input, mut output) = start_launcher(&home).await?;
let start = json!({"method":"start","params":{"id":"input","cwd":home.path(),"command":["/bin/sh","-c","sleep 0.2; wc -c"]}});
input.write_all(format!("{start}\n").as_bytes()).await?;
assert_eq!(next_event(&mut output).await?["method"], "started");
let data = BASE64.encode(vec![b'x'; 16 * 1024]);
for _ in 0..100 {
let write = json!({"method":"write","params":{"id":"input","data":data}});
input.write_all(format!("{write}\n").as_bytes()).await?;
assert_eq!(next_event(&mut output).await?["method"], "stdinConsumed");
}
input
.write_all(b"{\"method\":\"closeStdin\",\"params\":{\"id\":\"input\"}}\n")
.await?;
let event = next_event(&mut output).await?;
assert_eq!(event["method"], "output");
let bytes = BASE64.decode(event["params"]["data"].as_str().context("output data")?)?;
assert_eq!(String::from_utf8(bytes)?.trim(), "1638400");
assert_eq!(next_event(&mut output).await?["method"], "exited");
// Bubblewrap keeps the stdin pipe open even after the sandboxed command closes it.
#[cfg(target_os = "macos")]
{
let start = json!({"method":"start","params":{"id":"closed","cwd":home.path(),"command":["/bin/sh","-c","exec 0<&-; echo ready; exec sleep 60"]}});
input.write_all(format!("{start}\n").as_bytes()).await?;
assert_eq!(next_event(&mut output).await?["method"], "started");
assert_eq!(next_event(&mut output).await?["method"], "output");
let write = json!({"method":"write","params":{"id":"closed","data":BASE64.encode(b"x")}});
input.write_all(format!("{write}\n").as_bytes()).await?;
assert_eq!(next_event(&mut output).await?["method"], "stdinClosed");
let terminate = json!({"method":"terminate","params":{"id":"closed"}});
input.write_all(format!("{terminate}\n").as_bytes()).await?;
let event = next_event(&mut output).await?;
assert_eq!(
event["params"]["status"],
json!({"type":"signal","signal":9,"coreDumped":false})
);
}
stop_launcher(&mut child, input).await
}
#[tokio::test]
async fn exited_ids_can_be_reused_immediately() -> Result<()> {
if !sandbox_available()? {
return Ok(());
}
let home = TempDir::new()?;
let (mut child, mut input, mut output) = start_launcher(&home).await?;
let start = json!({"method":"start","params":{"id":"reusable","cwd":home.path(),"command":["/bin/sh","-c","exit 23"]}});
for _ in 0..2 {
input.write_all(format!("{start}\n").as_bytes()).await?;
input.flush().await?;
loop {
let event = next_event(&mut output).await?;
if event["method"] == "exited" {
assert_eq!(event["params"]["status"], json!({"type":"exit","code":23}));
break;
}
}
}
stop_launcher(&mut child, input).await
}
#[tokio::test]
async fn exited_helper_preserves_output_without_waiting_for_its_descendant() -> Result<()> {
if !sandbox_available()? {
return Ok(());
}
let home = TempDir::new()?;
let (mut child, mut input, mut output) = start_launcher(&home).await?;
let marker = home.path().join("sent");
let override_arg = format!(
"permissions.p={{filesystem={{\"/\"=\"read\",\"{}\"=\"write\"}},network={{enabled=false}}}}",
home.path().display()
);
let script = format!(
"/usr/bin/yes & IFS= read -r release; printf complete-response >&2; touch '{}'",
marker.display()
);
let start = json!({"method":"start","params":{"id":"output","cwd":home.path(),"command":["/bin/sh","-c",script],"configOverrides":[override_arg]}});
input.write_all(format!("{start}\n").as_bytes()).await?;
while next_event(&mut output).await?["method"] != "output" {}
// Hold controller output while the descendant fills the launcher queue.
tokio::time::sleep(Duration::from_millis(300)).await;
let release =
json!({"method":"write","params":{"id":"output","data":BASE64.encode(b"release\n")}});
input.write_all(format!("{release}\n").as_bytes()).await?;
timeout(Duration::from_secs(10), async {
while !marker.exists() {
tokio::time::sleep(Duration::from_millis(10)).await;
}
})
.await?;
// The old supervisor truncated output after its fixed 100 ms drain deadline.
tokio::time::sleep(Duration::from_millis(250)).await;
let stderr = timeout(Duration::from_secs(10), async {
let mut stderr = Vec::new();
loop {
let event = next_event(&mut output).await?;
if event["method"] == "output" {
let consumed =
json!({"method":"outputConsumed","params":{"id":event["params"]["id"]}});
input.write_all(format!("{consumed}\n").as_bytes()).await?;
}
if event["method"] == "output" && event["params"]["stream"] == "stderr" {
stderr.extend(
BASE64.decode(event["params"]["data"].as_str().context("stderr chunk")?)?,
);
}
if event["method"] == "exited" {
assert_eq!(event["params"]["status"], json!({"type":"exit","code":0}));
break Ok::<_, anyhow::Error>(stderr);
}
}
})
.await??;
assert_eq!(stderr, b"complete-response");
stop_launcher(&mut child, input).await
}
#[tokio::test]
async fn invalid_request_exits_while_controller_stdin_is_open() -> Result<()> {
let home = TempDir::new()?;
let (mut child, mut input, _output) = start_launcher(&home).await?;
input.write_all(b"{invalid}\n").await?;
input.flush().await?;
assert!(
!timeout(Duration::from_secs(10), child.wait())
.await??
.success()
);
drop(input);
Ok(())
}
#[tokio::test]
async fn controller_eof_stops_a_launcher_with_blocked_output() -> Result<()> {
if !sandbox_available()? {
return Ok(());
}
let home = TempDir::new()?;
let (mut child, mut input, mut output) = start_launcher(&home).await?;
let start = json!({"method":"start","params":{"id":"verbose","cwd":home.path(),"command":["/usr/bin/yes"]}});
input.write_all(format!("{start}\n").as_bytes()).await?;
input.flush().await?;
while next_event(&mut output).await?["method"] != "output" {}
// Leave stdout open but undrained long enough for the shared output queue to fill.
tokio::time::sleep(Duration::from_millis(300)).await;
let writable = home.path().join("second");
std::fs::create_dir(&writable)?;
let marker = writable.join("started");
let override_arg = format!(
"permissions.p={{filesystem={{\"/\"=\"read\",\"{}\"=\"write\"}},network={{enabled=false}}}}",
writable.display()
);
let script = format!("touch '{}'", marker.display());
let second = json!({"method":"start","params":{"id":"second","cwd":writable,"command":["/bin/sh","-c",script],"configOverrides":[override_arg]}});
input.write_all(format!("{second}\n").as_bytes()).await?;
input.flush().await?;
timeout(Duration::from_secs(10), async {
while !marker.exists() {
tokio::time::sleep(Duration::from_millis(10)).await;
}
})
.await?;
let burst = format!(
"{}\n",
json!({"method":"closeStdin","params":{"id":"missing"}})
)
.repeat(160);
input.write_all(burst.as_bytes()).await?;
// Reusing the live helper's ID gives us a response once the queued requests resume.
input.write_all(format!("{start}\n").as_bytes()).await?;
timeout(Duration::from_secs(10), async {
loop {
let line = output.next_line().await?.context("launcher event")?;
let event: Value = serde_json::from_str(&line)?;
if event["method"] == "output" {
let consumed =
json!({"method":"outputConsumed","params":{"id":event["params"]["id"]}});
input.write_all(format!("{consumed}\n").as_bytes()).await?;
}
if event["method"] == "error" && event["params"]["id"] == "verbose" {
break Ok::<_, anyhow::Error>(());
}
}
})
.await??;
// Saturate the queue again, then disconnect while both dispatch and input are blocked.
tokio::time::sleep(Duration::from_millis(300)).await;
input.write_all(format!("{start}\n").as_bytes()).await?;
input.write_all(burst.as_bytes()).await?;
stop_launcher(&mut child, input).await?;
drop(output);
Ok(())
}