Skip to main content
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
NameTypeDescription
nameimpl Into<String>Volume name (e.g. "pip-cache")
Returns
TypeDescription
VolumeBuilderBuilder with .quota() and .create()

​
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
NameTypeDescription
name&strVolume name
Returns
TypeDescription
VolumeHandleHandle for host-side operations

​
Volume::list()

async fn list() -> MicrosandboxResult<Vec<VolumeHandle>>
List all named volumes. Returns
TypeDescription
Vec<VolumeHandle>All volume handles

​
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
NameTypeDescription
name&strVolume name

​
VolumeBuilder

Builder for creating a named volume.

​
create()

async fn create(self) -> MicrosandboxResult<Volume>
Create the volume on disk. Returns
TypeDescription
VolumeThe created volume

​
quota()

fn quota(self, mib: u64) -> Self
Set the maximum storage size for this volume. The guest cannot write beyond this limit. Parameters
NameTypeDescription
mibu64Quota in MiB

​
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
NameTypeDescription
host_pathimpl Into<PathBuf>Directory path on the host

​
named()

fn named(self, name: impl Into<String>) -> Self
Mount a named volume. The volume must already exist (create it with Volume::builder()). Parameters
NameTypeDescription
nameimpl Into<String>Volume name

​
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
NameTypeDescription
mibimpl Into<Mebibytes>Size limit in MiB

​
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.
Property / MethodTypeDescription
fs()VolumeFsHandleHost-side filesystem access - read and write files without a running sandbox
name()&strVolume name
remove()()Delete this volume from disk