Rust SDK Volumes reference

See Volumes for usage examples.

Volume

Volume::get_default()

async fn get_default() -> MicrosandboxResult<VolumeHandle>

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.

Example

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()

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

Example

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

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

Parameters

nameimpl Into<String>

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

Returns

VolumeBuilder

Builder for configuring the volume.

Volume::create()

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

Example

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

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

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

Parameters

configVolumeConfig

Volume configuration. VolumeConfig is an alias for VolumeSpec.

Returns

Volume

The created volume.

Volume::get()

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

Example

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

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

Parameters

name&str

Volume name.

Returns

VolumeHandle

Handle for host-side operations.

Volume::list()

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

Example

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

List all named volumes, newest first.

Returns

Vec<VolumeHandle>

All volume handles.

Volume::remove()

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

Example

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

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

Parameters

name&str

Volume name.

Instance methods

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

vol.name()

fn name(&self) -> &str

The unique name identifying this volume.

Returns

&str

Volume name.

vol.kind()

fn kind(&self) -> VolumeKind

The storage kind: Directory or Disk.

Returns

VolumeKind

Storage kind.

vol.fs()

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

Example

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

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

Returns

VolumeFs

Filesystem handle.

vol.path()

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

Example

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

The host-side directory where this volume’s data is stored.

Returns

&Path

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

vol.disk_path()

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

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

Returns

Option<PathBuf>

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

vol.capacity_bytes()

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

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

Returns

Option<u64>

Capacity in bytes, or None.

vol.disk_format()

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

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

Returns

Option<&str>

Format string, or None.

vol.disk_fstype()

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

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

Returns

Option<&str>

Filesystem type, or None.

vol.backend_kind()

fn backend_kind(&self) -> BackendKind

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

Returns

BackendKind

Local or Cloud.

vol.local()

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

Returns Some for local-backed volumes and None otherwise.

Returns

Option<&VolumeLocalState>

Local state, or None.

vol.cloud()

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()

fn name(&self) -> &str

The unique name identifying this volume.

Returns

&str

Volume name.

h.kind()

fn kind(&self) -> VolumeKind

The storage kind: Directory or Disk.

Returns

VolumeKind

Storage kind.

h.fs()

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

Example

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

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

Returns

VolumeFs

Filesystem handle.

h.remove()

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

Example

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

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

h.used_bytes()

fn used_bytes(&self) -> u64

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

Returns

u64

Bytes used at handle-creation time.

h.quota_mib()

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

Maximum storage in MiB, or None if unlimited.

Returns

Option<u32>

Quota in MiB, or None.

h.capacity_bytes()

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

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

Returns

Option<u64>

Capacity in bytes, or None.

h.disk_format()

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

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

Returns

Option<&str>

Format string, or None.

h.disk_fstype()

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

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

Returns

Option<&str>

Filesystem type, or None.

h.disk_path()

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

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

Returns

Option<PathBuf>

Path to disk.raw, or None.

h.labels()

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

Key-value labels for organizing and filtering volumes.

Returns

&[(String, String)]

Label pairs.

h.created_at()

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

When this volume was first created, if recorded.

Returns

Option<DateTime<Utc>>

Creation timestamp, or None.

h.backend_kind()

fn backend_kind(&self) -> BackendKind

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

Returns

BackendKind

Local or Cloud.

h.local()

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

Returns Some for local-backed handles and None otherwise.

Returns

Option<&VolumeHandleLocalState>

Local state, or None.

h.cloud()

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()

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

Example

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

Read an entire file into memory as raw bytes.

Parameters

path&str

File path relative to the volume root.

Returns

Bytes

File contents.

fs.read_to_string()

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

Example

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

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

Parameters

path&str

File path relative to the volume root.

Returns

String

File contents as UTF-8.

fs.read_stream()

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

Example

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

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

Parameters

path&str

File path relative to the volume root.

Returns

VolumeFsReadStream

Chunked reader.

fs.write()

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

Example

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

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

Parameters

path&str

File path relative to the volume root.

dataimpl AsRef<[u8]>

Bytes to write.

fs.write_stream()

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

Example

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

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

Parameters

path&str

File path relative to the volume root.

Returns

VolumeFsWriteSink

Chunked writer.

fs.list()

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

Example

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

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

Parameters

path&str

Directory path relative to the volume root.

Returns

Vec<FsEntry>

Directory entries.

fs.mkdir()

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

Example

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

