--- title: Volumes "og:title": Rust SDK Volumes reference description: Create and mount persistent sandbox volumes with the Rust SDK. keywords: ["Rust SDK", "Rust volumes", "microsandbox volumes"] --- See [Volumes](/sandboxes/volumes) for usage examples. ## Volume #### Volume::get_default() Cloud-only ```rust async fn get_default() -> MicrosandboxResult ``` Get the Cloud account's always-present default volume. It has no user-assigned name, cannot be removed, and supports direct filesystem operations through `.fs()`. The local backend returns a typed `Unsupported` error; it never substitutes a directory from the caller's machine. ```rust let volume = Volume::get_default().await?; volume.fs().write("customers/acme.json", br#"{"active":true}"#).await?; println!("{}", volume.fs().read_to_string("customers/acme.json").await?); ``` #### Volume::builder() ```rust fn builder(name: impl Into) -> VolumeBuilder ``` ```rust 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()`](#volume_builder-disk) then [`.size()`](#volume_builder-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`](#volumebuilder-2) for all options.

Parameters

nameimpl Into<String>
Volume name, e.g. "pip-cache".

Returns

VolumeBuilder
Builder for configuring the volume.
#### Volume::create() Limited on cloud ```rust async fn create(config: VolumeConfig) -> MicrosandboxResult ``` ```rust 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`](#volumespec). 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()`](#volumebuilder), which calls this internally.

Parameters

Volume configuration. VolumeConfig is an alias for VolumeSpec.

Returns

The created volume.
#### Volume::get() ```rust async fn get(name: &str) -> MicrosandboxResult ``` ```rust 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

Handle for host-side operations.
#### Volume::list() ```rust async fn list() -> MicrosandboxResult> ``` ```rust for h in Volume::list().await? { println!("{} - {:?}", h.name(), h.kind()); } ``` List all named volumes, newest first.

Returns

All volume handles.
#### Volume::remove() ```rust async fn remove(name: &str) -> MicrosandboxResult<()> ``` ```rust Volume::remove("pip-cache").await?; ``` Delete a named volume and its contents from disk. Locally, files are deleted before the database record so interrupted removal can be retried. Fails with `VolumeNotFound` if the volume does not exist.

Parameters

name&str
Volume name.

Instance methods

