docs/sdk/rust/volumes.mdx
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 for usage examples and patterns.
<div className="msb-glance"> <p className="msb-gl"><span className="msb-dot static"></span>Static · Volume<span className="msb-ct">5</span></p> <a className="msb-row" href="#volumebuilder"><span className="msb-rn">Volume::builder()</span><span className="msb-rg">configure a new volume</span></a> <a className="msb-row" href="#volumecreate"><span className="msb-rn">Volume::create()</span><span className="msb-rg">provision from a config</span></a> <a className="msb-row" href="#volumeget"><span className="msb-rn">Volume::get()</span><span className="msb-rg">handle to an existing one</span></a> <a className="msb-row" href="#volumelist"><span className="msb-rn">Volume::list()</span><span className="msb-rg">all volumes</span></a> <a className="msb-row" href="#volumeremove"><span className="msb-rn">Volume::remove()</span><span className="msb-rg">delete by name</span></a> <p className="msb-gl"><span className="msb-dot instance"></span>Instance · Volume<span className="msb-ct">11</span></p> <a className="msb-row" href="#vol-name"><span className="msb-rn">vol.name()</span><span className="msb-rg">volume name</span></a> <a className="msb-row" href="#vol-kind"><span className="msb-rn">vol.kind()</span><span className="msb-rg">directory or disk</span></a> <a className="msb-row" href="#vol-fs"><span className="msb-rn">vol.fs()</span><span className="msb-rg">read / write files</span></a> <a className="msb-row" href="#vol-path"><span className="msb-rn">vol.path()</span><span className="msb-rg">host data directory</span></a> <a className="msb-row" href="#vol-disk_path"><span className="msb-rn">vol.disk_path()</span><span className="msb-rg">host disk image path</span></a> <a className="msb-row" href="#vol-capacity_bytes"><span className="msb-rn">vol.capacity_bytes()</span><span className="msb-rg">disk capacity</span></a> <a className="msb-row" href="#vol-disk_format"><span className="msb-rn">vol.disk_format()</span><span className="msb-rg">disk image format</span></a> <a className="msb-row" href="#vol-disk_fstype"><span className="msb-rn">vol.disk_fstype()</span><span className="msb-rg">inner disk filesystem</span></a> <a className="msb-row" href="#vol-backend_kind"><span className="msb-rn">vol.backend_kind()</span><span className="msb-rg">local or cloud</span></a> <a className="msb-row" href="#vol-local"><span className="msb-rn">vol.local()</span><span className="msb-rg">local-only state</span></a> <a className="msb-row" href="#vol-cloud"><span className="msb-rn">vol.cloud()</span><span className="msb-rg">cloud-only state</span></a> <p className="msb-gl"><span className="msb-dot instance"></span>Instance · VolumeHandle<span className="msb-ct">15</span></p> <a className="msb-row" href="#h-name"><span className="msb-rn">h.name()</span><span className="msb-rg">volume name</span></a> <a className="msb-row" href="#h-kind"><span className="msb-rn">h.kind()</span><span className="msb-rg">directory or disk</span></a> <a className="msb-row" href="#h-fs"><span className="msb-rn">h.fs()</span><span className="msb-rg">read / write files</span></a> <a className="msb-row" href="#h-remove"><span className="msb-rn">h.remove()</span><span className="msb-rg">delete this volume</span></a> <a className="msb-row" href="#h-used_bytes"><span className="msb-rn">h.used_bytes()</span><span className="msb-rg">usage snapshot</span></a> <a className="msb-row" href="#h-quota_mib"><span className="msb-rn">h.quota_mib()</span><span className="msb-rg">storage quota</span></a> <a className="msb-row" href="#h-capacity_bytes"><span className="msb-rn">h.capacity_bytes()</span><span className="msb-rg">disk capacity</span></a> <a className="msb-row" href="#h-disk_format"><span className="msb-rn">h.disk_format()</span><span className="msb-rg">disk image format</span></a> <a className="msb-row" href="#h-disk_fstype"><span className="msb-rn">h.disk_fstype()</span><span className="msb-rg">inner disk filesystem</span></a> <a className="msb-row" href="#h-disk_path"><span className="msb-rn">h.disk_path()</span><span className="msb-rg">host disk image path</span></a> <a className="msb-row" href="#h-labels"><span className="msb-rn">h.labels()</span><span className="msb-rg">key-value labels</span></a> <a className="msb-row" href="#h-created_at"><span className="msb-rn">h.created_at()</span><span className="msb-rg">creation time</span></a> <a className="msb-row" href="#h-backend_kind"><span className="msb-rn">h.backend_kind()</span><span className="msb-rg">local or cloud</span></a> <a className="msb-row" href="#h-local"><span className="msb-rn">h.local()</span><span className="msb-rg">local-only state</span></a> <a className="msb-row" href="#h-cloud"><span className="msb-rn">h.cloud()</span><span className="msb-rg">cloud-only state</span></a> <p className="msb-gl"><span className="msb-dot instance"></span>Instance · VolumeFs<span className="msb-ct">13</span></p> <a className="msb-row" href="#fs-read"><span className="msb-rn">fs.read()</span><span className="msb-rg">read bytes</span></a> <a className="msb-row" href="#fs-read_to_string"><span className="msb-rn">fs.read_to_string()</span><span className="msb-rg">read UTF-8 text</span></a> <a className="msb-row" href="#fs-read_stream"><span className="msb-rn">fs.read_stream()</span><span className="msb-rg">stream a file in</span></a> <a className="msb-row" href="#fs-write"><span className="msb-rn">fs.write()</span><span className="msb-rg">write bytes</span></a> <a className="msb-row" href="#fs-write_stream"><span className="msb-rn">fs.write_stream()</span><span className="msb-rg">stream a file out</span></a> <a className="msb-row" href="#fs-list"><span className="msb-rn">fs.list()</span><span className="msb-rg">list a directory</span></a> <a className="msb-row" href="#fs-mkdir"><span className="msb-rn">fs.mkdir()</span><span className="msb-rg">create a directory</span></a> <a className="msb-row" href="#fs-remove"><span className="msb-rn">fs.remove()</span><span className="msb-rg">delete a file</span></a> <a className="msb-row" href="#fs-remove_dir"><span className="msb-rn">fs.remove_dir()</span><span className="msb-rg">delete a directory</span></a> <a className="msb-row" href="#fs-copy"><span className="msb-rn">fs.copy()</span><span className="msb-rg">copy a file</span></a> <a className="msb-row" href="#fs-rename"><span className="msb-rn">fs.rename()</span><span className="msb-rg">rename / move</span></a> <a className="msb-row" href="#fs-stat"><span className="msb-rn">fs.stat()</span><span className="msb-rg">metadata</span></a> <a className="msb-row" href="#fs-exists"><span className="msb-rn">fs.exists()</span><span className="msb-rg">existence check</span></a> <p className="msb-gl"><span className="msb-dot builder"></span>Builder · VolumeBuilder<span className="msb-ct">7</span></p> <div className="msb-chiprow"> <a className="msb-chip" href="#directory">.directory()</a> <a className="msb-chip" href="#disk">.disk()</a> <a className="msb-chip" href="#size">.size()</a> <a className="msb-chip" href="#quota">.quota()</a> <a className="msb-chip" href="#label">.label()</a> <a className="msb-chip" href="#vb-build">.build()</a> <a className="msb-chip" href="#vb-create">.create()</a> </div> <p className="msb-gl"><span className="msb-dot builder"></span>Builder · MountBuilder<span className="msb-ct">15</span></p> <div className="msb-chiprow"> <a className="msb-chip" href="#bind">.bind()</a> <a className="msb-chip" href="#named">.named()</a> <a className="msb-chip" href="#named_with">.named_with()</a> <a className="msb-chip" href="#tmpfs">.tmpfs()</a> <a className="msb-chip" href="#mb-disk">.disk()</a> <a className="msb-chip" href="#format">.format()</a> <a className="msb-chip" href="#fstype">.fstype()</a> <a className="msb-chip" href="#readonly">.readonly()</a> <a className="msb-chip" href="#noexec">.noexec()</a> <a className="msb-chip" href="#nosuid">.nosuid()</a> <a className="msb-chip" href="#nodev">.nodev()</a> <a className="msb-chip" href="#stat_virtualization">.stat_virtualization()</a> <a className="msb-chip" href="#host_permissions">.host_permissions()</a> <a className="msb-chip" href="#mb-size">.size()</a> <a className="msb-chip" href="#mb-build">.build()</a> </div> <p className="msb-gl"><span className="msb-dot builder"></span>Builder · NamedVolumeBuilder<span className="msb-ct">9</span></p> <div className="msb-chiprow"> <a className="msb-chip" href="#nv-existing">.existing()</a> <a className="msb-chip" href="#nv-create">.create()</a> <a className="msb-chip" href="#nv-ensure_exists">.ensure_exists()</a> <a className="msb-chip" href="#nv-name">.name()</a> <a className="msb-chip" href="#nv-directory">.directory()</a> <a className="msb-chip" href="#nv-disk">.disk()</a> <a className="msb-chip" href="#nv-size">.size()</a> <a className="msb-chip" href="#nv-quota">.quota()</a> <a className="msb-chip" href="#nv-label">.label()</a> </div> <p className="msb-gl"><span className="msb-dot type"></span>Types</p> <div className="msb-chiprow"> <a className="msb-typepill" href="#volume">Volume</a> <a className="msb-typepill" href="#volumehandle">VolumeHandle</a> <a className="msb-typepill" href="#volumebuilder-2">VolumeBuilder</a> <a className="msb-typepill" href="#volumefs">VolumeFs</a> <a className="msb-typepill" href="#volumefsreadstream">VolumeFsReadStream</a> <a className="msb-typepill" href="#volumefswritesink">VolumeFsWriteSink</a> <a className="msb-typepill" href="#mountbuilder-2">MountBuilder</a> <a className="msb-typepill" href="#namedvolumebuilder-2">NamedVolumeBuilder</a> <a className="msb-typepill" href="#volumekind">VolumeKind</a> <a className="msb-typepill" href="#volumespec">VolumeSpec</a> <a className="msb-typepill" href="#mountoptions">MountOptions</a> <a className="msb-typepill" href="#statvirtualization">StatVirtualization</a> <a className="msb-typepill" href="#hostpermissions">HostPermissions</a> <a className="msb-typepill" href="#diskimageformat">DiskImageFormat</a> <a className="msb-typepill" href="#namedvolumemode">NamedVolumeMode</a> <a className="msb-typepill" href="/sdk/rust/filesystem#fsentry">FsEntry</a> <a className="msb-typepill" href="/sdk/rust/filesystem#fsmetadata">FsMetadata</a> </div> </div> <p className="msb-label" id="typical-flow">Typical flow</p>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?;
fn builder(name: impl Into<String>) -> VolumeBuilder
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.
let vol = Volume::builder("pip-cache").create().await?;
async fn create(config: VolumeConfig) -> MicrosandboxResult<Volume>
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.
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?;
async fn get(name: &str) -> MicrosandboxResult<VolumeHandle>
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.
let h = Volume::get("pip-cache").await?;
println!("{} — {} bytes used", h.name(), h.used_bytes());
async fn list() -> MicrosandboxResult<Vec<VolumeHandle>>
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> <Accordion title="Example">for h in Volume::list().await? {
println!("{} — {:?}", h.name(), h.kind());
}
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.
Volume::remove("pip-cache").await?;
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.
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 for the operations.
vol.fs().write("/seed.txt", "hello").await?;
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.
println!("{}", vol.path()?.display());
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.
fn cloud(&self) -> Option<&VolumeCloudState>
Cloud-only volume state. Returns Some for cloud-backed volumes, None for local-backed ones.
A lightweight handle returned by Volume::get() and Volume::list(). Exposes metadata captured at read time plus filesystem and delete operations, without holding a live 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.
fn fs(&self) -> VolumeFs<'_>
Get a filesystem handle for reading and writing the volume's files directly, without a running sandbox. See VolumeFs.
let h = Volume::get("pip-cache").await?;
let names = h.fs().list("/").await?;
async fn remove(&self) -> MicrosandboxResult<()>
Delete this volume and its contents. Locally the database record is removed first, then the directory.
<Accordion title="Example">Volume::get("pip-cache").await?.remove().await?;
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.
fn cloud(&self) -> Option<&VolumeHandleCloudState>
Cloud-only handle state. Returns Some for cloud-backed handles, None for local-backed ones.
Host-side filesystem operations on a named volume, obtained via Volume::fs() or VolumeHandle::fs(). Unlike SandboxFs, 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.
async fn read(&self, path: &str) -> MicrosandboxResult<Bytes>
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> <Accordion title="Example">let data = vol.fs().read("/seed.txt").await?;
async fn read_to_string(&self, path: &str) -> MicrosandboxResult<String>
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> <Accordion title="Example">let text = vol.fs().read_to_string("/seed.txt").await?;
async fn read_stream(&self, path: &str) -> MicrosandboxResult<VolumeFsReadStream>
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.
let mut stream = vol.fs().read_stream("/model.bin").await?;
while let Some(chunk) = stream.recv().await? {
// process chunk
}
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.
<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> <Accordion title="Example">vol.fs().write("/config/app.json", r#"{"ready":true}"#).await?;
async fn write_stream(&self, path: &str) -> MicrosandboxResult<VolumeFsWriteSink>
Open a file for streaming writes. Returns a VolumeFsWriteSink that accepts chunks of bytes. Creates parent directories as needed.
let mut sink = vol.fs().write_stream("/upload.bin").await?;
sink.write(&chunk).await?;
sink.close().await?;
async fn list(&self, path: &str) -> MicrosandboxResult<Vec<FsEntry>>
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> <Accordion title="Example">for entry in vol.fs().list("/").await? {
println!("{} ({} bytes)", entry.path, entry.size);
}
async fn mkdir(&self, path: &str) -> MicrosandboxResult<()>
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> <Accordion title="Example">vol.fs().mkdir("/data/incoming").await?;
async fn remove(&self, path: &str) -> MicrosandboxResult<()>
Delete a single file. Use remove_dir() for directories.
vol.fs().remove("/data/stale.tmp").await?;
async fn remove_dir(&self, path: &str) -> MicrosandboxResult<()>
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> <Accordion title="Example">vol.fs().remove_dir("/data/incoming").await?;
async fn copy(&self, from: &str, to: &str) -> MicrosandboxResult<()>
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> <Accordion title="Example">vol.fs().copy("/seed.txt", "/backup/seed.txt").await?;
async fn rename(&self, from: &str, to: &str) -> MicrosandboxResult<()>
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> <Accordion title="Example">vol.fs().rename("/tmp/out.txt", "/done/out.txt").await?;
async fn stat(&self, path: &str) -> MicrosandboxResult<FsMetadata>
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> <Accordion title="Example">let meta = vol.fs().stat("/seed.txt").await?;
println!("{} bytes", meta.size);
async fn exists(&self, path: &str) -> MicrosandboxResult<bool>
Check whether a file or directory exists at the given path. Returns false rather than an error if the path is absent.
if !vol.fs().exists("/seed.txt").await? {
vol.fs().write("/seed.txt", "hello").await?;
}
Builder for configuring a named volume before creation. Obtained via Volume::builder(name). Directory-backed is the default; disk volumes require .disk() plus .size(). Every setter returns Self, so calls chain.
fn directory(self) -> Self
Create a directory-backed named volume (mounted through virtiofs). This is the default.
fn disk(self) -> Self
Create a raw ext4 disk-image named volume (mounted through virtio-blk). Requires .size().
fn size(self, size: impl Into<Mebibytes>) -> 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().
use microsandbox::size::SizeExt;
let vol = Volume::builder("docker-data")
.disk()
.size(20.gib())
.create()
.await?;
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>
Create the volume on the active backend. Equivalent to Volume::create(self.build()).
let vol = Volume::builder("pip-cache")
.quota(1024)
.label("team", "ml")
.create()
.await?;
Builder for configuring a volume mount on a sandbox. Used in SandboxBuilder::volume(guest_path, |v| v...) (see .volume()). Pick exactly one mount kind: .bind(), .named() / .named_with(), .tmpfs(), or .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.
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().
fn named_with(
self,
name: impl Into<String>,
f: impl FnOnce(NamedVolumeBuilder) -> NamedVolumeBuilder,
) -> Self
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.
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?;
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().
<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 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.
<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.
<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.
<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 live named volume, carrying the backend it was created on. Returned by Volume::create() and VolumeBuilder::create().
| Method | Returns | Description |
|---|---|---|
name() | &str | Volume name |
kind() | VolumeKind | Directory or disk |
fs() | VolumeFs | Host-side filesystem handle |
path() | MicrosandboxResult<&Path> | Host data directory (local only) |
disk_path() | Option<PathBuf> | Host disk.raw path for disk volumes |
capacity_bytes() | Option<u64> | Disk capacity in bytes |
disk_format() | Option<&str> | Disk image format |
disk_fstype() | Option<&str> | Inner disk filesystem |
backend_kind() | BackendKind | Local or cloud |
local() | Option<&VolumeLocalState> | Local-only state |
cloud() | Option<&VolumeCloudState> | Cloud-only state |
A lightweight handle to a volume, exposing metadata plus filesystem and delete operations without a live Volume.
| Method | Returns | Description |
|---|---|---|
name() | &str | Volume name |
kind() | VolumeKind | Directory or disk |
fs() | VolumeFs | Host-side filesystem handle |
remove() | MicrosandboxResult<()> | Delete this volume |
used_bytes() | u64 | Usage snapshot at read time |
quota_mib() | Option<u32> | Storage quota in MiB |
capacity_bytes() | Option<u64> | Disk capacity in bytes |
disk_format() | Option<&str> | Disk image format |
disk_fstype() | Option<&str> | Inner disk filesystem |
disk_path() | Option<PathBuf> | Host disk.raw path |
labels() | &[(String, String)] | Key-value labels |
created_at() | Option<DateTime<Utc>> | Creation time |
backend_kind() | BackendKind | Local or cloud |
local() | Option<&VolumeHandleLocalState> | Local-only state |
cloud() | Option<&VolumeHandleCloudState> | Cloud-only state |
Builder for configuring a named volume before creation. Implements From<VolumeConfig>.
| Method | Returns | Description |
|---|---|---|
directory() | Self | Directory-backed (default) |
disk() | Self | Raw ext4 disk-image volume |
size() | Self | Disk capacity (required for disk) |
quota() | Self | Directory storage quota |
label() | Self | Attach a label |
build() | VolumeConfig | Materialize config |
create() | Volume | Create the volume |
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<'_>).
| Method | Returns | Description |
|---|---|---|
read() | Bytes | Read bytes |
read_to_string() | String | Read UTF-8 text |
read_stream() | VolumeFsReadStream | Stream a file in |
write() | () | Write bytes |
write_stream() | VolumeFsWriteSink | Stream a file out |
list() | Vec<FsEntry> | List a directory |
mkdir() | () | Create a directory |
remove() | () | Delete a file |
remove_dir() | () | Delete a directory recursively |
copy() | () | Copy a file |
rename() | () | Rename / move |
stat() | FsMetadata | Metadata |
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().
A streaming reader for file data from a local volume directory. Returned by VolumeFs::read_stream().
| Method | Returns | Description |
|---|---|---|
recv() | Option<Bytes> | Next chunk; None at EOF |
collect() | Bytes | Read the rest into one buffer |
A streaming writer for file data to a local volume directory. Returned by VolumeFs::write_stream().
| Method | Returns | Description |
|---|---|---|
write(data) | () | Append a chunk |
close() | () | Flush and close |
Builder for a sandbox volume mount, used in SandboxBuilder::volume. Builds a VolumeMount.
| Method | Returns | Description |
|---|---|---|
bind() | Self | Bind a host directory |
named() | Self | Mount an existing named volume |
named_with() | Self | Mount with sandbox-time provisioning |
tmpfs() | Self | In-memory filesystem |
disk() | Self | Host disk image as virtio-blk |
format() | Self | Disk image format (disk only) |
fstype() | Self | Inner filesystem type (disk only) |
readonly() | Self | Block writes |
noexec() | Self | Block direct execution |
nosuid() | Self | Ignore setuid/setgid |
nodev() | Self | Ignore device files |
stat_virtualization() | Self | Stat virtualization policy (virtiofs) |
host_permissions() | Self | Host permission policy (virtiofs) |
size() | Self | tmpfs size limit |
build() | MicrosandboxResult<VolumeMount> | Validate and materialize |
Sub-builder for MountBuilder::named_with(). Selects sandbox-time existence behavior and creation metadata.
| Method | Returns | Description |
|---|---|---|
existing() | Self | Require the volume to exist (default) |
create() | Self | Create, fail if it exists |
ensure_exists() | Self | Create if missing, else reuse |
name() | Self | Override the volume name |
directory() | Self | Directory-backed (default) |
disk() | Self | Disk-backed; requires size |
size() | Self | Disk capacity |
quota() | Self | Directory quota |
label() | Self | Attach a label |
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 |