Mount Host Directories into Guest VMs

VoidBox can mount host directories into the guest VM using sandbox.mounts. Each mount specifies a host path, a guest mount point, and a mode ("ro" or "rw", default "ro").

Read-write mounts write directly to the host directory — data persists across VM restarts since the host directory survives. This is the primary mechanism for stateful workloads.

Transport

Linux/KVM

9p (virtio-9p) — kernel-based 9P filesystem protocol over virtio transport.

Current limitation: the KVM backend still exposes a single virtio-9p device rooted at the first configured host path. Treat multi-mount layouts on Linux as not yet parity-complete.

macOS/VZ

virtiofs — Apple Virtualization.framework native shared directory support. macOS/VZ supports multiple named shares.

Mount Configuration

Each mount entry has three fields:

Field	Description	Default
host	Path on the host filesystem	(required)
guest	Mount point inside the guest VM	(required)
mode	"ro" (read-only) or "rw" (read-write)	"ro"

YAML Example

sandbox:
  mounts:
    - host: ./data
      guest: /data
      mode: rw        # persistent — host directory survives VM restarts

If you need multiple guest mount points today, prefer macOS/VZ or verify Linux/KVM behavior carefully against the current implementation.

Use Cases

Stateful Workloads

Use mode: rw mounts to persist agent output, databases, or generated artifacts across VM restarts. The host directory is the source of truth.

Shared Configuration

Use mode: ro mounts to inject configuration files, credentials, or reference data into the guest without risk of modification.

Persistent Data

Mount a host directory as rw to collect logs, results, or checkpoint files that survive VM lifecycle. Ideal for long-running pipelines.

Development Workflow

Mount your project source tree as ro to let the agent read and analyze code without modifying the host copy.