Volumes - microsandbox

Create and manage named volumes: persistent storage that lives independently of any sandbox. Read and write a volume’s files directly from the host, or mount it into a sandbox. See Volumes for usage examples and patterns.

Typical flow

use microsandbox::{Sandbox, Volume};

// 1. create a persistent named volume
let vol = Volume::builder("pip-cache").create().await?;

// 2. seed it from the host, no sandbox required
vol.fs().write("/note.txt", "shared cache").await?;

// 3. mount it into a sandbox
let sb = Sandbox::builder("api")
    .image("python")
    .volume("/root/.cache/pip", |v| v.named("pip-cache"))
    .create()
    .await?;

sb.exec("pip", ["install", "requests"]).await?;
sb.stop().await?;

Static methods

Volume::builder()

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

Example

let vol = Volume::builder("pip-cache").create().await?;

Create a builder for configuring a new named volume. Directory-backed volumes are the default; call .disk() then .size() for a raw ext4 disk-image volume. Volume names must start with an alphanumeric character and contain only alphanumeric characters, dots, hyphens, and underscores. See VolumeBuilder for all options.

Parameters

nameimpl Into<String>

Volume name, e.g. “pip-cache”.

Returns

VolumeBuilder

Builder for configuring the volume.

Volume::create()

async fn create(config: VolumeConfig) -> MicrosandboxResult<Volume>

Example

use microsandbox::volume::{VolumeConfig, VolumeKind};

let vol = Volume::create(VolumeConfig {
    name: "cache".into(),
    kind: VolumeKind::Directory,
    quota_mib: Some(1024),
    capacity_mib: None,
    labels: vec![("team".into(), "ml".into())],
})
.await?;

Provision a volume from a VolumeConfig. Routes through the active backend. Locally this inserts a database record and creates the host directory (formatting a disk.raw for disk volumes). Fails with VolumeAlreadyExists if a volume of the same name already exists. Most callers use Volume::builder(), which calls this internally.

Parameters

configVolumeConfig

Volume configuration. VolumeConfig is an alias for VolumeSpec.

Returns

Volume

The created volume.

Volume::get()

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

Example

let h = Volume::get("pip-cache").await?;
println!("{} - {} bytes used", h.name(), h.used_bytes());

Get a handle to an existing named volume. Use the handle to access the volume’s filesystem from the host, read its metadata, or delete it. Fails with VolumeNotFound if no volume by that name exists.

Parameters

name&str

Volume name.

Returns

VolumeHandle

Handle for host-side operations.

Volume::list()

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

Example

for h in Volume::list().await? {
    println!("{} - {:?}", h.name(), h.kind());
}

List all named volumes, newest first.

Returns

Vec<VolumeHandle>

All volume handles.

Volume::remove()

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

Example

Volume::remove("pip-cache").await?;

Delete a named volume and its contents from disk. Locally the database record is deleted first, then the directory, so an orphaned directory is easier to detect than an orphaned record. Fails with VolumeNotFound if the volume does not exist.

Parameters

name&str

Volume name.

Volume instance methods

A live Volume, returned by Volume::create() or VolumeBuilder::create(). Carries the backend it was created on.

vol.name()

fn name(&self) -> &str

The unique name identifying this volume.

Returns

&str

Volume name.

vol.kind()

fn kind(&self) -> VolumeKind

The storage kind: Directory or Disk.

Returns

VolumeKind

Storage kind.

vol.fs()

fn fs(&self) -> VolumeFs<'_>

Example

vol.fs().write("/seed.txt", "hello").await?;

Get a filesystem handle for reading and writing the volume’s files directly, without a running sandbox. Local volumes route to tokio::fs. See VolumeFs for the operations.

Returns

VolumeFs

Filesystem handle.

vol.path()

fn path(&self) -> MicrosandboxResult<&Path>

Example

println!("{}", vol.path()?.display());

The host-side directory where this volume’s data is stored (local backend only). Errors with Unsupported for cloud volumes, whose bytes live in the org’s object storage rather than on the caller’s host.

Returns

&Path

Host data directory, e.g. ~/.microsandbox/volumes/pip-cache/.

vol.disk_path()

fn disk_path(&self) -> Option<PathBuf>

