Volumes - Microsandbox

See Volumes for usage examples and patterns.

Volume

Named volumes are managed by microsandbox and stored by default under ~/.microsandbox/volumes/<name>/. They persist independently of any sandbox.

Volume::builder()

rust

fn builder(name: impl Into<String>) -> VolumeBuilder

Create a builder for a new named volume. Directory-backed volumes are the default. Call .disk().size(...) to create a disk-backed volume.

Parameters

Name	Type	Description
name	`impl Into<String>`	Volume name (e.g. `"pip-cache"`)

Returns

Type	Description
`VolumeBuilder`	Builder with `.directory()`, `.disk()`, `.size()`, `.quota()`, and `.create()`

Volume::get()

rust

async fn get(name: &str) -> MicrosandboxResult<VolumeHandle>

Get a handle to an existing named volume. Use the handle to access the volume's filesystem from the host or to delete it.

Parameters

Name	Type	Description
name	`&str`	Volume name

Returns

Type	Description
`VolumeHandle`	Handle for host-side operations

Volume::list()

rust

async fn list() -> MicrosandboxResult<Vec<VolumeHandle>>

List all named volumes.

Returns

Type	Description
`Vec<VolumeHandle>`	All volume handles

Volume::remove()

rust

async fn remove(name: &str) -> MicrosandboxResult<()>

Delete a named volume and its contents from disk. Fails if the volume is currently mounted by a running sandbox.

Parameters

Name	Type	Description
name	`&str`	Volume name

VolumeBuilder

Builder for creating a named volume.

create()

rust

async fn create(self) -> MicrosandboxResult<Volume>

Create the volume on disk.

Returns

Type	Description
`Volume`	The created volume

quota()

rust

fn quota(self, mib: u64) -> Self

Set the recorded quota metadata for a directory-backed volume.

Parameters

Name	Type	Description
mib	`u64`	Quota in MiB

directory()

rust

fn directory(self) -> Self

Create a directory-backed named volume. This is the default.

disk()

rust

fn disk(self) -> Self

Create a raw ext4 disk-backed named volume.

size()

rust

fn size(self, size: impl Into<Mebibytes>) -> Self

Set disk volume capacity. Required after .disk().

MountBuilder

Builder for configuring a volume mount. Used in SandboxBuilder::volume(path, |v| v...).

bind()

rust

fn bind(self, host_path: impl Into<PathBuf>) -> Self

Mount a host directory into the sandbox. Changes in the guest are reflected on the host and vice versa.

Parameters

Name	Type	Description
host_path	`impl Into<PathBuf>`	Directory path on the host

named()

rust

fn named(self, name: impl Into<String>) -> Self

Mount a named volume. The volume must already exist (create it with Volume::builder()).

Parameters

Name	Type	Description
name	`impl Into<String>`	Volume name

named_with()

rust

fn named_with(
    self,
    name: impl Into<String>,
    f: impl FnOnce(NamedVolumeBuilder) -> NamedVolumeBuilder,
) -> Self

Mount a named volume with explicit sandbox-time existence behavior. NamedVolumeMode::Existing is the default and behaves like named(). .create() creates the volume and fails if it already exists. .ensure_exists() creates the volume if it is missing or reuses an existing compatible volume.

rust

let sb = Sandbox::builder("worker")
    .image("python")
    .volume("/cache", |v| v.named_with("pip-cache", |n| n.ensure_exists()))
    .volume("/var/lib/docker", |v| {
        v.named_with("docker-data", |n| n.ensure_exists().disk().size(20.gib()))
    })
    .create()
    .await?;

The ensure-exists mode validates existing volume metadata. It errors when the existing volume has a different kind, quota, capacity, or explicitly requested labels than the requested configuration; it does not mutate existing volume metadata.

Named volume builder methods

Method	Description
`existing()`	Require the volume to already exist. This is the default.
`create()`	Create the volume and fail if it already exists.
`ensure_exists()`	Create the volume if missing or reuse a compatible existing volume.
`directory()`	Use directory-backed storage. This is the default.
`disk()`	Use disk-backed raw ext4 storage. Requires `size(...)` when creating or ensuring a missing volume.
`size(size)`	Disk capacity.
`quota(size)`	Directory volume quota.
`label(key, value)`	Attach a label to newly-created volumes and require matching labels for ensure-existing volumes when labels are requested.

readonly()

rust

fn readonly(self) -> Self

Mount as read-only. The guest can read but not write, and virtiofs-backed mounts also reject writes in the host filesystem server.

noexec()

rust

fn noexec(self) -> Self

Prevent direct execution from this mount. Interpreters can still read scripts from the mount, such as sh /mnt/script.sh.

disk()

rust

fn disk(self, host_path: impl Into<PathBuf>) -> Self

Mount a host disk image as a virtio-blk device. The disk image format defaults from the extension (.qcow2, .raw, .vmdk; otherwise raw).

format()

rust

fn format(self, format: DiskImageFormat) -> Self

Set the disk image format explicitly. Valid only with disk().

fstype()

rust

fn fstype(self, fstype: impl Into<String>) -> Self

Set the inner filesystem type for a disk-image volume, for example "ext4". If omitted, agentd probes supported filesystems and uses the first type that mounts cleanly. Empty values and mount-spec separators are rejected.

size()

rust

fn size(self, mib: impl Into<Mebibytes>) -> Self

Set the size limit for a tmpfs mount. Valid only for tmpfs mounts.

Parameters

Name	Type	Description
mib	`impl Into<Mebibytes>`	Size limit in MiB

tmpfs()

rust

fn tmpfs(self) -> Self

Use an in-memory filesystem. Contents are discarded when the sandbox stops. Good for scratch space, temp files, and build artifacts.

Types

VolumeHandle

Handle for interacting with a named volume from the host side.

Property / Method	Type	Description
fs()	`VolumeFsHandle`	Host-side filesystem access - read and write files without a running sandbox
name()	`&str`	Volume name
kind()	`VolumeKind`	Volume kind: `Directory` or `Disk`
capacity_bytes()	`Option<u64>`	Disk capacity in bytes
disk_format()	`Option<&str>`	Disk image format
disk_fstype()	`Option<&str>`	Disk filesystem type
remove()	`()`	Delete this volume from disk