Struct Sandbox 

pub struct Sandbox { /* private fields */ }

Implementations

impl Sandbox

pub fn builder() -> VmConfigBuilder

pub fn start(&self) -> Result<()>

pub fn stop(&self) -> Result<()>

pub fn wait_ready(&self) -> Result<()>

Block until the guest control server accepts vsock connections.

pub fn state_channel(&self) -> Receiver<VmState>

pub fn exec( &self, argv: &[impl AsRef<str>], stdout: &mut impl Write, stderr: &mut impl Write, ) -> Result<i32>

Run a command non-interactively over vsock, streaming output to the provided writers. Returns the guest process exit code.

pub fn exec_with_env( &self, argv: &[impl AsRef<str>], env: &HashMap<String, String>, stdout: &mut impl Write, stderr: &mut impl Write, ) -> Result<i32>

pub fn reach(&self) -> Result<()>

Block until the guest’s vsock server answers, and give up saying so if it never does.

start returns when the VMM is running, which is earlier than the guest is reachable — kernel and guest init still have to happen. A caller that announces readiness at start hands its own caller a race it cannot see: the first request pays the whole wait, and on a loaded host pays past the connect budget and fails. Waiting here moves that wait to where it can be named.

pub fn attest(&self, bind: &[u8; 64]) -> Result<Status>

Ask the guest’s platform for a report over bind.

The 64 bytes are what a verifier will check the report’s caller field against — Measurement::bind. A guest on ordinary hardware answers none, which is an answer: nothing here will sign for a measurement.

The read is bounded because a guest that predates this request drops the frame in silence, and a caller must not wait out a vm’s whole life on a question it was never able to hear.

pub fn read_file(&self, path: &str) -> Result<Vec<u8>>

pub fn write_file(&self, path: &str, content: &[u8]) -> Result<()>

pub fn mkdir(&self, path: &str, recursive: bool) -> Result<()>

pub fn download( &self, url: &str, path: &str, extract: bool, strip_components: u32, on_progress: impl Fn(DownloadProgress), ) -> Result<()>

Download a URL into the sandbox. Streams progress via the callback.

pub fn read_dir(&self, path: &str) -> Result<ReadDirResponse>

pub fn stat(&self, path: &str) -> Result<StatResponse>

pub fn remove(&self, path: &str, recursive: bool) -> Result<()>

pub fn discard_overlay(&self, path: &str) -> Result<()>

Discard overlay changes for a file: removes it from the upper dir, revealing the original host version from the lower layer.

pub fn rename(&self, old_path: &str, new_path: &str) -> Result<()>

pub fn copy(&self, src: &str, dst: &str, recursive: bool) -> Result<()>

pub fn chmod(&self, path: &str, mode: u32) -> Result<()>

pub fn open_exec( &self, argv: &[impl AsRef<str>], env: &HashMap<String, String>, cwd: Option<&str>, ) -> Result<TcpStream>

Open a vsock connection for streaming exec. Returns the raw stream after sending mounts + ExecRequest. Caller manages I/O (reads STDOUT/STDERR/EXIT frames, writes STDIN/KILL frames).

pub fn open_shell( &self, argv: &[impl AsRef<str>], env: &HashMap<String, String>, rows: u16, cols: u16, ) -> Result<TcpStream>

Open a vsock connection for an interactive shell with PTY support. Like open_exec but with tty=true. Returns the raw stream after sending mounts + ExecRequest. Caller manages I/O using the binary frame protocol (STDIN/STDOUT/RESIZE/EXIT frames).

pub fn open_shell_with_cwd( &self, argv: &[impl AsRef<str>], env: &HashMap<String, String>, rows: u16, cols: u16, cwd: Option<&str>, ) -> Result<TcpStream>

pub fn open_watch(&self, path: &str, recursive: bool) -> Result<TcpStream>

Open a vsock connection for file watching. Returns a stream that emits WATCH_EVENT frames until the connection is closed.

pub fn shell( &self, argv: &[impl AsRef<str>], env: &HashMap<String, String>, ) -> Result<i32>

Run an interactive shell session with PTY support. Puts the host terminal in raw mode, relays I/O bidirectionally over vsock, and handles SIGWINCH for window resize. Returns the guest process exit code.

pub fn start_port_forwarding( &self, forwards: &[PortMapping], ) -> Result<PortForwardHandle>

Start port forwarding proxies. Returns a handle that stops all listeners when dropped.

pub fn connect_forward(&self, guest_port: u16) -> Result<TcpStream>

Open a raw bidirectional stream to a TCP port listening inside the guest.

Unlike start_port_forwarding, this does not bind a host listener. It completes the vsock forward handshake and hands back the connected stream directly, so callers can bridge a guest service to an arbitrary transport (e.g. a tunnel) without a local port. The returned stream talks to 127.0.0.1:guest_port inside the guest and works whether or not networking (--allow-net) is enabled.