Host path to the managed raw disk image (disk.raw) for disk volumes. Returns None for directory volumes.

Returns

Option<PathBuf>

Path to disk.raw, or None for directory volumes.

vol.capacity_bytes()

fn capacity_bytes(&self) -> Option<u64>

Disk capacity in bytes for disk volumes. None for directory volumes.

Returns

Option<u64>

Capacity in bytes, or None.

vol.disk_format()

fn disk_format(&self) -> Option<&str>

Disk image format for disk volumes (always "raw" for managed disk volumes). None for directory volumes.

Returns

Option<&str>

Format string, or None.

vol.disk_fstype()

fn disk_fstype(&self) -> Option<&str>

Inner disk filesystem type for disk volumes (always "ext4" for managed disk volumes). None for directory volumes.

Returns

Option<&str>

Filesystem type, or None.

vol.backend_kind()

fn backend_kind(&self) -> BackendKind

Which backend variant this volume is bound to: Local or Cloud.

Returns

BackendKind

Local or Cloud.

vol.local()

fn local(&self) -> Option<&VolumeLocalState>

Local-only volume state. Returns Some for local-backed volumes, None for cloud-backed ones.

Returns

Option<&VolumeLocalState>

Local state, or None.

vol.cloud()

fn cloud(&self) -> Option<&VolumeCloudState>

Cloud-only volume state. Returns Some for cloud-backed volumes, None for local-backed ones.

Returns

Option<&VolumeCloudState>

Cloud state, or None.

VolumeHandle methods

A lightweight handle returned by Volume::get() and Volume::list(). Exposes metadata captured at read time plus filesystem and delete operations, without holding a live Volume.

h.name()

fn name(&self) -> &str

The unique name identifying this volume.

Returns

&str

Volume name.

h.kind()

fn kind(&self) -> VolumeKind

The storage kind: Directory or Disk.

Returns

VolumeKind

Storage kind.

h.fs()

fn fs(&self) -> VolumeFs<'_>

Example

let h = Volume::get("pip-cache").await?;
let names = h.fs().list("/").await?;

Get a filesystem handle for reading and writing the volume’s files directly, without a running sandbox. See VolumeFs.

Returns

VolumeFs

Filesystem handle.

h.remove()

async fn remove(&self) -> MicrosandboxResult<()>

Example

Volume::get("pip-cache").await?.remove().await?;

Delete this volume and its contents. Locally the database record is removed first, then the directory.

h.used_bytes()

fn used_bytes(&self) -> u64

Disk usage snapshot from when this handle was created. Not live, call Volume::get() again for a fresh reading.

Returns

u64

Bytes used at handle-creation time.

h.quota_mib()

fn quota_mib(&self) -> Option<u32>

Maximum storage in MiB, or None if unlimited.

Returns

Option<u32>

Quota in MiB, or None.

h.capacity_bytes()

fn capacity_bytes(&self) -> Option<u64>

Disk capacity in bytes for disk volumes. None for directory volumes.

Returns

Option<u64>

Capacity in bytes, or None.

h.disk_format()

fn disk_format(&self) -> Option<&str>

Disk image format for disk volumes. None for directory volumes.

Returns

Option<&str>

Format string, or None.

h.disk_fstype()

fn disk_fstype(&self) -> Option<&str>

Inner disk filesystem type for disk volumes. None for directory volumes.

Returns

Option<&str>

Filesystem type, or None.

h.disk_path()

fn disk_path(&self) -> Option<PathBuf>

Host path to the managed raw disk image (disk.raw) for local disk volumes. None otherwise.

Returns

Option<PathBuf>

Path to disk.raw, or None.

h.labels()

fn labels(&self) -> &[(String, String)]

Key-value labels for organizing and filtering volumes.

Returns

&[(String, String)]

Label pairs.

h.created_at()

fn created_at(&self) -> Option<DateTime<Utc>>

When this volume was first created, if recorded.

Returns

Option<DateTime<Utc>>

Creation timestamp, or None.

h.backend_kind()

fn backend_kind(&self) -> BackendKind

Which backend variant this handle is bound to: Local or Cloud.

Returns

BackendKind

Local or Cloud.

