> ## Documentation Index > Fetch the complete documentation index at: https://microsanbox-staging-appcypher-sdk-runtime-bootstrap.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Volumes > Rust SDK - Volume API reference Create, manage, and mount named volumes. See [Volumes](/sandboxes/volumes) for usage examples. ## Volume #### Volume::get\_default() Cloud-only ```rust theme={null} 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 theme={null} 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 theme={null} fn builder(name: impl Into) -> VolumeBuilder ``` ```rust theme={null} 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()`](#disk) then [`.size()`](#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\
Volume name, e.g. "pip-cache".

Returns

VolumeBuilder
Builder for configuring the volume.
#### Volume::create() Limited on cloud ```rust theme={null} async fn create(config: VolumeConfig) -> MicrosandboxResult ``` ```rust theme={null} 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 theme={null} async fn get(name: &str) -> MicrosandboxResult ``` ```rust theme={null} 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 theme={null} async fn list() -> MicrosandboxResult> ``` ```rust theme={null} for h in Volume::list().await? { println!("{} - {:?}", h.name(), h.kind()); } ``` List all named volumes, newest first.

Returns

All volume handles.
#### Volume::remove() ```rust theme={null} async fn remove(name: &str) -> MicrosandboxResult<()> ``` ```rust theme={null} 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.

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 theme={null} fn name(&self) -> &str ``` The unique name identifying this volume.

Returns

\&str
Volume name.
#### vol.kind() ```rust theme={null} fn kind(&self) -> VolumeKind ``` The storage kind: [`Directory`](#volumekind) or [`Disk`](#volumekind).

Returns

Storage kind.
#### vol.fs() ```rust theme={null} fn fs(&self) -> VolumeFs<'_> ``` ```rust theme={null} 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 theme={null} fn path(&self) -> MicrosandboxResult<&Path> ``` ```rust theme={null} 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 theme={null} 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\
Path to disk.raw, or None for directory volumes.
#### vol.capacity\_bytes() ```rust theme={null} fn capacity_bytes(&self) -> Option ``` Disk capacity in bytes for disk volumes. `None` for directory volumes.

Returns

Option\
Capacity in bytes, or None.
#### vol.disk\_format() ```rust theme={null} 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 theme={null} 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 theme={null} 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 theme={null} 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 theme={null} 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 theme={null} fn name(&self) -> &str ``` The unique name identifying this volume.

Returns

\&str
Volume name.
#### h.kind() ```rust theme={null} fn kind(&self) -> VolumeKind ``` The storage kind: [`Directory`](#volumekind) or [`Disk`](#volumekind).

Returns

Storage kind.
#### h.fs() ```rust theme={null} fn fs(&self) -> VolumeFs<'_> ``` ```rust theme={null} 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 theme={null} async fn remove(&self) -> MicrosandboxResult<()> ``` ```rust theme={null} 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 theme={null} 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 theme={null} fn quota_mib(&self) -> Option ``` Maximum storage in MiB, or `None` if unlimited.

Returns

Option\
Quota in MiB, or None.
#### h.capacity\_bytes() ```rust theme={null} fn capacity_bytes(&self) -> Option ``` Disk capacity in bytes for disk volumes. `None` for directory volumes.

Returns

Option\
Capacity in bytes, or None.
#### h.disk\_format() ```rust theme={null} 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 theme={null} 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 theme={null} fn disk_path(&self) -> Option ``` Host path to the managed raw disk image (`disk.raw`) for local disk volumes. `None` otherwise.

Returns

Option\
Path to disk.raw, or None.
#### h.labels() ```rust theme={null} fn labels(&self) -> &[(String, String)] ``` Key-value labels for organizing and filtering volumes.

Returns

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

Returns

Option\>
Creation timestamp, or None.
#### h.backend\_kind() ```rust theme={null} 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 theme={null} 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 theme={null} fn cloud(&self) -> Option<&VolumeHandleCloudState> ``` Returns `Some` for cloud-backed handles and `None` otherwise.

Returns

Option\<\&VolumeHandleCloudState>
Cloud state, or None.
## VolumeFs

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

Host-side filesystem operations for a named volume. #### fs.read() ```rust theme={null} async fn read(&self, path: &str) -> MicrosandboxResult ``` ```rust theme={null} 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 theme={null} async fn read_to_string(&self, path: &str) -> MicrosandboxResult ``` ```rust theme={null} 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 theme={null} async fn read_stream(&self, path: &str) -> MicrosandboxResult ``` ```rust theme={null} 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 theme={null} async fn write(&self, path: &str, data: impl AsRef<[u8]>) -> MicrosandboxResult<()> ``` ```rust theme={null} 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 theme={null} async fn write_stream(&self, path: &str) -> MicrosandboxResult ``` ```rust theme={null} 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 theme={null} async fn list(&self, path: &str) -> MicrosandboxResult> ``` ```rust theme={null} 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 theme={null} async fn mkdir(&self, path: &str) -> MicrosandboxResult<()> ``` ```rust theme={null} 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 theme={null} async fn remove(&self, path: &str) -> MicrosandboxResult<()> ``` ```rust theme={null} 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 theme={null} async fn remove_dir(&self, path: &str) -> MicrosandboxResult<()> ``` ```rust theme={null} 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 theme={null} async fn copy(&self, from: &str, to: &str) -> MicrosandboxResult<()> ``` ```rust theme={null} 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 theme={null} async fn rename(&self, from: &str, to: &str) -> MicrosandboxResult<()> ``` ```rust theme={null} 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 theme={null} async fn stat(&self, path: &str) -> MicrosandboxResult ``` ```rust theme={null} 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 theme={null} async fn exists(&self, path: &str) -> MicrosandboxResult ``` ```rust theme={null} 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 theme={null} fn directory(self) -> Self ``` Create a directory-backed named volume (mounted through virtiofs). This is the default. #### volume\_builder.disk() Local-only ```rust theme={null} fn disk(self) -> Self ``` Create a raw ext4 disk-image named volume (mounted through virtio-blk). Requires [`.size()`](#size). #### volume\_builder.size() Local-only ```rust theme={null} fn size(self, size: impl Into) -> Self ``` ```rust theme={null} 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\
Capacity in MiB.
#### volume\_builder.quota() Limited on cloud ```rust theme={null} 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()`](#size).

