--- title: Volumes description: Rust SDK - Volume API reference --- 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](/sandboxes/volumes) for usage examples and patterns.

Static · Volume5

Volume::builder()configure a new volume Volume::create()provision from a config Volume::get()handle to an existing one Volume::list()all volumes Volume::remove()delete by name

Instance · Volume11

vol.name()volume name vol.kind()directory or disk vol.fs()read / write files vol.path()host data directory vol.disk_path()host disk image path vol.capacity_bytes()disk capacity vol.disk_format()disk image format vol.disk_fstype()inner disk filesystem vol.backend_kind()local or cloud vol.local()local-only state vol.cloud()cloud-only state

Instance · VolumeHandle15

h.name()volume name h.kind()directory or disk h.fs()read / write files h.remove()delete this volume h.used_bytes()usage snapshot h.quota_mib()storage quota h.capacity_bytes()disk capacity h.disk_format()disk image format h.disk_fstype()inner disk filesystem h.disk_path()host disk image path h.labels()key-value labels h.created_at()creation time h.backend_kind()local or cloud h.local()local-only state h.cloud()cloud-only state

Instance · VolumeFs13

fs.read()read bytes fs.read_to_string()read UTF-8 text fs.read_stream()stream a file in fs.write()write bytes fs.write_stream()stream a file out fs.list()list a directory fs.mkdir()create a directory fs.remove()delete a file fs.remove_dir()delete a directory fs.copy()copy a file fs.rename()rename / move fs.stat()metadata fs.exists()existence check

Builder · VolumeBuilder7

.directory() .disk() .size() .quota() .label() .build() .create()

Builder · MountBuilder15

.bind() .named() .named_with() .tmpfs() .disk() .format() .fstype() .readonly() .noexec() .nosuid() .nodev() .stat_virtualization() .host_permissions() .size() .build()

Builder · NamedVolumeBuilder9

.existing() .create() .ensure_exists() .name() .directory() .disk() .size() .quota() .label()

Types

Volume VolumeHandle VolumeBuilder VolumeFs VolumeFsReadStream VolumeFsWriteSink MountBuilder NamedVolumeBuilder VolumeKind VolumeSpec MountOptions StatVirtualization HostPermissions DiskImageFormat NamedVolumeMode FsEntry FsMetadata

Typical flow