h.local()

fn local(&self) -> Option<&VolumeHandleLocalState>

Local-only handle state. Returns Some for local-backed handles, None for cloud-backed ones.

Returns

Option<&VolumeHandleLocalState>

Local state, or None.

h.cloud()

fn cloud(&self) -> Option<&VolumeHandleCloudState>

Cloud-only handle state. Returns Some for cloud-backed handles, None for local-backed ones.

Returns

Option<&VolumeHandleCloudState>

Cloud state, or None.

VolumeFs methods

Host-side filesystem operations on a named volume, obtained via Volume::fs() or VolumeHandle::fs(). Unlike SandboxFsOps, which goes through the agent protocol, VolumeFs reads and writes the volume’s bytes directly. Paths are relative to the volume root; a leading / is stripped, and path traversal outside the root is rejected.

fs.read()

async fn read(&self, path: &str) -> MicrosandboxResult<Bytes>

Example

let data = vol.fs().read("/seed.txt").await?;

Read an entire file into memory as raw bytes.

Parameters

path&str

File path relative to the volume root.

Returns

Bytes

File contents.

fs.read_to_string()

async fn read_to_string(&self, path: &str) -> MicrosandboxResult<String>

Example

let text = vol.fs().read_to_string("/seed.txt").await?;

Read an entire file into memory as a UTF-8 string.

Parameters

path&str

File path relative to the volume root.

Returns

String

File contents as UTF-8.

fs.read_stream()

async fn read_stream(&self, path: &str) -> MicrosandboxResult<VolumeFsReadStream>

Example

let mut stream = vol.fs().read_stream("/model.bin").await?;
while let Some(chunk) = stream.recv().await? {
    // process chunk
}

Open a file for streaming reads. Returns a VolumeFsReadStream that yields 64 KiB chunks, so large files don’t have to be held in memory at once.

Parameters

path&str

File path relative to the volume root.

Returns

VolumeFsReadStream

Chunked reader.

fs.write()

async fn write(&self, path: &str, data: impl AsRef<[u8]>) -> MicrosandboxResult<()>

Example