Create a directory and any missing parents.

Parameters

path&str

Directory path relative to the volume root.

fs.remove()

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

Example

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

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

Parameters

path&str

File path relative to the volume root.

fs.remove_dir()

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

Example

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

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

Parameters

path&str

Directory path relative to the volume root.

fs.copy()

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

Example

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

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

Parameters

from&str

Source path relative to the volume root.

to&str

Destination path relative to the volume root.

fs.rename()

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

Example

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

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

Parameters

from&str

Source path relative to the volume root.

to&str

Destination path relative to the volume root.

fs.stat()

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

Example

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

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

Parameters

path&str

Path relative to the volume root.

Returns

FsMetadata

Entry metadata.

fs.exists()

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

Example

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

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

Parameters

path&str

Path relative to the volume root.

Returns

bool

true if the path exists.

VolumeBuilder

Returned by Volume::builder()

Builder for configuring a named volume.

volume_builder.directory()

fn directory(self) -> Self

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

volume_builder.disk()

fn disk(self) -> Self

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

volume_builder.size()

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

Example

use microsandbox::size::SizeExt;

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

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

Parameters

sizeimpl Into<Mebibytes>

Capacity in MiB.

volume_builder.quota()

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

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

Parameters

sizeimpl Into<Mebibytes>

Quota in MiB.

volume_builder.label()

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

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

Parameters

keyimpl Into<String>

Label key.

valueimpl Into<String>

Label value.

volume_builder.build()

fn build(self) -> VolumeConfig

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

Returns

VolumeConfig

The volume configuration.

volume_builder.create()

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

Example

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

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

Returns

Volume

The created volume.

MountBuilder

Used by SandboxBuilder::volume()

Builder for configuring a sandbox volume mount.

mount.bind()

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

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

Parameters

hostimpl Into<PathBuf>

Directory path on the host.

mount.named()

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

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

Parameters

nameimpl Into<String>

Volume name.

mount.named_with()

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

Example

use microsandbox::size::SizeExt;

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

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

Parameters

nameimpl Into<String>

Volume name.

fFnOnce(NamedVolumeBuilder)

Configure existence behavior and creation metadata.

mount.tmpfs()

fn tmpfs(self) -> Self

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

mount.disk()

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

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

Parameters

hostimpl Into<PathBuf>

Disk image path on the host.

mount.format()

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

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

Parameters

formatDiskImageFormat

Disk image format.

mount.fstype()

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

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

Parameters

fstypeimpl Into<String>

Inner filesystem type.

mount.readonly()

fn readonly(self) -> Self

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

mount.noexec()

fn noexec(self) -> Self

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

mount.nosuid()

fn nosuid(self) -> Self

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

mount.nodev()

fn nodev(self) -> Self

Ignore device files on this mount.

mount.stat_virtualization()

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

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

Parameters

policyStatVirtualization

Stat virtualization policy.

mount.host_permissions()

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

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

Parameters

policyHostPermissions

Host permission propagation policy.

mount.owner()

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.

let sb = Sandbox::builder("worker")
    .image("python")
    .volume("/workspace", |mount| mount.bind("./workspace").owner(1000, 1000))
    .create()
    .await?;

mount.size()

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

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

Parameters

sizeimpl Into<Mebibytes>

Size limit in MiB.

mount.build()

fn build(self) -> MicrosandboxResult<VolumeMount>

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

Returns

VolumeMount

Validated mount specification.

NamedVolumeBuilder

Used by MountBuilder::named_with()

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

named.existing()

fn existing(self) -> Self

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

named.create()

fn create(self) -> Self

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

named.ensure_exists()

fn ensure_exists(self) -> Self

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

named.name()

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

Override the volume name passed to named_with().

Parameters

nameimpl Into<String>

Volume name.

named.directory()

fn directory(self) -> Self

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

named.disk()

fn disk(self) -> Self

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

named.size()

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

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

Parameters

sizeimpl Into<Mebibytes>

Capacity in MiB.

named.quota()

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

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

Parameters

sizeimpl Into<Mebibytes>

Quota in MiB.

named.label()

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

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

Parameters

keyimpl Into<String>

Label key.

valueimpl Into<String>

Label value.

VolumeFsReadStream

Returned by VolumeFs::read_stream()

A streaming reader for file data from a local volume directory.

stream.recv()

recv()

Next chunk; None at EOF

Returns

Option<Bytes>

stream.collect()

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()

