pub struct AsyncSandbox { /* private fields */ }Expand description
Async wrapper around a Hanzo VM VM sandbox.
All VM operations are dispatched to a dedicated OS thread that owns the sandbox. This avoids Send/Sync constraints from the Apple Virtualization framework’s Objective-C objects.
Implementations§
Source§impl AsyncSandbox
impl AsyncSandbox
Sourcepub async fn boot(config: SandboxConfig) -> Result<Self>
pub async fn boot(config: SandboxConfig) -> Result<Self>
Boot a new sandbox VM with the given configuration.
Sourcepub async fn exec(&self, argv: &[&str]) -> Result<ExecResult>
pub async fn exec(&self, argv: &[&str]) -> Result<ExecResult>
Execute a command and wait for the result.
Sourcepub async fn exec_shell(&self, command: &str) -> Result<ExecResult>
pub async fn exec_shell(&self, command: &str) -> Result<ExecResult>
Execute a command string via the given shell (defaults to /bin/sh).
Sourcepub async fn exec_in(&self, shell: &str, command: &str) -> Result<ExecResult>
pub async fn exec_in(&self, shell: &str, command: &str) -> Result<ExecResult>
Execute a command string via a specific shell.
Use exec_in("bash", cmd) when you need login profile (PATH etc.),
or exec_in("/bin/sh", cmd) for basic POSIX shell.
Sourcepub async fn open_shell(
&self,
rows: u16,
cols: u16,
cwd: Option<&str>,
argv: Option<&[&str]>,
extra_env: HashMap<String, String>,
) -> Result<ShellHandle>
pub async fn open_shell( &self, rows: u16, cols: u16, cwd: Option<&str>, argv: Option<&[&str]>, extra_env: HashMap<String, String>, ) -> Result<ShellHandle>
Spawn an interactive PTY session.
If argv is None, opens a login shell (bash -l).
If argv is Some, runs that command directly (no shell wrapper).
If cwd is Some, the process starts in that directory.
Sourcepub async fn read_file(&self, path: &str) -> Result<Vec<u8>>
pub async fn read_file(&self, path: &str) -> Result<Vec<u8>>
Read a file from the VM. Returns raw bytes.
Sourcepub async fn write_file(&self, path: &str, content: &[u8]) -> Result<()>
pub async fn write_file(&self, path: &str, content: &[u8]) -> Result<()>
Write a file to the VM.
Sourcepub async fn discard_overlay(&self, path: &str) -> Result<()>
pub async fn discard_overlay(&self, path: &str) -> Result<()>
Discard overlay changes for a file. Removes it from the overlay upper dir, revealing the original host version from the lower layer.
Sourcepub async fn add_port_forward(
&self,
host_port: u16,
guest_port: u16,
) -> Result<()>
pub async fn add_port_forward( &self, host_port: u16, guest_port: u16, ) -> Result<()>
Add a port forward to a running sandbox.
Sourcepub async fn dial_guest(&self, port: u16) -> Result<GuestStream>
pub async fn dial_guest(&self, port: u16) -> Result<GuestStream>
Open a raw byte stream to a TCP port listening inside the guest.
This is the ingress counterpart to outbound proxying: it lets host-side
code reach a server running in the sandbox without binding a local
listener (unlike add_port_forward). The
returned GuestStream is a blocking bidirectional pipe to
127.0.0.1:<port> inside the guest, suitable for bridging the guest
service onto any transport (for example, a tunnel to the public
internet). It works whether or not --allow-net is enabled.
For async I/O, take the inner stream with GuestStream::into_inner,
set it non-blocking, and wrap it with tokio::net::TcpStream::from_std.
Sourcepub async fn remove(&self, path: &str, recursive: bool) -> Result<()>
pub async fn remove(&self, path: &str, recursive: bool) -> Result<()>
Remove a file or directory inside the VM.
Sourcepub async fn read_dir(&self, path: &str) -> Result<ReadDirResponse>
pub async fn read_dir(&self, path: &str) -> Result<ReadDirResponse>
List directory contents in the VM.
Sourcepub async fn mkdir(&self, path: &str, recursive: bool) -> Result<()>
pub async fn mkdir(&self, path: &str, recursive: bool) -> Result<()>
Create a directory inside the VM. If recursive is true, creates
parent directories as needed (like mkdir -p).
Sourcepub async fn rename(&self, old_path: &str, new_path: &str) -> Result<()>
pub async fn rename(&self, old_path: &str, new_path: &str) -> Result<()>
Rename a file or directory inside the VM.
Sourcepub async fn chmod(&self, path: &str, mode: u32) -> Result<()>
pub async fn chmod(&self, path: &str, mode: u32) -> Result<()>
Change file permissions inside the VM.
Sourcepub async fn download(
&self,
url: &str,
path: &str,
extract: bool,
strip_components: u32,
) -> Result<(Receiver<Result<()>>, Receiver<DownloadProgress>)>
pub async fn download( &self, url: &str, path: &str, extract: bool, strip_components: u32, ) -> Result<(Receiver<Result<()>>, Receiver<DownloadProgress>)>
Download a URL into the sandbox. If extract is true, the download
is treated as a .tar.gz and extracted to path as a directory.
strip_components mirrors tar --strip-components=N — set to 1
for tarballs wrapped in a single top-level directory (Node, Pi)
and 0 for flat tarballs (single binary at root).
Returns a channel that receives progress updates.
Sourcepub async fn checkpoint(&self, name: &str) -> Result<()>
pub async fn checkpoint(&self, name: &str) -> Result<()>
Save the current rootfs state as a named checkpoint (CoW clone).
Future VMs can boot from this checkpoint via SandboxConfig::from.
Sourcepub async fn open_watch(
&self,
path: &str,
recursive: bool,
) -> Result<WatchHandle>
pub async fn open_watch( &self, path: &str, recursive: bool, ) -> Result<WatchHandle>
Watch a path inside the VM for filesystem changes (inotify-backed).
Returns a handle whose receiver emits WatchEvents. Drop the handle
to stop watching.
Sourcepub fn instance_dir(&self) -> &str
pub fn instance_dir(&self) -> &str
Get the instance directory path (contains the working rootfs copy).