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, generated artifacts, logs, or checkpoint files across VM restarts. The host directory is the source of truth — ideal for long-running pipelines.

Shared configuration

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

Development workflow

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