vol.fs().write("/config/app.json", r#"{"ready":true}"#).await?;

Write data to a file, creating parent directories as needed. Overwrites if the file already exists.

Parameters

path&str

File path relative to the volume root.

dataimpl AsRef<[u8]>

Bytes to write.

fs.write_stream()

async fn write_stream(&self, path: &str) -> MicrosandboxResult<VolumeFsWriteSink>

Example

let mut sink = vol.fs().write_stream("/upload.bin").await?;
sink.write(&chunk).await?;
sink.close().await?;

Open a file for streaming writes. Returns a VolumeFsWriteSink that accepts chunks of bytes. Creates parent directories as needed.

Parameters

path&str

File path relative to the volume root.

Returns

VolumeFsWriteSink

Chunked writer.

fs.list()

async fn list(&self, path: &str) -> MicrosandboxResult<Vec<FsEntry>>

Example

for entry in vol.fs().list("/").await? {
    println!("{} ({} bytes)", entry.path, entry.size);
}

List the immediate children of a directory (non-recursive). Each entry includes the path, kind, size, permissions, and modification time.

Parameters

path&str

Directory path relative to the volume root.

Returns

Vec<FsEntry>

Directory entries.

fs.mkdir()

async fn mkdir(&self, path: &str) -> MicrosandboxResult<()>

Example

vol.fs().mkdir("/data/incoming").await?;

Create a directory and any missing parents.

Parameters

path&str

Directory path relative to the volume root.

fs.remove()

async fn remove(&self, path: &str) -> MicrosandboxResult<()>

Example

vol.fs().remove("/data/stale.tmp").await?;

Delete a single file. Use remove_dir() for directories.

Parameters

path&str

File path relative to the volume root.

fs.remove_dir()

async fn remove_dir(&self, path: &str) -> MicrosandboxResult<()>

Example

vol.fs().remove_dir("/data/incoming").await?;

Remove a directory and its contents recursively. Targeting the volume root is rejected.

Parameters

path&str

Directory path relative to the volume root.

fs.copy()

async fn copy(&self, from: &str, to: &str) -> MicrosandboxResult<()>

Example

vol.fs().copy("/seed.txt", "/backup/seed.txt").await?;

Copy a file within the volume. Creates the destination’s parent directories as needed.

Parameters

from&str

Source path relative to the volume root.

to&str

Destination path relative to the volume root.

fs.rename()

async fn rename(&self, from: &str, to: &str) -> MicrosandboxResult<()>

Example

vol.fs().rename("/tmp/out.txt", "/done/out.txt").await?;

Rename or move a file or directory. Creates the destination’s parent directories as needed.

Parameters

from&str

Source path relative to the volume root.

to&str

Destination path relative to the volume root.

fs.stat()

async fn stat(&self, path: &str) -> MicrosandboxResult<FsMetadata>

Example

let meta = vol.fs().stat("/seed.txt").await?;
println!("{} bytes", meta.size);

Get metadata for a file or directory: kind, size, permission bits, read-only flag, and timestamps.

Parameters

path&str

Path relative to the volume root.

Returns

FsMetadata

Entry metadata.

fs.exists()

async fn exists(&self, path: &str) -> MicrosandboxResult<bool>

Example

if !vol.fs().exists("/seed.txt").await? {
    vol.fs().write("/seed.txt", "hello").await?;
}

Check whether a file or directory exists at the given path. Returns false rather than an error if the path is absent.

Parameters

path&str

Path relative to the volume root.

Returns

bool

true if the path exists.

VolumeBuilder

Builder for configuring a named volume before creation. Obtained via Volume::builder(name). Directory-backed is the default; disk volumes require .disk() plus .size(). Every setter returns Self, so calls chain.

.directory()

fn directory(self) -> Self

Create a directory-backed named volume (mounted through virtiofs). This is the default.

.disk()

fn disk(self) -> Self

Create a raw ext4 disk-image named volume (mounted through virtio-blk). Requires .size().

.size()

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

Example

use microsandbox::size::SizeExt;

let vol = Volume::builder("docker-data")
    .disk()
    .size(20.gib())
    .create()
    .await?;

Set the disk volume’s capacity. Required for disk volumes; rejected for directory volumes. Accepts a bare u32 (MiB) or a SizeExt helper such as 20.gib().

Parameters

sizeimpl Into<Mebibytes>

Capacity in MiB.

.quota()

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

Limit a directory volume’s storage. Accepts a bare u32 (MiB) or a SizeExt helper such as 1.gib(). Omit for unlimited growth (the default). Rejected for disk volumes, which size up front via .size().

Parameters

sizeimpl Into<Mebibytes>

Quota in MiB.

.label()

fn label(self, key: impl Into<String>, value: impl Into<String>) -> Self

Attach a key-value label for organizing and filtering volumes. Can be called multiple times.

Parameters

keyimpl Into<String>

Label key.

valueimpl Into<String>

Label value.

.build()

fn build(self) -> VolumeConfig

Materialize the VolumeConfig without creating the volume. Pass the result to Volume::create() to provision it later.

Returns

VolumeConfig

The volume configuration.

.create()

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

Example

let vol = Volume::builder("pip-cache")
    .quota(1024)
    .label("team", "ml")
    .create()
    .await?;

Create the volume on the active backend. Equivalent to Volume::create(self.build()).

Returns

Volume

The created volume.

MountBuilder

Builder for configuring a volume mount on a sandbox. Used in SandboxBuilder::volume(guest_path, |v| v...) (see .volume()). Pick exactly one mount kind: .bind(), .named() / .named_with(), .tmpfs(), or .disk(). Kind-specific options are validated when the surrounding SandboxBuilder is finalized, so an option set on the wrong kind surfaces a clear error rather than being silently dropped.

.bind()

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

Bind mount a host directory into the guest. Changes in the guest are reflected on the host and vice versa. The host path must be valid UTF-8 and must not contain ,, :, or ;.

Parameters

hostimpl Into<PathBuf>

Directory path on the host.

.named()

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

Mount a named volume created via Volume::create(). The volume must already exist. Persists across sandbox restarts and can be shared between sandboxes. For sandbox-time provisioning, use .named_with().

Parameters

nameimpl Into<String>

Volume name.

.named_with()

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

Example

use microsandbox::size::SizeExt;

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?;

Mount a named volume with explicit sandbox-time existence behavior, configured via a NamedVolumeBuilder closure. existing (the default) behaves like .named(); create provisions the volume and fails if it already exists; ensure_exists provisions it if missing or reuses a compatible existing volume. The ensure-exists mode validates existing metadata and errors when the kind, quota, capacity, or explicitly requested labels differ; it does not mutate existing metadata.

Parameters

nameimpl Into<String>

Volume name.

fFnOnce(NamedVolumeBuilder)

Configure existence behavior and creation metadata.

.tmpfs()

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. Cap its size with .size().

.disk()

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

Mount a host disk-image file as a virtio-blk device at the guest path. The format defaults from the file extension (.qcow2, .vmdk; anything else is Raw). Override with .format().

Parameters

hostimpl Into<PathBuf>

Disk image path on the host.

.format()

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

Override the disk-image format for a .disk() mount. Valid only with .disk(); calling it on a bind, named, or tmpfs mount errors when the SandboxBuilder is finalized.

Parameters

formatDiskImageFormat

Disk image format.

.fstype()

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

Set the inner filesystem type for a .disk() mount, for example "ext4". If omitted, agentd probes /proc/filesystems and uses the first type that mounts cleanly. Empty values and the separators ,, ;, :, = are rejected. Valid only with .disk().

Parameters

fstypeimpl Into<String>

Inner filesystem type.

.readonly()

fn readonly(self) -> Self

Prevent writes to this mount. Enforced both at the host (virtiofs server rejects writes) and in the guest (the kernel returns EROFS).

.noexec()

fn noexec(self) -> Self

Prevent direct execution of files on this mount. Interpreters can still read scripts from the mount, such as sh /mnt/script.sh, because the interpreter binary executes from a different filesystem.

.nosuid()

fn nosuid(self) -> Self

Ignore setuid and setgid privilege elevation from files on this mount.

.nodev()

fn nodev(self) -> Self

Ignore device files on this mount.

.stat_virtualization()

fn stat_virtualization(self, policy: StatVirtualization) -> Self

Set the guest stat virtualization policy for a virtiofs-backed mount. Default: Strict. Valid only for bind and directory-backed named-volume mounts. Tmpfs and disk-image mounts are rejected when the mount is built; disk-backed named volumes are rejected once the backing volume kind is known during sandbox create or start.

Parameters

policyStatVirtualization

Stat virtualization policy.

.host_permissions()

fn host_permissions(self, policy: HostPermissions) -> Self

Set the host permission propagation policy for a virtiofs-backed mount. Default: Private. Valid only for bind and directory-backed named-volume mounts. Combining StatVirtualization::Off with HostPermissions::Mirror is rejected, since with no overlay the guest chmod already hits the host inode and Mirror would be a no-op.

Parameters

policyHostPermissions

Host permission propagation policy.

.size()

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

Set the size limit for a .tmpfs() mount. Accepts a bare u32 (MiB) or a SizeExt helper such as 1.gib(). Valid only for tmpfs mounts.

Parameters

sizeimpl Into<Mebibytes>

Size limit in MiB.

.build()

fn build(self) -> MicrosandboxResult<VolumeMount>

Validate and materialize the mount. Usually called internally by SandboxBuilder::volume; call it directly only when assembling a VolumeMount by hand. Errors when no mount kind is set, the guest path is not absolute or is /, or a kind-specific option was set on the wrong mount kind.

Returns

VolumeMount

Validated mount specification.

NamedVolumeBuilder

Sub-builder for MountBuilder::named_with(). Selects the sandbox-time existence behavior and, for create / ensure_exists, the creation metadata. Defaults to existing and directory-backed.

.existing()

fn existing(self) -> Self

Require the named volume to already exist. This is the default.

.create()

fn create(self) -> Self

Create the named volume at sandbox launch and fail if it already exists.

.ensure_exists()

fn ensure_exists(self) -> Self

Create the named volume if it is missing, or reuse a compatible existing volume. Errors if an existing volume’s kind, quota, capacity, or explicitly requested labels differ.

.name()

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

Override the volume name passed to named_with().

Parameters

nameimpl Into<String>

Volume name.

.directory()

fn directory(self) -> Self

Use directory-backed storage for a created volume. This is the default. Clears any previously set disk capacity.

.disk()

fn disk(self) -> Self

Use raw ext4 disk-image storage for a created volume. Requires .size(). Clears any previously set quota.

.size()

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

Set disk capacity for a created disk volume. Accepts a bare u32 (MiB) or a SizeExt helper.

Parameters

sizeimpl Into<Mebibytes>

Capacity in MiB.

.quota()

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

Set a storage quota for a created directory volume. Accepts a bare u32 (MiB) or a SizeExt helper.

Parameters

sizeimpl Into<Mebibytes>

Quota in MiB.

.label()

fn label(self, key: impl Into<String>, value: impl Into<String>) -> Self

Attach a label to a newly-created volume. For ensure_exists, requested labels must match the existing volume. Can be called multiple times.

Parameters

keyimpl Into<String>

Label key.

valueimpl Into<String>

Label value.

Types

Volume

A live named volume, carrying the backend it was created on. Returned by Volume::create() and VolumeBuilder::create().

Returned by Volume::create() · VolumeBuilder::create()

Method	Returns	Description
`name()`	`&str`	Volume name
`kind()`	`VolumeKind`	Directory or disk
`fs()`	`VolumeFs`	Host-side filesystem handle
`path()`	`MicrosandboxResult<&Path>`	Host data directory (local only)
`disk_path()`	`Option<PathBuf>`	Host `disk.raw` path for disk volumes
`capacity_bytes()`	`Option<u64>`	Disk capacity in bytes
`disk_format()`	`Option<&str>`	Disk image format
`disk_fstype()`	`Option<&str>`	Inner disk filesystem
`backend_kind()`	`BackendKind`	Local or cloud
`local()`	`Option<&VolumeLocalState>`	Local-only state
`cloud()`	`Option<&VolumeCloudState>`	Cloud-only state

VolumeHandle

A lightweight handle to a volume, exposing metadata plus filesystem and delete operations without a live Volume.

Returned by Volume::get() · Volume::list()

Method	Returns	Description
`name()`	`&str`	Volume name
`kind()`	`VolumeKind`	Directory or disk
`fs()`	`VolumeFs`	Host-side filesystem handle
`remove()`	`MicrosandboxResult<()>`	Delete this volume
`used_bytes()`	`u64`	Usage snapshot at read time
`quota_mib()`	`Option<u32>`	Storage quota in MiB
`capacity_bytes()`	`Option<u64>`	Disk capacity in bytes
`disk_format()`	`Option<&str>`	Disk image format
`disk_fstype()`	`Option<&str>`	Inner disk filesystem
`disk_path()`	`Option<PathBuf>`	Host `disk.raw` path
`labels()`	`&[(String, String)]`	Key-value labels
`created_at()`	`Option<DateTime<Utc>>`	Creation time
`backend_kind()`	`BackendKind`	Local or cloud
`local()`	`Option<&VolumeHandleLocalState>`	Local-only state
`cloud()`	`Option<&VolumeHandleCloudState>`	Cloud-only state

VolumeBuilder

Builder for configuring a named volume before creation. Implements From<VolumeConfig>.

Returned by Volume::builder()

Method	Returns	Description
`directory()`	`Self`	Directory-backed (default)
`disk()`	`Self`	Raw ext4 disk-image volume
`size()`	`Self`	Disk capacity (required for disk)
`quota()`	`Self`	Directory storage quota
`label()`	`Self`	Attach a label
`build()`	`VolumeConfig`	Materialize config
`create()`	`Volume`	Create the volume

VolumeFs

Host-side filesystem operations on a volume. Borrows the parent’s backend and name and dispatches each op through the backend. A lifetime-bound handle (VolumeFs<'_>).

Returned by Volume::fs() · VolumeHandle::fs()

Method	Returns	Description
`read()`	`Bytes`	Read bytes
`read_to_string()`	`String`	Read UTF-8 text
`read_stream()`	`VolumeFsReadStream`	Stream a file in
`write()`	`()`	Write bytes
`write_stream()`	`VolumeFsWriteSink`	Stream a file out
`list()`	`Vec<FsEntry>`	List a directory
`mkdir()`	`()`	Create a directory
`remove()`	`()`	Delete a file
`remove_dir()`	`()`	Delete a directory recursively
`copy()`	`()`	Copy a file
`rename()`	`()`	Rename / move
`stat()`	`FsMetadata`	Metadata
`exists()`	`bool`	Existence check

VolumeFs::with_backend(backend, name) is also available as a public constructor for FFI shims that re-assemble a handle per call; most callers use Volume::fs() / VolumeHandle::fs().

VolumeFsReadStream

A streaming reader for file data from a local volume directory. Returned by VolumeFs::read_stream().

Returned by VolumeFs::read_stream()

Method	Returns	Description
`recv()`	`Option<Bytes>`	Next chunk; `None` at EOF
`collect()`	`Bytes`	Read the rest into one buffer

VolumeFsWriteSink

A streaming writer for file data to a local volume directory. Returned by VolumeFs::write_stream().

Returned by VolumeFs::write_stream()

Method	Returns	Description
`write(data)`	`()`	Append a chunk
`close()`	`()`	Flush and close

MountBuilder

Builder for a sandbox volume mount, used in SandboxBuilder::volume. Builds a VolumeMount.

Used by SandboxBuilder::volume()

Method	Returns	Description
`bind()`	`Self`	Bind a host directory
`named()`	`Self`	Mount an existing named volume
`named_with()`	`Self`	Mount with sandbox-time provisioning
`tmpfs()`	`Self`	In-memory filesystem
`disk()`	`Self`	Host disk image as virtio-blk
`format()`	`Self`	Disk image format (disk only)
`fstype()`	`Self`	Inner filesystem type (disk only)
`readonly()`	`Self`	Block writes
`noexec()`	`Self`	Block direct execution
`nosuid()`	`Self`	Ignore setuid/setgid
`nodev()`	`Self`	Ignore device files
`stat_virtualization()`	`Self`	Stat virtualization policy (virtiofs)
`host_permissions()`	`Self`	Host permission policy (virtiofs)
`size()`	`Self`	tmpfs size limit
`build()`	`MicrosandboxResult<VolumeMount>`	Validate and materialize

NamedVolumeBuilder

Sub-builder for MountBuilder::named_with(). Selects sandbox-time existence behavior and creation metadata.

Used by MountBuilder::named_with()

Method	Returns	Description
`existing()`	`Self`	Require the volume to exist (default)
`create()`	`Self`	Create, fail if it exists
`ensure_exists()`	`Self`	Create if missing, else reuse
`name()`	`Self`	Override the volume name
`directory()`	`Self`	Directory-backed (default)
`disk()`	`Self`	Disk-backed; requires `size`
`size()`	`Self`	Disk capacity
`quota()`	`Self`	Directory quota
`label()`	`Self`	Attach a label

VolumeKind

Storage kind for a named volume.

Returned by Volume::kind() · VolumeHandle::kind()

Variant	Description
`Directory`	Directory-backed volume mounted through virtiofs
`Disk`	Raw ext4 disk-image volume mounted through virtio-blk

VolumeSpec

Configuration for creating a named volume. Re-exported as both VolumeSpec and the alias VolumeConfig.

Used by Volume::create() · returned by VolumeBuilder::build()

Field	Type	Description
`name`	`String`	Volume name
`kind`	`VolumeKind`	Storage kind
`quota_mib`	`Option<u32>`	Size quota in MiB; `None` is unlimited
`capacity_mib`	`Option<u32>`	Disk capacity in MiB; required for disk volumes
`labels`	`Vec<(String, String)>`	Organization labels

MountOptions

Guest mount behavior shared by every mount kind. Set via the MountBuilder toggles; all fields default to false.

Field	Type	Description
`readonly`	`bool`	Guest writes fail; virtiofs mounts also reject host-side writes
`noexec`	`bool`	Direct execution from the mount is disabled
`nosuid`	`bool`	setuid/setgid elevation from files on the mount is ignored
`nodev`	`bool`	Device files on the mount are ignored

StatVirtualization

Stat virtualization policy for a virtiofs-backed mount. Default: Strict. Set via MountBuilder::stat_virtualization().

Variant	Description
`Strict`	Fail-closed: probe the host backing path; require xattr support
`Relaxed`	Opportunistic: apply the overlay when present; tolerate missing xattr support
`Off`	Literal host metadata: do not read or apply the override xattr

HostPermissions

Host permission propagation policy for a virtiofs-backed mount. Default: Private. Set via MountBuilder::host_permissions().

Variant	Description
`Private`	Guest chmod stays in the metadata overlay only
`Mirror`	Mirror ordinary rwx bits for files and directories to the host inode

DiskImageFormat

Disk image format for virtio-blk root filesystems and volume mounts. Used by MountBuilder::format().

Variant	Description
`Qcow2`	QEMU Copy-on-Write v2
`Raw`	Raw disk image
`Vmdk`	VMware Disk (FLAT/ZERO only, no delta links)

NamedVolumeMode

Sandbox-time behavior for a named volume mount, chosen via NamedVolumeBuilder.

Variant	Description
`Existing`	Require the named volume to already exist (default)
`Create`	Create the named volume and fail if it already exists
`EnsureExists`	Ensure the volume exists, or reuse a compatible existing one

​Static methods

​Volume::builder()

​Volume::create()

​Volume::get()

​Volume::list()

​Volume::remove()

​Volume instance methods

​vol.name()

​vol.kind()

​vol.fs()

​vol.path()

​vol.disk_path()

​vol.capacity_bytes()

​vol.disk_format()

​vol.disk_fstype()

​vol.backend_kind()

​vol.local()

​vol.cloud()

​VolumeHandle methods

​h.name()

​h.kind()

​h.fs()

​h.remove()

​h.used_bytes()

​h.quota_mib()

​h.capacity_bytes()

​h.disk_format()

​h.disk_fstype()

​h.disk_path()

​h.labels()

​h.created_at()

​h.backend_kind()

​h.local()

​h.cloud()

​VolumeFs methods

​fs.read()

​fs.read_to_string()

​fs.read_stream()

​fs.write()

​fs.write_stream()

​fs.list()

​fs.mkdir()

​fs.remove()

​fs.remove_dir()

​fs.copy()

​fs.rename()

​fs.stat()

​fs.exists()

​VolumeBuilder

​.directory()

​.disk()

​.size()

​.quota()

​.label()

​.build()

​.create()

​MountBuilder

​.bind()

​.named()

​.named_with()

​.tmpfs()

​.disk()

​.format()

​.fstype()

​.readonly()

​.noexec()

​.nosuid()

​.nodev()

​.stat_virtualization()

​.host_permissions()

​.size()

​.build()

​NamedVolumeBuilder

​.existing()

​.create()

​.ensure_exists()

​.name()

​.directory()

​.disk()

​.size()

Static methods

Volume::builder()

Volume::create()

Volume::get()

Volume::list()

Volume::remove()

Volume instance methods

vol.name()

vol.kind()

vol.fs()

vol.path()

vol.disk_path()

vol.capacity_bytes()

vol.disk_format()

vol.disk_fstype()

vol.backend_kind()

vol.local()

vol.cloud()

VolumeHandle methods

h.name()

h.kind()

h.fs()

h.remove()

h.used_bytes()

h.quota_mib()

h.capacity_bytes()

h.disk_format()

h.disk_fstype()

h.disk_path()

h.labels()

h.created_at()

h.backend_kind()

h.local()

h.cloud()

VolumeFs methods

fs.read()

fs.read_to_string()

fs.read_stream()

fs.write()

fs.write_stream()

fs.list()

fs.mkdir()

fs.remove()

fs.remove_dir()

fs.copy()

fs.rename()

fs.stat()

fs.exists()

VolumeBuilder

.directory()

.disk()

.size()

.quota()

.label()

.build()

.create()

MountBuilder

.bind()

.named()

.named_with()

.tmpfs()

.disk()

.format()

.fstype()

.readonly()

.noexec()

.nosuid()

.nodev()

.stat_virtualization()

.host_permissions()

.size()

.build()

NamedVolumeBuilder

.existing()

.create()

.ensure_exists()

.name()

.directory()

.disk()

.size()