feat: implement exec and forward commands for running commands in sandboxes
release / release (push) Successful in 2s
release / build (macos-arm64) (push) Successful in 21s
release / build (ubuntu-latest) (push) Successful in 1m5s

- Added `exec` command to run a shell or command in a running sandbox, utilizing a new exec server.
- Introduced `forward` command to expose ports of a running sandbox on the host's localhost.
- Updated Cargo.toml and Cargo.lock to reflect version bump and new dependencies.
- Enhanced README.md with usage instructions for new commands.
- Refactored build.rs to include new guest helper files for exec functionality.
- Created new source files for exec and forward logic, including protocol handling and connection management.
This commit is contained in:
2026-10-03 21:48:44 +02:00
parent 4ef8dd62e9
commit bc7512a373
10 changed files with 688 additions and 46 deletions
+121
View File
@@ -0,0 +1,121 @@
//! `wsbx exec`: shell or command in a running sandbox, via vfkit's exec.sock -> vsock -> guest helper.
//! Protocol (see guest/exec.go): one JSON request line, then frames both ways: kind u8, len u32 BE, payload.
use crate::sandbox::lock_stopped;
use crate::util::sanitize;
use crate::vm::{stty, term_size};
use anyhow::{Result, anyhow, bail};
use serde_json::json;
use std::io::{self, IsTerminal, Read, Write};
use std::os::unix::net::UnixStream;
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex};
use std::time::Duration;
/// Guest vsock port of the exec server.
pub const VPORT: u32 = 2222;
/// exec.sock of a running sandbox.
pub fn sock(h: &Path, name: &str) -> Result<PathBuf> {
let dir = h.join("sandboxes").join(name);
if name.is_empty() || sanitize(name) != name || !dir.join("meta.json").exists() {
bail!("no sandbox {name:?} (see wsbx ps)");
}
if lock_stopped(&dir).is_ok() {
bail!("sandbox {name} is not running");
}
Ok(dir.join("exec.sock"))
}
pub fn connect(sock: &Path, name: &str) -> Result<UnixStream> {
UnixStream::connect(sock).map_err(|e| anyhow!("can't reach {name}: {e} (started by an older wsbx?)"))
}
pub fn frame(kind: u8, p: &[u8]) -> Vec<u8> {
[&[kind][..], &(p.len() as u32).to_be_bytes(), p].concat()
}
pub fn exec(h: &Path, name: &str, user: Option<String>, argv: Vec<String>) -> Result<()> {
let s = connect(&sock(h, name)?, name)?;
// Like ssh: a pty only when we're interactive, so `wsbx exec x -- cat f > out` stays byte-exact.
let tty = io::stdin().is_terminal() && io::stdout().is_terminal();
let (rows, cols) = if tty { term_size().unwrap_or((24, 80)) } else { (0, 0) };
let w = Arc::new(Mutex::new(s.try_clone()?));
let req = json!({"argv": argv, "user": user, "tty": tty, "term": std::env::var("TERM").ok(), "rows": rows, "cols": cols});
w.lock().unwrap().write_all(format!("{req}\n").as_bytes())?;
let saved = if tty { stty(&["-g"]) } else { None };
if saved.is_some() {
stty(&["raw", "-echo"]);
}
let wi = w.clone();
std::thread::spawn(move || {
let (mut stdin, mut b) = (io::stdin().lock(), vec![0u8; 32 << 10]);
loop {
match stdin.read(&mut b) {
Ok(0) => break,
Ok(n) if send(&wi, b'd', &b[..n]).is_err() => return,
Ok(_) => {}
Err(e) if e.kind() == io::ErrorKind::Interrupted => {}
Err(_) => break,
}
}
let _ = send(&wi, b'e', &[]);
});
if tty {
// ponytail: polls instead of a SIGWINCH handler; resizes land within 250 ms.
std::thread::spawn(move || {
let mut last = (rows, cols);
loop {
std::thread::sleep(Duration::from_millis(250));
if let Some((r, c)) = term_size().filter(|&sz| sz != last) {
last = (r, c);
if send(&w, b'w', &[r.to_be_bytes(), c.to_be_bytes()].concat()).is_err() {
return;
}
}
}
});
}
let code = output(s);
if let Some(s) = saved {
stty(&[s.trim()]);
}
match code? {
Some(c) => std::process::exit(c),
None => bail!("lost connection to {name} (VM stopped?)"),
}
}
fn send(w: &Mutex<UnixStream>, kind: u8, p: &[u8]) -> io::Result<()> {
w.lock().unwrap().write_all(&frame(kind, p))
}
/// Copy guest output frames to stdout/stderr until the exit status arrives (None: connection closed first).
fn output(s: UnixStream) -> io::Result<Option<i32>> {
let mut r = io::BufReader::new(s);
let (mut out, mut err) = (io::stdout().lock(), io::stderr().lock());
loop {
let mut h = [0u8; 5];
if r.read_exact(&mut h).is_err() {
return Ok(None);
}
let mut p = (&mut r).take(u32::from_be_bytes([h[1], h[2], h[3], h[4]]).into());
match h[0] {
b'o' => {
io::copy(&mut p, &mut out)?;
out.flush()?;
}
b'r' => {
io::copy(&mut p, &mut err)?;
}
b'x' => {
let mut c = [0u8; 4];
p.read_exact(&mut c)?;
return Ok(Some(i32::from_be_bytes(c)));
}
_ => {
io::copy(&mut p, &mut io::sink())?;
}
}
}
}
+105
View File
@@ -0,0 +1,105 @@
//! `wsbx forward NAME [HOSTPORT:]PORT...`: host 127.0.0.1:HOSTPORT -> exec.sock -> vsock -> guest helper ->
//! guest localhost:PORT. Framed like exec (see guest/exec.go), so closes and a vanished host are noticed.
use crate::exec::{connect, frame, sock};
use anyhow::{Context, Result, bail};
use serde_json::json;
use std::io::{self, BufReader, Read, Write};
use std::net::{Shutdown, TcpListener, TcpStream};
use std::path::Path;
use std::thread;
pub fn forward(h: &Path, name: &str, specs: Vec<String>) -> Result<()> {
let sock = sock(h, name)?;
let mut ls = Vec::new();
for spec in specs {
let (host, guest) = spec.split_once(':').unwrap_or((&spec, &spec));
let (Ok(host), Ok(guest)) = (host.parse::<u16>(), guest.parse::<u16>()) else {
bail!("bad port {spec:?} (PORT or HOSTPORT:PORT)");
};
if guest == 0 {
bail!("bad port {spec:?}");
}
// Loopback only: nothing on the LAN reaches the sandbox. [::1] is best effort.
let l = TcpListener::bind(("127.0.0.1", host)).with_context(|| format!("localhost:{host}"))?;
let host = l.local_addr()?.port(); // 0 picks a free one
if let Ok(l6) = TcpListener::bind(("::1", host)) {
ls.push((l6, guest));
}
ls.push((l, guest));
eprintln!("wsbx: localhost:{host} -> {name}:{guest}");
}
// ponytail: thread per connection, fine for dev servers; async if someone forwards thousands of sockets.
let threads: Vec<_> = ls
.into_iter()
.map(|(l, port)| {
let (sock, name) = (sock.clone(), name.to_string());
thread::spawn(move || {
for c in l.incoming().flatten() {
let (sock, name) = (sock.clone(), name.clone());
thread::spawn(move || {
if let Err(e) = conn(&sock, &name, c, port) {
eprintln!("wsbx: {name}:{port}: {e}");
}
});
}
})
})
.collect();
for t in threads {
let _ = t.join();
}
Ok(())
}
fn conn(sock: &Path, name: &str, c: TcpStream, port: u16) -> Result<()> {
let s = connect(sock, name)?;
let mut w = s.try_clone()?;
w.write_all(format!("{}\n", json!({"connect": port})).as_bytes())?;
let mut cr = c.try_clone()?;
let up = thread::spawn(move || {
let mut b = vec![0u8; 32 << 10];
loop {
match cr.read(&mut b) {
Ok(0) | Err(_) => break,
Ok(n) if w.write_all(&frame(b'd', &b[..n])).is_err() => return,
Ok(_) => {}
}
}
let _ = w.write_all(&frame(b'e', &[]));
});
let res = down(BufReader::new(s), &c);
// Clean EOF from the service: only our write side ends, the client may still be sending.
// Anything else (dial failed, VM gone, client gone): drop both, which also ends `up`.
let _ = c.shutdown(if matches!(res, Ok(true)) { Shutdown::Write } else { Shutdown::Both });
let _ = up.join();
res.map(|_| ())
}
/// Guest frames -> client, until 'x'. Ok(true): the service closed cleanly.
fn down(mut r: BufReader<std::os::unix::net::UnixStream>, mut c: &TcpStream) -> Result<bool> {
loop {
let mut h = [0u8; 5];
if r.read_exact(&mut h).is_err() {
bail!("lost connection (VM stopped?)");
}
let mut p = (&mut r).take(u32::from_be_bytes([h[1], h[2], h[3], h[4]]).into());
match h[0] {
b'o' => {
io::copy(&mut p, &mut c)?;
}
b'r' => {
let mut m = String::new();
p.read_to_string(&mut m)?;
bail!("{m}");
}
b'x' => {
let mut x = [0u8; 4];
p.read_exact(&mut x)?;
return Ok(x == [0; 4]);
}
_ => {
io::copy(&mut p, &mut io::sink())?;
}
}
}
}
+27 -1
View File
@@ -1,6 +1,8 @@
//! wsbx — Docker-Sandboxes-style microVMs on macOS (Virtualization.framework via vfkit).
mod agents;
mod disk;
mod exec;
mod forward;
mod kernel;
mod oci;
mod sandbox;
@@ -18,7 +20,7 @@ use std::process::Command;
use vm::Guest;
#[derive(Parser)]
#[command(name = "wsbx", about = "Launch coding agents or bare Linux in microVMs")]
#[command(name = "wsbx", version, about = "Launch coding agents or bare Linux in microVMs")]
struct Cli {
#[command(subcommand)]
cmd: Cmd,
@@ -60,6 +62,25 @@ enum Cmd {
#[arg(long)]
pi_auth: bool,
},
/// Shell (default) or command in a running sandbox
#[command(visible_alias = "sh")]
Exec {
name: String,
/// Run as this user (default: the image's user, like the sandbox's main command)
#[arg(short, long)]
user: Option<String>,
#[arg(last = true)]
cmd: Vec<String>,
},
/// Expose ports of a running sandbox on the host's localhost (until Ctrl-C). Works for services
/// bound to the guest's localhost too. Note: browsers share localhost cookies across ports.
#[command(visible_alias = "fwd")]
Forward {
name: String,
/// PORT, or HOSTPORT:PORT (HOSTPORT 0: any free port)
#[arg(required = true)]
ports: Vec<String>,
},
/// List sandboxes and whether they're running
#[command(visible_alias = "ps")]
Ls,
@@ -73,6 +94,8 @@ enum Cmd {
},
/// Delete cached images that no sandbox uses
Gc,
/// Print the wsbx version
Version,
}
#[derive(Args)]
@@ -143,9 +166,12 @@ fn main() -> Result<()> {
Cmd::Codex(a) => agents::agent(&h, a, "codex", "codex", vec![], &["OPENAI_API_KEY"], Guest::default()),
Cmd::Gemini(a) => agents::agent(&h, a, "gemini", "gemini", vec![], &["GEMINI_API_KEY", "GOOGLE_API_KEY"], Guest::default()),
Cmd::Pi { a, pi_auth } => agents::pi(&h, a, pi_auth),
Cmd::Exec { name, user, cmd } => exec::exec(&h, &name, user, cmd),
Cmd::Forward { name, ports } => forward::forward(&h, &name, ports),
Cmd::Ls => sandbox::ls(&h),
Cmd::Gc => sandbox::gc(&h),
Cmd::Rm { names, disk } => sandbox::rm(&h, names, disk),
Cmd::Version => Ok(println!("wsbx {}", env!("CARGO_PKG_VERSION"))),
}
}
+37 -25
View File
@@ -1,5 +1,6 @@
//! Booting a sandbox: run script, vfkit invocation, guest results.
use crate::disk::create_disk;
use crate::exec;
use crate::kernel::kernel;
use crate::oci;
use crate::sandbox::lock_stopped;
@@ -17,7 +18,7 @@ use std::process::{Command, Stdio};
const INIT: &str = include_str!("init.sh");
const DHCP: &str = include_str!("dhcp.sh");
const FWD: &[u8] = include_bytes!(concat!(env!("OUT_DIR"), "/wsbx-fwd"));
const GUEST: &[u8] = include_bytes!(concat!(env!("OUT_DIR"), "/wsbx-guest"));
/// Agent-specific guest preparation.
#[derive(Default)]
@@ -97,7 +98,7 @@ pub fn run(h: &Path, o: Opts, image: &str, cmd: Vec<String>, extra: &[String], g
let mut s = String::from("B=/.wsbx/busybox\n");
s += &format!("$B date -s @{} >/dev/null\n", now());
s += &format!("$B hostname {name}; echo {name} > /etc/hostname; $B grep -q ' {name}$' /etc/hosts 2>/dev/null || echo '127.0.1.1 {name}' >> /etc/hosts\n");
if let Some((rows @ 1.., cols @ 1..)) = term_size() {
if let Some((rows, cols)) = term_size() {
s += &format!("$B stty rows {rows} cols {cols}\n");
}
if let Some(ws) = &ws {
@@ -132,30 +133,39 @@ pub fn run(h: &Path, o: Opts, image: &str, cmd: Vec<String>, extra: &[String], g
}
s += &g.setup;
// Host tunnel: guest wsbx-fwd listens on localhost:PORT -> vsock -> vfkit -> unix socket -> host localhost:PORT
s += &format!("cd {} 2>/dev/null || cd /\n", sq(&wd));
// Guest helper (guest/*.go), started after the cd so exec sessions inherit run.sh's env and working dir.
// `wsbx exec`: host -> vfkit listening on exec.sock -> vsock -> helper (runs the command, pty or pipes)
// Host tunnel: helper listens on guest localhost:PORT -> vsock -> vfkit -> unix socket -> host localhost:PORT
fs::write(share.join("guest"), GUEST)?;
fs::set_permissions(share.join("guest"), fs::Permissions::from_mode(0o755))?;
let (mut vsock, mut args) = (Vec::new(), Vec::new());
let exec_sock = dir.join("exec.sock");
let _ = fs::remove_file(&exec_sock); // left over if vfkit was killed; vfkit can't listen on it then
if exec_sock.as_os_str().len() <= 100 {
// `connect`: vfkit listens on the unix socket and dials the guest (vfkit defaults to `listen`)
vsock.push(format!("virtio-vsock,port={},socketURL={},connect", exec::VPORT, vf(&exec_sock)?));
args.push(format!("-exec {}", exec::VPORT));
} else {
eprintln!("wsbx: note: `wsbx exec` unavailable, socket path too long (set WSBX_HOME to something shorter)");
}
let mut ports = o.host_ports.clone();
ports.sort();
ports.dedup();
let mut vsock = Vec::new();
for (i, &p) in ports.iter().enumerate() {
let vport = 10000 + i as u32;
let sock = dir.join(format!("p{p}.sock"));
tunnel(&sock, p)?;
vsock.push(format!("virtio-vsock,port={vport},socketURL={},listen", vf(&sock)?));
args.push(format!("{p}={vport}"));
}
if !ports.is_empty() {
let fwd = share.join("fwd");
fs::write(&fwd, FWD)?;
fs::set_permissions(&fwd, fs::Permissions::from_mode(0o755))?;
let mut specs = Vec::new();
for (i, &p) in ports.iter().enumerate() {
let vport = 10000 + i as u32;
let sock = dir.join(format!("p{p}.sock"));
tunnel(&sock, p)?;
vsock.push(format!("virtio-vsock,port={vport},socketURL={},listen", vf(&sock)?));
specs.push(format!("{p}={vport}"));
}
s += "$B mkfifo /run/wsbx-fwd\n";
s += &format!("/.wsbx/host/fwd {} >/run/wsbx-fwd 2>/.wsbx/host/fwd.log &\n", specs.join(" "));
s += "read _ </run/wsbx-fwd\n";
eprintln!("wsbx: host localhost:{{{}}} tunneled into the VM", ports.iter().map(u16::to_string).collect::<Vec<_>>().join(","));
}
s += &format!("cd {} 2>/dev/null || cd /\n", sq(&wd));
s += "$B mkfifo /run/wsbx-guest\n";
s += &format!("/.wsbx/host/guest {} >/run/wsbx-guest 2>/.wsbx/host/guest.log &\n", args.join(" "));
s += "read _ </run/wsbx-guest\n";
let argv: Vec<String> = argv.iter().map(|a| sq(a)).collect();
if u.is_empty() || u == "root" || u == "0" {
s += &format!("exec {}\n", argv.join(" "));
@@ -253,15 +263,17 @@ fn out_path() -> PathBuf {
fs::read_link("/dev/fd/1").unwrap_or("/dev/stdout".into())
}
fn stty(args: &[&str]) -> Option<String> {
pub fn stty(args: &[&str]) -> Option<String> {
let out = Command::new("stty").args(args).stdin(Stdio::inherit()).stderr(Stdio::null()).output().ok()?;
out.status.success().then(|| String::from_utf8_lossy(&out.stdout).into_owned())
}
fn term_size() -> Option<(u32, u32)> {
let s = stty(&["size"])?;
let mut it = s.split_whitespace().map(|x| x.parse().ok());
Some((it.next()??, it.next()??))
/// Rows and columns of the terminal on stdin.
pub fn term_size() -> Option<(u16, u16)> {
// SAFETY: TIOCGWINSZ only writes a winsize struct.
let mut ws: libc::winsize = unsafe { std::mem::zeroed() };
let ok = unsafe { libc::ioctl(0, libc::TIOCGWINSZ, &mut ws) } == 0;
(ok && ws.ws_row > 0 && ws.ws_col > 0).then_some((ws.ws_row, ws.ws_col))
}
#[cfg(test)]