write(data)

Append a chunk

sink.close()

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`	Storage kind
`quota_mib`	`Option<u32>`	Size quota in MiB; `None` is unlimited
`capacity_mib`	`Option<u32>`	Disk capacity in MiB; required for disk volumes
`labels`	`Vec<(String, String)>`	Organization labels

MountOptions

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

Field	Type	Description
`readonly`	`bool`	Guest writes fail; virtiofs mounts also reject host-side writes
`noexec`	`bool`	Direct execution from the mount is disabled
`nosuid`	`bool`	setuid/setgid elevation from files on the mount is ignored
`nodev`	`bool`	Device files on the mount are ignored
`override_uid`	`Option<u32>`	Guest uid fallback for host files without a per-file override; set together with `override_gid` via `MountBuilder::owner()`
`override_gid`	`Option<u32>`	Guest gid fallback for host files without a per-file override; set together with `override_uid` via `MountBuilder::owner()`

StatVirtualization

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

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

HostPermissions

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

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

DiskImageFormat

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

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

NamedVolumeMode

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

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

​Volume

​Volume::get_default()

​Volume::builder()

​Volume::create()

​Volume::get()

​Volume::list()

​Volume::remove()

​vol.name()

​vol.kind()

​vol.fs()

​vol.path()

​vol.disk_path()

​vol.capacity_bytes()

​vol.disk_format()

​vol.disk_fstype()

​vol.backend_kind()

​vol.local()

​vol.cloud()

​VolumeHandle

​h.name()

​h.kind()

​h.fs()

​h.remove()

​h.used_bytes()

​h.quota_mib()

​h.capacity_bytes()

​h.disk_format()

​h.disk_fstype()

​h.disk_path()

​h.labels()

​h.created_at()

​h.backend_kind()

​h.local()

​h.cloud()

​VolumeFs

​fs.read()

​fs.read_to_string()

​fs.read_stream()

​fs.write()

​fs.write_stream()

​fs.list()

​fs.mkdir()

​fs.remove()

​fs.remove_dir()

​fs.copy()

​fs.rename()

​fs.stat()

​fs.exists()

​VolumeBuilder

​volume_builder.directory()

​volume_builder.disk()

​volume_builder.size()

​volume_builder.quota()

​volume_builder.label()

​volume_builder.build()

​volume_builder.create()

​MountBuilder

​mount.bind()

​mount.named()

​mount.named_with()

​mount.tmpfs()

​mount.disk()

​mount.format()

​mount.fstype()

​mount.readonly()

​mount.noexec()

​mount.nosuid()

​mount.nodev()

​mount.stat_virtualization()

​mount.host_permissions()

​mount.owner()

​mount.size()

​mount.build()

​NamedVolumeBuilder

​named.existing()

​named.create()

​named.ensure_exists()

​named.name()

​named.directory()

​named.disk()

Volume

Volume::get_default()

Volume::builder()

Volume::create()

Volume::get()

Volume::list()

Volume::remove()

vol.name()

vol.kind()

vol.fs()

vol.path()

vol.disk_path()

vol.capacity_bytes()

vol.disk_format()

vol.disk_fstype()

vol.backend_kind()

vol.local()

vol.cloud()

VolumeHandle

h.name()

h.kind()

h.fs()

h.remove()

h.used_bytes()

h.quota_mib()

h.capacity_bytes()

h.disk_format()

h.disk_fstype()

h.disk_path()

h.labels()

h.created_at()

h.backend_kind()

h.local()

h.cloud()

VolumeFs

fs.read()

fs.read_to_string()

fs.read_stream()

fs.write()

fs.write_stream()

fs.list()

fs.mkdir()

fs.remove()

fs.remove_dir()

fs.copy()

fs.rename()

fs.stat()

fs.exists()

VolumeBuilder

volume_builder.directory()

volume_builder.disk()

volume_builder.size()

volume_builder.quota()

volume_builder.label()

volume_builder.build()

volume_builder.create()

MountBuilder

mount.bind()

mount.named()

mount.named_with()

mount.tmpfs()

mount.disk()

mount.format()

mount.fstype()

mount.readonly()

mount.noexec()

mount.nosuid()

mount.nodev()

mount.stat_virtualization()

mount.host_permissions()

mount.owner()

mount.size()

mount.build()

NamedVolumeBuilder

named.existing()

named.create()

named.ensure_exists()

named.name()

named.directory()

named.disk()