A live `Volume`, returned by [`Volume::create()`](#volumecreate) or [`VolumeBuilder::create()`](#vb-create). Carries the backend it was created on. #### vol.name() ```rust fn name(&self) -> &str ``` The unique name identifying this volume.

Returns

&str
Volume name.
#### vol.kind() ```rust fn kind(&self) -> VolumeKind ``` The storage kind. See [`VolumeKind`](#volumekind).

Returns

Storage kind.
#### vol.fs() ```rust fn fs(&self) -> VolumeFs<'_> ``` ```rust 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`; Cloud volumes route through the authenticated volume API. See [`VolumeFs`](#volumefs) for the operations.

Returns

Filesystem handle.
#### vol.path() Local-only ```rust fn path(&self) -> MicrosandboxResult<&Path> ``` ```rust println!("{}", vol.path()?.display()); ``` The host-side directory where this volume's data is stored.

Returns

&Path
Host data directory, e.g. ~/.microsandbox/volumes/pip-cache/.
#### vol.disk_path() ```rust fn disk_path(&self) -> Option ``` 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() ```rust fn capacity_bytes(&self) -> Option ``` Disk capacity in bytes for disk volumes. `None` for directory volumes.

Returns

Option<u64>
Capacity in bytes, or None.
#### vol.disk_format() ```rust 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() ```rust 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() ```rust fn backend_kind(&self) -> BackendKind ``` Which backend variant this volume is bound to: `Local` or `Cloud`.

Returns

BackendKind
Local or Cloud.
#### vol.local() Local-only ```rust fn local(&self) -> Option<&VolumeLocalState> ``` Returns `Some` for local-backed volumes and `None` otherwise.

Returns

Option<&VolumeLocalState>
Local state, or None.
#### vol.cloud() Cloud-only ```rust fn cloud(&self) -> Option<&VolumeCloudState> ``` Returns `Some` for cloud-backed volumes and `None` otherwise.

Returns

Option<&VolumeCloudState>
Cloud state, or None.
## VolumeHandle

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

A metadata and lifecycle handle for a named volume. #### h.name() ```rust fn name(&self) -> &str ``` The unique name identifying this volume.

Returns

&str
Volume name.
#### h.kind() ```rust fn kind(&self) -> VolumeKind ``` The storage kind. See [`VolumeKind`](#volumekind).

Returns

Storage kind.
#### h.fs() ```rust fn fs(&self) -> VolumeFs<'_> ``` ```rust 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`](#volumefs).

Returns

Filesystem handle.
#### h.remove() ```rust async fn remove(&self) -> MicrosandboxResult<()> ``` ```rust 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() ```rust fn used_bytes(&self) -> u64 ``` Disk usage snapshot from when this handle was created. Not live; call [`Volume::get()`](#volumeget) again for a fresh reading.

Returns

u64
Bytes used at handle-creation time.
#### h.quota_mib() ```rust fn quota_mib(&self) -> Option ``` Maximum storage in MiB, or `None` if unlimited.

Returns

Option<u32>
Quota in MiB, or None.
#### h.capacity_bytes() ```rust fn capacity_bytes(&self) -> Option ``` Disk capacity in bytes for disk volumes. `None` for directory volumes.

Returns

Option<u64>
Capacity in bytes, or None.
#### h.disk_format() ```rust 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() ```rust 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() ```rust fn disk_path(&self) -> Option ``` 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() ```rust fn labels(&self) -> &[(String, String)] ``` Key-value labels for organizing and filtering volumes.

Returns

&[(String, String)]
Label pairs.
#### h.created_at() ```rust fn created_at(&self) -> Option> ``` When this volume was first created, if recorded.

Returns

Option<DateTime<Utc>>
Creation timestamp, or None.
#### h.backend_kind() ```rust fn backend_kind(&self) -> BackendKind ``` Which backend variant this handle is bound to: `Local` or `Cloud`.

Returns

BackendKind
Local or Cloud.
#### h.local() Local-only ```rust fn local(&self) -> Option<&VolumeHandleLocalState> ``` Returns `Some` for local-backed handles and `None` otherwise.

Returns

Option<&VolumeHandleLocalState>
Local state, or None.
#### h.cloud() Cloud-only ```rust fn cloud(&self) -> Option<&VolumeHandleCloudState> ``` Returns `Some` for cloud-backed handles and `None` otherwise.

Returns

Option<&VolumeHandleCloudState>
Cloud state, or None.
## VolumeFs Local operations remain confined to the opened volume directory, including symlink traversal, missing parents, streams, copy, rename, and recursive deletion. Paths that leave the volume return an error. A leading `/` denotes the volume root; valid in-volume parent components and symlinks keep their meaning. Removing or renaming the volume root is refused.

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

Host-side filesystem operations for a named volume. #### fs.read() ```rust async fn read(&self, path: &str) -> MicrosandboxResult ``` ```rust 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() ```rust async fn read_to_string(&self, path: &str) -> MicrosandboxResult ``` ```rust 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() ```rust async fn read_stream(&self, path: &str) -> MicrosandboxResult ``` ```rust 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`](#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

Chunked reader.
#### fs.write() ```rust async fn write(&self, path: &str, data: impl AsRef<[u8]>) -> MicrosandboxResult<()> ``` ```rust 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() ```rust async fn write_stream(&self, path: &str) -> MicrosandboxResult ``` ```rust 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`](#volumefswritesink) that accepts chunks of bytes. Creates parent directories as needed.

Parameters

path&str
File path relative to the volume root.

Returns

Chunked writer.
#### fs.list() ```rust async fn list(&self, path: &str) -> MicrosandboxResult> ``` ```rust 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

Directory entries.
#### fs.mkdir() ```rust async fn mkdir(&self, path: &str) -> MicrosandboxResult<()> ``` ```rust 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() ```rust async fn remove(&self, path: &str) -> MicrosandboxResult<()> ``` ```rust vol.fs().remove("/data/stale.tmp").await?; ``` Delete a single file. Use [`remove_dir()`](#fs-remove_dir) for directories.

Parameters

path&str
File path relative to the volume root.
#### fs.remove_dir() ```rust async fn remove_dir(&self, path: &str) -> MicrosandboxResult<()> ``` ```rust 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() ```rust async fn copy(&self, from: &str, to: &str) -> MicrosandboxResult<()> ``` ```rust 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() ```rust async fn rename(&self, from: &str, to: &str) -> MicrosandboxResult<()> ``` ```rust 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() ```rust async fn stat(&self, path: &str) -> MicrosandboxResult ``` ```rust 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

Entry metadata.
#### fs.exists() ```rust async fn exists(&self, path: &str) -> MicrosandboxResult ``` ```rust 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

Returned by Volume::builder()

Builder for configuring a named volume. #### volume_builder.directory() ```rust fn directory(self) -> Self ``` Create a directory-backed named volume (mounted through virtiofs). This is the default. #### volume_builder.disk() Local-only ```rust fn disk(self) -> Self ``` Create a raw ext4 disk-image named volume (mounted through virtio-blk). Requires [`.size()`](#volume_builder-size). #### volume_builder.size() Local-only ```rust fn size(self, size: impl Into) -> Self ``` ```rust 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.
#### volume_builder.quota() Limited on cloud ```rust fn quota(self, size: impl Into) -> 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()`](#volume_builder-size).

Parameters

sizeimpl Into<Mebibytes>
Quota in MiB.
#### volume_builder.label() ```rust fn label(self, key: impl Into, value: impl Into) -> 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.
#### volume_builder.build() ```rust fn build(self) -> VolumeConfig ``` Materialize the [`VolumeConfig`](#volumespec) without creating the volume. Pass the result to [`Volume::create()`](#volumecreate) to provision it later.

Returns

The volume configuration.
#### volume_builder.create() ```rust async fn create(self) -> MicrosandboxResult ``` ```rust 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

The created volume.
## MountBuilder #### mount.owned() ```rust fn owned(self) -> Self ``` Create an empty directory owned by this sandbox. It survives stop/start and is removed with the sandbox. Snapshots and forks capture it; restore makes private copies. Cloud rejects owned mounts. #### mount.owned_with() ```rust fn owned_with(self, f: impl FnOnce(OwnedVolumeBuilder) -> OwnedVolumeBuilder) -> Self ``` Configure an owned directory or raw ext4 disk. Directory storage accepts a quota; disks require a positive size. Common mount flags stay on `MountBuilder`. See [owned mounts](/sandboxes/volumes#owned-volumes) for lifecycle and examples. #### mount.bind() Limited on cloud ```rust fn bind(self, host: impl Into) -> 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.
#### mount.named() ```rust fn named(self, name: impl Into) -> Self ``` Mount a named volume created via [`Volume::create()`](#volumecreate). The volume must already exist. Persists across sandbox restarts and can be shared between sandboxes. For sandbox-time provisioning, use [`.named_with()`](#mount-named_with).

Parameters

nameimpl Into<String>
Volume name.
#### mount.named_with() Limited on cloud ```rust fn named_with( self, name: impl Into, f: impl FnOnce(NamedVolumeBuilder) -> NamedVolumeBuilder, ) -> Self ``` ```rust 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`](#namedvolumebuilder) closure. `existing` (the default) behaves like [`.named()`](#mount-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.
Configure existence behavior and creation metadata.
#### mount.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. Cap its size with [`.size()`](#mb-size). #### mount.disk() Limited on cloud ```rust fn disk(self, host: impl Into) -> 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()`](#mount-format).

Parameters

hostimpl Into<PathBuf>
Disk image path on the host.
#### mount.format() ```rust fn format(self, format: DiskImageFormat) -> Self ``` Override the disk-image format for a [`.disk()`](#mb-disk) mount. Valid only with `.disk()`; calling it on a bind, named, or tmpfs mount errors when the `SandboxBuilder` is finalized.

Parameters

Disk image format.
#### mount.fstype() ```rust fn fstype(self, fstype: impl Into) -> Self ``` Set the inner filesystem type for a [`.disk()`](#mb-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.
#### mount.readonly() ```rust 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`). #### mount.noexec() ```rust 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. #### mount.nosuid() ```rust fn nosuid(self) -> Self ``` Ignore setuid and setgid privilege elevation from files on this mount. #### mount.nodev() ```rust fn nodev(self) -> Self ``` Ignore device files on this mount. #### mount.stat_virtualization() ```rust fn stat_virtualization(self, policy: StatVirtualization) -> Self ``` Set the guest stat virtualization policy for a virtiofs-backed mount. Default: [`Strict`](#statvirtualization). 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

Stat virtualization policy.
#### mount.host_permissions() ```rust fn host_permissions(self, policy: HostPermissions) -> Self ``` Set the host permission propagation policy for a virtiofs-backed mount. Default: [`Private`](#hostpermissions). Valid only for bind and directory-backed named-volume mounts. Combining [`StatVirtualization::Off`](#statvirtualization) with [`HostPermissions::Mirror`](#hostpermissions) is rejected, since with no overlay the guest chmod already hits the host inode and `Mirror` would be a no-op.

Parameters

Host permission propagation policy.
#### mount.owner() ```rust fn owner(self, uid: u32, gid: u32) -> Self ``` Present host files without a per-file stat override as the specified guest owner. Existing per-file overrides still take precedence, and the host inode is not changed. Valid only for bind and directory-backed named-volume mounts with stat virtualization enabled; tmpfs, disk images, disk-backed named volumes, and `StatVirtualization::Off` are rejected. ```rust let sb = Sandbox::builder("worker") .image("python") .volume("/workspace", |mount| mount.bind("./workspace").owner(1000, 1000)) .create() .await?; ``` #### mount.size() ```rust fn size(self, size: impl Into) -> Self ``` Set the size limit for a [`.tmpfs()`](#mount-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.
#### mount.build() ```rust fn build(self) -> MicrosandboxResult ``` Validate and materialize the mount. Usually called internally by `SandboxBuilder::volume`; call it directly only when assembling a [`VolumeMount`](#mountbuilder) 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

Used by MountBuilder::named_with()

Sub-builder for [`MountBuilder::named_with()`](#mount-named_with). Selects the sandbox-time existence behavior and, for `create` / `ensure_exists`, the creation metadata. Defaults to `existing` and directory-backed. #### named.existing() ```rust fn existing(self) -> Self ``` Require the named volume to already exist. This is the default. #### named.create() ```rust fn create(self) -> Self ``` Create the named volume at sandbox launch and fail if it already exists. #### named.ensure_exists() ```rust 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. #### named.name() ```rust fn name(self, name: impl Into) -> Self ``` Override the volume name passed to [`named_with()`](#mount-named_with).

Parameters

nameimpl Into<String>
Volume name.
#### named.directory() ```rust fn directory(self) -> Self ``` Use directory-backed storage for a created volume. This is the default. Clears any previously set disk capacity. #### named.disk() Local-only ```rust fn disk(self) -> Self ``` Use raw ext4 disk-image storage for a created volume. Requires [`.size()`](#nv-size). Clears any previously set quota. #### named.size() Local-only ```rust fn size(self, size: impl Into) -> 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.
#### named.quota() Limited on cloud ```rust fn quota(self, size: impl Into) -> 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.
#### named.label() ```rust fn label(self, key: impl Into, value: impl Into) -> 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.
## VolumeFsReadStream

Returned by VolumeFs::read_stream()

A streaming reader for file data from a local volume directory. #### stream.recv() ```rust recv() ``` Next chunk; `None` at EOF

Returns

`Option` #### stream.collect() ```rust collect() ``` Read the rest into one buffer

Returns

`Bytes` ## VolumeFsWriteSink

Returned by VolumeFs::write_stream()

A streaming writer for file data to a local volume directory. #### sink.write() ```rust write(data) ``` Append a chunk #### sink.close() ```rust close() ``` Flush and close ## Types ### 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`](#volumekind) | Storage kind | | `quota_mib` | `Option` | Size quota in MiB; `None` is unlimited | | `capacity_mib` | `Option` | 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`](#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 | | `override_uid` | `Option` | Guest uid fallback for host files without a per-file override; set together with `override_gid` via [`MountBuilder::owner()`](#mount-owner) | | `override_gid` | `Option` | Guest gid fallback for host files without a per-file override; set together with `override_uid` via [`MountBuilder::owner()`](#mount-owner) | ### StatVirtualization Stat virtualization policy for a virtiofs-backed mount. Default: `Strict`. Set via [`MountBuilder::stat_virtualization()`](#mount-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()`](#mount-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()`](#mount-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`](#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 | ## OwnedVolumeBuilder #### owned.directory() ```rust fn directory(self) -> Self ``` Select directory storage (the default). #### owned.disk() ```rust fn disk(self) -> Self ``` Select raw ext4 disk storage. Requires a positive size. #### owned.quota() ```rust fn quota(self, quota: impl Into) -> Self ``` Set a directory quota in MiB. Unset means no quota. #### owned.size() ```rust fn size(self, size: impl Into) -> Self ``` Set disk capacity in MiB. The value must be positive.