Parameters

sizeimpl Into\
Quota in MiB.
#### volume\_builder.label() ```rust theme={null} 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\
Label key.
valueimpl Into\
Label value.
#### volume\_builder.build() ```rust theme={null} 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 theme={null} async fn create(self) -> MicrosandboxResult ``` ```rust theme={null} 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

Used by SandboxBuilder::volume()

Builder for configuring a sandbox volume mount. #### mount.bind() Limited on cloud ```rust theme={null} 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\
Directory path on the host.
#### mount.named() ```rust theme={null} 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()`](#named_with).

Parameters

nameimpl Into\
Volume name.
#### mount.named\_with() Limited on cloud ```rust theme={null} fn named_with( self, name: impl Into, f: impl FnOnce(NamedVolumeBuilder) -> NamedVolumeBuilder, ) -> Self ``` ```rust theme={null} 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-2) closure. `existing` (the default) behaves like [`.named()`](#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\
Volume name.
Configure existence behavior and creation metadata.
#### mount.tmpfs() ```rust theme={null} 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 theme={null} 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()`](#format).

Parameters

hostimpl Into\
Disk image path on the host.
#### mount.format() ```rust theme={null} 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 theme={null} 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\
Inner filesystem type.
#### mount.readonly() ```rust theme={null} 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 theme={null} 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 theme={null} fn nosuid(self) -> Self ``` Ignore setuid and setgid privilege elevation from files on this mount. #### mount.nodev() ```rust theme={null} fn nodev(self) -> Self ``` Ignore device files on this mount. #### mount.stat\_virtualization() ```rust theme={null} 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 theme={null} 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 theme={null} 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 theme={null} let sb = Sandbox::builder("worker") .image("python") .volume("/workspace", |mount| mount.bind("./workspace").owner(1000, 1000)) .create() .await?; ``` #### mount.size() ```rust theme={null} fn size(self, size: impl Into) -> Self ``` Set the size limit for a [`.tmpfs()`](#tmpfs) mount. Accepts a bare `u32` (MiB) or a `SizeExt` helper such as `1.gib()`. Valid only for tmpfs mounts.

Parameters

sizeimpl Into\
Size limit in MiB.
#### mount.build() ```rust theme={null} fn build(self) -> MicrosandboxResult ``` Validate and materialize the mount. Usually called internally by `SandboxBuilder::volume`; call it directly only when assembling a [`VolumeMount`](#mountbuilder-2) 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()`](#named_with). Selects sandbox-time existence behavior and creation metadata.

Used by MountBuilder::named\_with()

Sub-builder for [`MountBuilder::named_with()`](#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 theme={null} fn existing(self) -> Self ``` Require the named volume to already exist. This is the default. #### named.create() ```rust theme={null} fn create(self) -> Self ``` Create the named volume at sandbox launch and fail if it already exists. #### named.ensure\_exists() ```rust theme={null} 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 theme={null} fn name(self, name: impl Into) -> Self ``` Override the volume name passed to [`named_with()`](#named_with).

Parameters

nameimpl Into\
Volume name.
#### named.directory() ```rust theme={null} 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 theme={null} 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 theme={null} 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\
Capacity in MiB.
#### named.quota() Limited on cloud ```rust theme={null} 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\
Quota in MiB.
#### named.label() ```rust theme={null} 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\
Label key.
valueimpl Into\
Label value.
## VolumeFsReadStream A streaming reader for file data from a local volume directory. Returned by [`VolumeFs::read_stream()`](#fs-read_stream).

Returned by VolumeFs::read\_stream()

#### stream.recv() ```rust theme={null} recv() ``` Next chunk; `None` at EOF

Returns

`Option` #### stream.collect() ```rust theme={null} collect() ``` Read the rest into one buffer

Returns

`Bytes` ## VolumeFsWriteSink A streaming writer for file data to a local volume directory. Returned by [`VolumeFs::write_stream()`](#fs-write_stream).

Returned by VolumeFs::write\_stream()

#### sink.write() ```rust theme={null} write(data) ``` Append a chunk #### sink.close() ```rust theme={null} 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-2) 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()`](#owner) | | `override_gid` | `Option` | Guest gid fallback for host files without a per-file override; set together with `override_uid` via [`MountBuilder::owner()`](#owner) | ### StatVirtualization Stat virtualization policy for a virtiofs-backed mount. Default: `Strict`. Set via [`MountBuilder::stat_virtualization()`](#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()`](#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()`](#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-2). | 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 |