```rust 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()
static
```rust fn builder(name: impl Into) -> VolumeBuilder ``` 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<String>
Volume name, e.g. "pip-cache".

Returns

VolumeBuilder
Builder for configuring the volume.
```rust let vol = Volume::builder("pip-cache").create().await?; ``` --- #### Volume::create()
staticasync
```rust async fn create(config: VolumeConfig) -> MicrosandboxResult ``` 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

configVolumeConfig
Volume configuration. VolumeConfig is an alias for VolumeSpec.

Returns

Volume
The created volume.
```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?; ``` --- #### Volume::get()
staticasync
```rust async fn get(name: &str) -> MicrosandboxResult ``` 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.
```rust let h = Volume::get("pip-cache").await?; println!("{} — {} bytes used", h.name(), h.used_bytes()); ``` --- #### Volume::list()
staticasync
```rust async fn list() -> MicrosandboxResult> ``` List all named volumes, newest first.

Returns

All volume handles.
```rust for h in Volume::list().await? { println!("{} — {:?}", h.name(), h.kind()); } ``` --- #### Volume::remove()
staticasync
```rust async fn remove(name: &str) -> MicrosandboxResult<()> ``` 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.
```rust Volume::remove("pip-cache").await?; ``` --- ## Volume instance methods A live `Volume`, returned by [`Volume::create()`](#volumecreate) or [`VolumeBuilder::create()`](#vb-create). Carries the backend it was created on. --- #### vol.name()
instance
```rust fn name(&self) -> &str ``` The unique name identifying this volume.

Returns

&str
Volume name.
--- #### vol.kind()
instance
```rust fn kind(&self) -> VolumeKind ``` The storage kind: [`Directory`](#volumekind) or [`Disk`](#volumekind).

Returns

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

Returns

Filesystem handle.
```rust vol.fs().write("/seed.txt", "hello").await?; ``` --- #### vol.path()
instance
```rust fn path(&self) -> MicrosandboxResult<&Path> ``` 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/.
```rust println!("{}", vol.path()?.display()); ``` --- #### vol.disk_path()
instance
```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()
instance
```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()
instance
```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()
instance
```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()
instance
```rust fn backend_kind(&self) -> BackendKind ``` Which backend variant this volume is bound to: `Local` or `Cloud`.

Returns

BackendKind
Local or Cloud.
--- #### vol.local()
instance
```rust 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()
instance
```rust 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()`](#volumeget) and [`Volume::list()`](#volumelist). Exposes metadata captured at read time plus filesystem and delete operations, without holding a live [`Volume`](#volume). --- #### h.name()
instance
```rust fn name(&self) -> &str ``` The unique name identifying this volume.

Returns

&str
Volume name.
--- #### h.kind()
instance
```rust fn kind(&self) -> VolumeKind ``` The storage kind: [`Directory`](#volumekind) or [`Disk`](#volumekind).

Returns

Storage kind.
--- #### h.fs()
instance
```rust fn fs(&self) -> VolumeFs<'_> ``` Get a filesystem handle for reading and writing the volume's files directly, without a running sandbox. See [`VolumeFs`](#volumefs).

Returns

Filesystem handle.
```rust let h = Volume::get("pip-cache").await?; let names = h.fs().list("/").await?; ``` --- #### h.remove()
instanceasync
```rust async fn remove(&self) -> MicrosandboxResult<()> ``` Delete this volume and its contents. Locally the database record is removed first, then the directory. ```rust Volume::get("pip-cache").await?.remove().await?; ``` --- #### h.used_bytes()
instance
```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()
instance
```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()
instance
```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()
instance
```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()
instance
```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()
instance
```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()
instance
```rust fn labels(&self) -> &[(String, String)] ``` Key-value labels for organizing and filtering volumes.

Returns

&[(String, String)]
Label pairs.
--- #### h.created_at()
instance
```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()
instance
```rust fn backend_kind(&self) -> BackendKind ``` Which backend variant this handle is bound to: `Local` or `Cloud`.

Returns

BackendKind
Local or Cloud.
--- #### h.local()
instance
```rust 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()
instance
```rust 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()`](#vol-fs) or [`VolumeHandle::fs()`](#h-fs). Unlike [`SandboxFs`](/sdk/rust/filesystem), 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()
instanceasync
```rust async fn read(&self, path: &str) -> MicrosandboxResult ``` Read an entire file into memory as raw bytes.

Parameters

path&str
File path relative to the volume root.

Returns

Bytes
File contents.
```rust let data = vol.fs().read("/seed.txt").await?; ``` --- #### fs.read_to_string()
instanceasync
```rust async fn read_to_string(&self, path: &str) -> MicrosandboxResult ``` 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.
```rust let text = vol.fs().read_to_string("/seed.txt").await?; ``` --- #### fs.read_stream()
instanceasync
```rust async fn read_stream(&self, path: &str) -> MicrosandboxResult ``` 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.
```rust let mut stream = vol.fs().read_stream("/model.bin").await?; while let Some(chunk) = stream.recv().await? { // process chunk } ``` --- #### fs.write()
instanceasync
```rust async fn write(&self, path: &str, data: impl AsRef<[u8]>) -> MicrosandboxResult<()> ``` 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.
```rust vol.fs().write("/config/app.json", r#"{"ready":true}"#).await?; ``` --- #### fs.write_stream()
instanceasync
```rust async fn write_stream(&self, path: &str) -> MicrosandboxResult ``` 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.
```rust let mut sink = vol.fs().write_stream("/upload.bin").await?; sink.write(&chunk).await?; sink.close().await?; ``` --- #### fs.list()
instanceasync
```rust async fn list(&self, path: &str) -> MicrosandboxResult> ``` 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.
```rust for entry in vol.fs().list("/").await? { println!("{} ({} bytes)", entry.path, entry.size); } ``` --- #### fs.mkdir()
instanceasync
```rust async fn mkdir(&self, path: &str) -> MicrosandboxResult<()> ``` Create a directory and any missing parents.

Parameters

path&str
Directory path relative to the volume root.
```rust vol.fs().mkdir("/data/incoming").await?; ``` --- #### fs.remove()
instanceasync
```rust async fn remove(&self, path: &str) -> MicrosandboxResult<()> ``` Delete a single file. Use [`remove_dir()`](#fs-remove_dir) for directories.

Parameters

path&str
File path relative to the volume root.
```rust vol.fs().remove("/data/stale.tmp").await?; ``` --- #### fs.remove_dir()
instanceasync
```rust async fn remove_dir(&self, path: &str) -> MicrosandboxResult<()> ``` Remove a directory and its contents recursively. Targeting the volume root is rejected.

Parameters

path&str
Directory path relative to the volume root.
```rust vol.fs().remove_dir("/data/incoming").await?; ``` --- #### fs.copy()
instanceasync
```rust async fn copy(&self, from: &str, to: &str) -> MicrosandboxResult<()> ``` 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.
```rust vol.fs().copy("/seed.txt", "/backup/seed.txt").await?; ``` --- #### fs.rename()
instanceasync
```rust async fn rename(&self, from: &str, to: &str) -> MicrosandboxResult<()> ``` 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.
```rust vol.fs().rename("/tmp/out.txt", "/done/out.txt").await?; ``` --- #### fs.stat()
instanceasync
```rust async fn stat(&self, path: &str) -> MicrosandboxResult ``` 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.
```rust let meta = vol.fs().stat("/seed.txt").await?; println!("{} bytes", meta.size); ``` --- #### fs.exists()
instanceasync
```rust async fn exists(&self, path: &str) -> MicrosandboxResult ``` 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.
```rust if !vol.fs().exists("/seed.txt").await? { vol.fs().write("/seed.txt", "hello").await?; } ``` --- ## VolumeBuilder Builder for configuring a named volume before creation. Obtained via [`Volume::builder(name)`](#volumebuilder). Directory-backed is the default; disk volumes require [`.disk()`](#disk) plus [`.size()`](#size). Every setter returns `Self`, so calls chain. --- #### .directory()
builder
```rust fn directory(self) -> Self ``` Create a directory-backed named volume (mounted through virtiofs). This is the default. --- #### .disk()
builder
```rust fn disk(self) -> Self ``` Create a raw ext4 disk-image named volume (mounted through virtio-blk). Requires [`.size()`](#size). --- #### .size()
builder
```rust fn size(self, size: impl Into) -> Self ``` 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.
```rust use microsandbox::size::SizeExt; let vol = Volume::builder("docker-data") .disk() .size(20.gib()) .create() .await?; ``` --- #### .quota()
builder
```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()`](#size).

Parameters

sizeimpl Into<Mebibytes>
Quota in MiB.
--- #### .label()
builder
```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.
--- #### .build()
builder
```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.
--- #### .create()
builderasync
```rust async fn create(self) -> MicrosandboxResult ``` Create the volume on the active backend. Equivalent to `Volume::create(self.build())`.

Returns

The created volume.
```rust let vol = Volume::builder("pip-cache") .quota(1024) .label("team", "ml") .create() .await?; ``` --- ## MountBuilder Builder for configuring a volume mount on a sandbox. Used in `SandboxBuilder::volume(guest_path, |v| v...)` (see [`.volume()`](/sdk/rust/sandbox#volume)). Pick exactly one mount kind: [`.bind()`](#bind), [`.named()`](#named) / [`.named_with()`](#named_with), [`.tmpfs()`](#tmpfs), or [`.disk()`](#mb-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()
builder
```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.
--- #### .named()
builder
```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()`](#named_with).

Parameters

nameimpl Into<String>
Volume name.
--- #### .named_with()
builder
```rust fn named_with( self, name: impl Into, f: impl FnOnce(NamedVolumeBuilder) -> NamedVolumeBuilder, ) -> Self ``` 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<String>
Volume name.
Configure existence behavior and creation metadata.
```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?; ``` --- #### .tmpfs()
builder
```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). --- #### .disk()
builder
```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()`](#format).

Parameters

hostimpl Into<PathBuf>
Disk image path on the host.
--- #### .format()
builder
```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.
--- #### .fstype()
builder
```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.
--- #### .readonly()
builder
```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`). --- #### .noexec()
builder
```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. --- #### .nosuid()
builder
```rust fn nosuid(self) -> Self ``` Ignore setuid and setgid privilege elevation from files on this mount. --- #### .nodev()
builder
```rust fn nodev(self) -> Self ``` Ignore device files on this mount. --- #### .stat_virtualization()
builder
```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 named-volume mounts; calling it on a tmpfs or disk-image mount errors at finalize time.

Parameters

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

Parameters

nameimpl Into<String>
Volume name.
--- #### .directory()
builder
```rust fn directory(self) -> Self ``` Use directory-backed storage for a created volume. This is the default. Clears any previously set disk capacity. --- #### .disk()
builder
```rust fn disk(self) -> Self ``` Use raw ext4 disk-image storage for a created volume. Requires [`.size()`](#nv-size). Clears any previously set quota. --- #### .size()
builder
```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.
--- #### .quota()
builder
```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.
--- #### .label()
builder
```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.
--- ## Types --- ### Volume
struct
A live named volume, carrying the backend it was created on. Returned by [`Volume::create()`](#volumecreate) and [`VolumeBuilder::create()`](#vb-create).

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

| Method | Returns | Description | |--------|---------|-------------| | [`name()`](#vol-name) | `&str` | Volume name | | [`kind()`](#vol-kind) | [`VolumeKind`](#volumekind) | Directory or disk | | [`fs()`](#vol-fs) | [`VolumeFs`](#volumefs) | Host-side filesystem handle | | [`path()`](#vol-path) | `MicrosandboxResult<&Path>` | Host data directory (local only) | | [`disk_path()`](#vol-disk_path) | `Option` | Host `disk.raw` path for disk volumes | | [`capacity_bytes()`](#vol-capacity_bytes) | `Option` | Disk capacity in bytes | | [`disk_format()`](#vol-disk_format) | `Option<&str>` | Disk image format | | [`disk_fstype()`](#vol-disk_fstype) | `Option<&str>` | Inner disk filesystem | | [`backend_kind()`](#vol-backend_kind) | `BackendKind` | Local or cloud | | [`local()`](#vol-local) | `Option<&VolumeLocalState>` | Local-only state | | [`cloud()`](#vol-cloud) | `Option<&VolumeCloudState>` | Cloud-only state | --- ### VolumeHandle
struct
A lightweight handle to a volume, exposing metadata plus filesystem and delete operations without a live [`Volume`](#volume).

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

| Method | Returns | Description | |--------|---------|-------------| | [`name()`](#h-name) | `&str` | Volume name | | [`kind()`](#h-kind) | [`VolumeKind`](#volumekind) | Directory or disk | | [`fs()`](#h-fs) | [`VolumeFs`](#volumefs) | Host-side filesystem handle | | [`remove()`](#h-remove) | `MicrosandboxResult<()>` | Delete this volume | | [`used_bytes()`](#h-used_bytes) | `u64` | Usage snapshot at read time | | [`quota_mib()`](#h-quota_mib) | `Option` | Storage quota in MiB | | [`capacity_bytes()`](#h-capacity_bytes) | `Option` | Disk capacity in bytes | | [`disk_format()`](#h-disk_format) | `Option<&str>` | Disk image format | | [`disk_fstype()`](#h-disk_fstype) | `Option<&str>` | Inner disk filesystem | | [`disk_path()`](#h-disk_path) | `Option` | Host `disk.raw` path | | [`labels()`](#h-labels) | `&[(String, String)]` | Key-value labels | | [`created_at()`](#h-created_at) | `Option>` | Creation time | | [`backend_kind()`](#h-backend_kind) | `BackendKind` | Local or cloud | | [`local()`](#h-local) | `Option<&VolumeHandleLocalState>` | Local-only state | | [`cloud()`](#h-cloud) | `Option<&VolumeHandleCloudState>` | Cloud-only state | --- ### VolumeBuilder
struct
Builder for configuring a named volume before creation. Implements `From`.

Returned by Volume::builder()

| Method | Returns | Description | |--------|---------|-------------| | [`directory()`](#directory) | `Self` | Directory-backed (default) | | [`disk()`](#disk) | `Self` | Raw ext4 disk-image volume | | [`size()`](#size) | `Self` | Disk capacity (required for disk) | | [`quota()`](#quota) | `Self` | Directory storage quota | | [`label()`](#label) | `Self` | Attach a label | | [`build()`](#vb-build) | [`VolumeConfig`](#volumespec) | Materialize config | | [`create()`](#vb-create) | [`Volume`](#volume) | Create the volume | --- ### VolumeFs
struct
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()`](#fs-read) | `Bytes` | Read bytes | | [`read_to_string()`](#fs-read_to_string) | `String` | Read UTF-8 text | | [`read_stream()`](#fs-read_stream) | [`VolumeFsReadStream`](#volumefsreadstream) | Stream a file in | | [`write()`](#fs-write) | `()` | Write bytes | | [`write_stream()`](#fs-write_stream) | [`VolumeFsWriteSink`](#volumefswritesink) | Stream a file out | | [`list()`](#fs-list) | `Vec<`[`FsEntry`](/sdk/rust/filesystem#fsentry)`>` | List a directory | | [`mkdir()`](#fs-mkdir) | `()` | Create a directory | | [`remove()`](#fs-remove) | `()` | Delete a file | | [`remove_dir()`](#fs-remove_dir) | `()` | Delete a directory recursively | | [`copy()`](#fs-copy) | `()` | Copy a file | | [`rename()`](#fs-rename) | `()` | Rename / move | | [`stat()`](#fs-stat) | [`FsMetadata`](/sdk/rust/filesystem#fsmetadata) | Metadata | | [`exists()`](#fs-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
struct
A streaming reader for file data from a local volume directory. Returned by [`VolumeFs::read_stream()`](#fs-read_stream).

Returned by VolumeFs::read_stream()

| Method | Returns | Description | |--------|---------|-------------| | `recv()` | `Option` | Next chunk; `None` at EOF | | `collect()` | `Bytes` | Read the rest into one buffer | --- ### VolumeFsWriteSink
struct
A streaming writer for file data to a local volume directory. Returned by [`VolumeFs::write_stream()`](#fs-write_stream).

Returned by VolumeFs::write_stream()

| Method | Returns | Description | |--------|---------|-------------| | `write(data)` | `()` | Append a chunk | | `close()` | `()` | Flush and close | --- ### MountBuilder
struct
Builder for a sandbox volume mount, used in `SandboxBuilder::volume`. Builds a `VolumeMount`.

Used by SandboxBuilder::volume()

| Method | Returns | Description | |--------|---------|-------------| | [`bind()`](#bind) | `Self` | Bind a host directory | | [`named()`](#named) | `Self` | Mount an existing named volume | | [`named_with()`](#named_with) | `Self` | Mount with sandbox-time provisioning | | [`tmpfs()`](#tmpfs) | `Self` | In-memory filesystem | | [`disk()`](#mb-disk) | `Self` | Host disk image as virtio-blk | | [`format()`](#format) | `Self` | Disk image format (disk only) | | [`fstype()`](#fstype) | `Self` | Inner filesystem type (disk only) | | [`readonly()`](#readonly) | `Self` | Block writes | | [`noexec()`](#noexec) | `Self` | Block direct execution | | [`nosuid()`](#nosuid) | `Self` | Ignore setuid/setgid | | [`nodev()`](#nodev) | `Self` | Ignore device files | | [`stat_virtualization()`](#stat_virtualization) | `Self` | Stat virtualization policy (virtiofs) | | [`host_permissions()`](#host_permissions) | `Self` | Host permission policy (virtiofs) | | [`size()`](#mb-size) | `Self` | tmpfs size limit | | [`build()`](#mb-build) | `MicrosandboxResult` | Validate and materialize | --- ### NamedVolumeBuilder
struct
Sub-builder for [`MountBuilder::named_with()`](#named_with). Selects sandbox-time existence behavior and creation metadata.

Used by MountBuilder::named_with()

| Method | Returns | Description | |--------|---------|-------------| | [`existing()`](#nv-existing) | `Self` | Require the volume to exist (default) | | [`create()`](#nv-create) | `Self` | Create, fail if it exists | | [`ensure_exists()`](#nv-ensure_exists) | `Self` | Create if missing, else reuse | | [`name()`](#nv-name) | `Self` | Override the volume name | | [`directory()`](#nv-directory) | `Self` | Directory-backed (default) | | [`disk()`](#nv-disk) | `Self` | Disk-backed; requires `size` | | [`size()`](#nv-size) | `Self` | Disk capacity | | [`quota()`](#nv-quota) | `Self` | Directory quota | | [`label()`](#nv-label) | `Self` | Attach a label | --- ### VolumeKind
enum
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
struct
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
struct
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 | --- ### StatVirtualization
enum
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
enum
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
enum
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
enum
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 |