docs/sdk/rust/volumes.mdx
Create, manage, and mount named volumes. See Volumes for usage examples.
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.
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?);
fn builder(name: impl Into<String>) -> VolumeBuilder
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.
async fn create(config: VolumeConfig) -> MicrosandboxResult<Volume>
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.
async fn get(name: &str) -> MicrosandboxResult<VolumeHandle>
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.
async fn list() -> MicrosandboxResult<Vec<VolumeHandle>>
for h in Volume::list().await? {
println!("{} - {:?}", h.name(), h.kind());
}
List all named volumes, newest first.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#volumehandle">Vec<VolumeHandle></a></div> <div className="msb-param-desc">All volume handles.</div> </div> </div>async fn remove(name: &str) -> MicrosandboxResult<()>
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.
A live Volume, returned by Volume::create() or VolumeBuilder::create(). Carries the backend it was created on.
fn name(&self) -> &str
The unique name identifying this volume.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">&str</span></div> <div className="msb-param-desc">Volume name.</div> </div> </div>fn kind(&self) -> VolumeKind
The storage kind: Directory or Disk.
<Tooltip tip="Unmounted-volume filesystem access is not available on microsandbox cloud; mount the volume into a sandbox and use the sandbox filesystem."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
fn fs(&self) -> VolumeFs<'_>
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.
fn path(&self) -> MicrosandboxResult<&Path>
println!("{}", vol.path()?.display());
The host-side directory where this volume's data is stored (local backend only). Errors with Unsupported for cloud volumes, whose bytes live in the org's object storage rather than on the caller's host.
fn disk_path(&self) -> Option<PathBuf>
Host path to the managed raw disk image (disk.raw) for disk volumes. Returns None for directory volumes.
fn capacity_bytes(&self) -> Option<u64>
Disk capacity in bytes for disk volumes. None for directory volumes.
fn disk_format(&self) -> Option<&str>
Disk image format for disk volumes (always "raw" for managed disk volumes). None for directory volumes.
fn disk_fstype(&self) -> Option<&str>
Inner disk filesystem type for disk volumes (always "ext4" for managed disk volumes). None for directory volumes.
fn backend_kind(&self) -> BackendKind
Which backend variant this volume is bound to: Local or Cloud.
fn local(&self) -> Option<&VolumeLocalState>
Local-only volume state. Returns Some for local-backed volumes, None for cloud-backed ones.
<Tooltip tip="Returns state only for cloud-backed volumes; None on the local backend."><span className="msb-badge-cloud">Cloud-only <Icon icon="circle-info" size={11} /></span></Tooltip>
fn cloud(&self) -> Option<&VolumeCloudState>
Cloud-only volume state. Returns Some for cloud-backed volumes, None for local-backed ones.
A metadata and lifecycle handle for a named volume.
fn name(&self) -> &str
The unique name identifying this volume.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">&str</span></div> <div className="msb-param-desc">Volume name.</div> </div> </div>fn kind(&self) -> VolumeKind
The storage kind: Directory or Disk.
<Tooltip tip="Unmounted-volume filesystem access is not available on microsandbox cloud; mount the volume into a sandbox and use the sandbox filesystem."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
fn fs(&self) -> VolumeFs<'_>
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.
async fn remove(&self) -> MicrosandboxResult<()>
Volume::get("pip-cache").await?.remove().await?;
Delete this volume and its contents. Locally the database record is removed first, then the directory.
fn used_bytes(&self) -> u64
Disk usage snapshot from when this handle was created. Not live, call Volume::get() again for a fresh reading.
fn quota_mib(&self) -> Option<u32>
Maximum storage in MiB, or None if unlimited.
fn capacity_bytes(&self) -> Option<u64>
Disk capacity in bytes for disk volumes. None for directory volumes.
fn disk_format(&self) -> Option<&str>
Disk image format for disk volumes. None for directory volumes.
fn disk_fstype(&self) -> Option<&str>
Inner disk filesystem type for disk volumes. None for directory volumes.
fn disk_path(&self) -> Option<PathBuf>
Host path to the managed raw disk image (disk.raw) for local disk volumes. None otherwise.
fn labels(&self) -> &[(String, String)]
Key-value labels for organizing and filtering volumes.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">&[(String, String)]</span></div> <div className="msb-param-desc">Label pairs.</div> </div> </div>fn created_at(&self) -> Option<DateTime<Utc>>
When this volume was first created, if recorded.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">Option<DateTime<Utc>></span></div> <div className="msb-param-desc">Creation timestamp, or <code>None</code>.</div> </div> </div>fn backend_kind(&self) -> BackendKind
Which backend variant this handle is bound to: Local or Cloud.
fn local(&self) -> Option<&VolumeHandleLocalState>
Local-only handle state. Returns Some for local-backed handles, None for cloud-backed ones.
<Tooltip tip="Returns state only for cloud-backed volume handles; None on the local backend."><span className="msb-badge-cloud">Cloud-only <Icon icon="circle-info" size={11} /></span></Tooltip>
fn cloud(&self) -> Option<&VolumeHandleCloudState>
Cloud-only handle state. Returns Some for cloud-backed handles, None for local-backed ones.
Host-side filesystem operations for a named volume.
<Tooltip tip="Unmounted-volume filesystem access is not available on microsandbox cloud; mount the volume into a sandbox and use the sandbox filesystem."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
async fn read(&self, path: &str) -> MicrosandboxResult<Bytes>
let data = vol.fs().read("/seed.txt").await?;
Read an entire file into memory as raw bytes.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">&str</span></div> <div className="msb-param-desc">File path relative to the volume root.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">Bytes</span></div> <div className="msb-param-desc">File contents.</div> </div> </div><Tooltip tip="Unmounted-volume filesystem access is not available on microsandbox cloud; mount the volume into a sandbox and use the sandbox filesystem."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
async fn read_to_string(&self, path: &str) -> MicrosandboxResult<String>
let text = vol.fs().read_to_string("/seed.txt").await?;
Read an entire file into memory as a UTF-8 string.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">&str</span></div> <div className="msb-param-desc">File path relative to the volume root.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">String</span></div> <div className="msb-param-desc">File contents as UTF-8.</div> </div> </div><Tooltip tip="Unmounted-volume filesystem access is not available on microsandbox cloud; mount the volume into a sandbox and use the sandbox filesystem."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
async fn read_stream(&self, path: &str) -> MicrosandboxResult<VolumeFsReadStream>
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.
<Tooltip tip="Unmounted-volume filesystem access is not available on microsandbox cloud; mount the volume into a sandbox and use the sandbox filesystem."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
async fn write(&self, path: &str, data: impl AsRef<[u8]>) -> MicrosandboxResult<()>
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">&str</span></div> <div className="msb-param-desc">File path relative to the volume root.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>data</code><span className="msb-type">impl AsRef<[u8]></span></div> <div className="msb-param-desc">Bytes to write.</div> </div> </div><Tooltip tip="Unmounted-volume filesystem access is not available on microsandbox cloud; mount the volume into a sandbox and use the sandbox filesystem."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
async fn write_stream(&self, path: &str) -> MicrosandboxResult<VolumeFsWriteSink>
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.
async fn list(&self, path: &str) -> MicrosandboxResult<Vec<FsEntry>>
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">&str</span></div> <div className="msb-param-desc">Directory path relative to the volume root.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="/sdk/rust/filesystem#fsentry">Vec<FsEntry></a></div> <div className="msb-param-desc">Directory entries.</div> </div> </div>async fn mkdir(&self, path: &str) -> MicrosandboxResult<()>
vol.fs().mkdir("/data/incoming").await?;
Create a directory and any missing parents.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">&str</span></div> <div className="msb-param-desc">Directory path relative to the volume root.</div> </div> </div>async fn remove(&self, path: &str) -> MicrosandboxResult<()>
vol.fs().remove("/data/stale.tmp").await?;
Delete a single file. Use remove_dir() for directories.
async fn remove_dir(&self, path: &str) -> MicrosandboxResult<()>
vol.fs().remove_dir("/data/incoming").await?;
Remove a directory and its contents recursively. Targeting the volume root is rejected.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">&str</span></div> <div className="msb-param-desc">Directory path relative to the volume root.</div> </div> </div>async fn copy(&self, from: &str, to: &str) -> MicrosandboxResult<()>
vol.fs().copy("/seed.txt", "/backup/seed.txt").await?;
Copy a file within the volume. Creates the destination's parent directories as needed.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>from</code><span className="msb-type">&str</span></div> <div className="msb-param-desc">Source path relative to the volume root.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>to</code><span className="msb-type">&str</span></div> <div className="msb-param-desc">Destination path relative to the volume root.</div> </div> </div>async fn rename(&self, from: &str, to: &str) -> MicrosandboxResult<()>
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>from</code><span className="msb-type">&str</span></div> <div className="msb-param-desc">Source path relative to the volume root.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>to</code><span className="msb-type">&str</span></div> <div className="msb-param-desc">Destination path relative to the volume root.</div> </div> </div>async fn stat(&self, path: &str) -> MicrosandboxResult<FsMetadata>
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">&str</span></div> <div className="msb-param-desc">Path relative to the volume root.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="/sdk/rust/filesystem#fsmetadata">FsMetadata</a></div> <div className="msb-param-desc">Entry metadata.</div> </div> </div>async fn exists(&self, path: &str) -> MicrosandboxResult<bool>
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.
Builder for configuring a named volume.
fn directory(self) -> Self
Create a directory-backed named volume (mounted through virtiofs). This is the default.
<Tooltip tip="Disk-kind volumes are not available on microsandbox cloud; use a directory-backed named volume."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
fn disk(self) -> Self
Create a raw ext4 disk-image named volume (mounted through virtio-blk). Requires .size().
<Tooltip tip="Disk-kind volumes are not available on microsandbox cloud; use a directory-backed named volume."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
fn size(self, size: impl Into<Mebibytes>) -> Self
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().
<Tooltip tip="On microsandbox cloud, quota sets a storage cap and must be a whole number of GiB."><span className="msb-badge-note">On cloud <Icon icon="circle-info" size={11} /></span></Tooltip>
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().
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>key</code><span className="msb-type">impl Into<String></span></div> <div className="msb-param-desc">Label key.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>value</code><span className="msb-type">impl Into<String></span></div> <div className="msb-param-desc">Label value.</div> </div> </div><a id="vb-build"></a>
fn build(self) -> VolumeConfig
Materialize the VolumeConfig without creating the volume. Pass the result to Volume::create() to provision it later.
<a id="vb-create"></a>
async fn create(self) -> MicrosandboxResult<Volume>
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()).
Builder for configuring a sandbox volume mount.
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 ;.
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().
<Tooltip tip="On microsandbox cloud, create the named volume before mounting; create-on-mount, disk-kind, and size are not available."><span className="msb-badge-limited">Limited on cloud <Icon icon="circle-info" size={11} /></span></Tooltip>
fn named_with(
self,
name: impl Into<String>,
f: impl FnOnce(NamedVolumeBuilder) -> NamedVolumeBuilder,
) -> Self
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.
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().
<Tooltip tip="On microsandbox cloud, the disk-image path resolves against your organization's host volume, not the computer running the SDK or CLI."><span className="msb-badge-note">On cloud <Icon icon="circle-info" size={11} /></span></Tooltip>
<a id="mb-disk"></a>
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().
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.
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().
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).
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.
fn nosuid(self) -> Self
Ignore setuid and setgid privilege elevation from files on this mount.
fn nodev(self) -> Self
Ignore device files on this mount.
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.
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.
<a id="mb-size"></a>
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.
<a id="mb-build"></a>
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.
Sub-builder for MountBuilder::named_with(). Selects sandbox-time existence behavior and creation metadata.
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.
<a id="nv-existing"></a>
fn existing(self) -> Self
Require the named volume to already exist. This is the default.
<a id="nv-create"></a>
fn create(self) -> Self
Create the named volume at sandbox launch and fail if it already exists.
<a id="nv-ensure_exists"></a>
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.
<a id="nv-name"></a>
fn name(self, name: impl Into<String>) -> Self
Override the volume name passed to named_with().
<a id="nv-directory"></a>
fn directory(self) -> Self
Use directory-backed storage for a created volume. This is the default. Clears any previously set disk capacity.
<Tooltip tip="Disk-kind volumes are not available on microsandbox cloud; use a directory-backed named volume."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
<a id="nv-disk"></a>
fn disk(self) -> Self
Use raw ext4 disk-image storage for a created volume. Requires .size(). Clears any previously set quota.
<Tooltip tip="Disk-kind volumes are not available on microsandbox cloud; use a directory-backed named volume."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
<a id="nv-size"></a>
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.
<Tooltip tip="On microsandbox cloud, quota sets a storage cap and must be a whole number of GiB."><span className="msb-badge-note">On cloud <Icon icon="circle-info" size={11} /></span></Tooltip>
<a id="nv-quota"></a>
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.
<a id="nv-label"></a>
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.
A streaming reader for file data from a local volume directory. Returned by VolumeFs::read_stream().
recv()
Next chunk; None at EOF
Option<Bytes>
collect()
Read the rest into one buffer
<p className="msb-label">Returns</p>Bytes
A streaming writer for file data to a local volume directory. Returned by VolumeFs::write_stream().
write(data)
Append a chunk
close()
Flush and close
Storage kind for a named volume.
<p className="msb-backref">Returned by <a href="#vol-kind">Volume::kind()</a> · <a href="#h-kind">VolumeHandle::kind()</a></p>| Variant | Description |
|---|---|
Directory | Directory-backed volume mounted through virtiofs |
Disk | Raw ext4 disk-image volume mounted through virtio-blk |
Configuration for creating a named volume. Re-exported as both VolumeSpec and the alias VolumeConfig.
| 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 |
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 |
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 |
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 |
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) |
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 |