Host Mounts

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.

macOS/VZ

virtiofs — Apple Virtualization.framework native shared directory support.

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

sandbox:
  mounts:
    - host: ./data
      guest: /data
      mode: rw        # persistent — host directory survives VM restarts
    - host: ./config
      guest: /config
      mode: ro        # read-only (default)

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.