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.

​
Static methods

​
Volume.create()

async def Volume.create(
    name: str,
    *,
    quota_mib: int | None = None,
    labels: dict[str, str] | None = None,
) -> Volume
Create a new named volume. Parameters
NameTypeDescription
namestrVolume name (required)
quota_mibint | NoneMaximum storage size in MiB
labelsdict[str, str] | NoneMetadata labels
Returns
TypeDescription
VolumeCreated volume with name and path properties

​
Volume.get()

async def Volume.get(name: str) -> VolumeHandle
Get a handle to an existing named volume. Parameters
NameTypeDescription
namestrVolume name
Returns
TypeDescription
VolumeHandleVolume handle

​
Volume.list()

async def Volume.list() -> list[VolumeHandle]
List all named volumes. Returns
TypeDescription
list[VolumeHandle]All volumes

​
Volume.remove()

async def Volume.remove(name: str) -> None
Delete a named volume and its contents. Fails if the volume is currently mounted. Parameters
NameTypeDescription
namestrVolume name

​
Volume instance properties

PropertyTypeDescription
namestrVolume name
pathstrHost path to the volume directory

​
Mount config factories

Static factory methods on Volume for creating mount configurations used in sandbox volume config.

​
Volume.bind()

def Volume.bind(path: str, *, readonly: bool = False) -> dict
Mount a host directory into the sandbox. Changes in the guest are reflected on the host and vice versa. Parameters
NameTypeDescription
pathstrDirectory path on the host
readonlyboolMount as read-only
Returns
TypeDescription
dictMount configuration dictionary

​
Volume.named()

def Volume.named(name: str, *, readonly: bool = False) -> dict
Mount a named volume. The volume must already exist (create it with Volume.create()). Parameters
NameTypeDescription
namestrVolume name
readonlyboolMount as read-only
Returns
TypeDescription
dictMount configuration dictionary

​
Volume.tmpfs()

def Volume.tmpfs(*, size_mib: int | None = None, readonly: bool = False) -> dict
Use an in-memory filesystem. Contents are discarded when the sandbox stops. Parameters
NameTypeDescription
size_mibint | NoneMaximum size in MiB
readonlyboolMount as read-only
Returns
TypeDescription
dictMount configuration dictionary

​
VolumeHandle

Handle to an existing named volume, returned by Volume.get() and Volume.list().
Property / MethodTypeDescription
namestrVolume name
quota_mibint | NoneStorage quota in MiB
used_bytesintCurrent disk usage in bytes
labelsdict[str, str]Metadata labels
created_atfloat | NoneCreation timestamp (ms since epoch)
fsVolumeFsHost-side filesystem handle
remove()(async) NoneDelete this volume

​
VolumeFs

Host-side filesystem operations on a named volume. Obtained via the fs property on VolumeHandle. These operations run directly on the host filesystem - no running sandbox is required.

​
read()

async def read(path: str) -> bytes
Read the entire contents of a file as raw bytes. Parameters
NameTypeDescription
pathstrPath relative to the volume root
Returns
TypeDescription
bytesFile contents as raw bytes

​
read_text()

async def read_text(path: str) -> str
Read the entire contents of a file and decode as UTF-8. Parameters
NameTypeDescription
pathstrPath relative to the volume root
Returns
TypeDescription
strFile contents as a string

​
write()

async def write(path: str, data: bytes) -> None
Write content to a file, creating it if it doesn’t exist and overwriting if it does. Parameters
NameTypeDescription
pathstrPath relative to the volume root
databytesFile content

​
list()

async def list(path: str) -> list[FsEntry]
List the entries in a directory. Parameters
NameTypeDescription
pathstrPath relative to the volume root
Returns
TypeDescription
list[FsEntry]Directory entries

​
mkdir()

async def mkdir(path: str) -> None
Create a directory and all parent directories. Parameters
NameTypeDescription
pathstrPath relative to the volume root

​
remove_file()

async def remove_file(path: str) -> None
Remove a file. Parameters
NameTypeDescription
pathstrPath relative to the volume root

​
exists()

async def exists(path: str) -> bool
Check whether a path exists within the volume. Parameters
NameTypeDescription
pathstrPath relative to the volume root
Returns
TypeDescription
boolTrue if the path exists

​
Types

​
MountConfig

Frozen dataclass representing a mount configuration. 
MountConfig(
    kind: MountKind,
    bind: str | None = None,
    named: str | None = None,
    size_mib: int | None = None,
    readonly: bool = False,
)
FieldTypeDefaultDescription
kindMountKind-Type of mount (required)
bindstr | NoneNoneHost path for bind mounts
namedstr | NoneNoneVolume name for named mounts
size_mibint | NoneNoneSize limit for tmpfs mounts
readonlyboolFalseWhether the mount is read-only

​
MountKind

String enum representing the type of mount.
ValueDescription
"bind"Host bind mount
"named"Named volume mount
"tmpfs"In-memory filesystem