Volumes

See Volumes for usage examples and patterns.

Volume

Named volumes are managed by microsandbox and stored at ~/.microsandbox/volumes/<name>/. They persist independently of any sandbox.

Volume::builder()

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

Create a builder for a new named volume. Call .quota() to set a storage limit, then .create() to finalize.

Parameters

Returns

Volume::get()

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 or to delete it.

Parameters

Returns

Volume::list()

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

List all named volumes.

Returns

Volume::remove()

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

Delete a named volume and its contents from disk. Fails if the volume is currently mounted by a running sandbox.

Parameters

VolumeBuilder

Builder for creating a named volume.

create()

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

Create the volume on disk.

Returns

quota()

fn quota(self, mib: u64) -> Self

Set the maximum storage size for this volume. The guest cannot write beyond this limit.

Parameters

MountBuilder

Builder for configuring a volume mount. Used in SandboxBuilder::volume(path, |v| v...).

bind()

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

Mount a host directory into the sandbox. Changes in the guest are reflected on the host and vice versa.

Parameters

named()

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

Mount a named volume. The volume must already exist (create it with Volume::builder()).

Parameters

readonly()

fn readonly(self) -> Self

Mount as read-only. The guest can read but not write.

size()

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

Set the size limit for a tmpfs mount. Has no effect on bind or named mounts.

Parameters

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.

Types

VolumeHandle

Handle for interacting with a named volume from the host side.