Volumes - microsandbox

Create, manage, and mount named volumes. See Volumes for usage examples.

Volume

Instance properties

volume.name

name: str

Volume name.

volume.path

path: str

Host path to the volume’s directory.

Static methods

Volume.get_default()

async def get_default() -> 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 raises a typed unsupported error; it never substitutes a directory from the caller’s machine.

volume = await Volume.get_default()
await volume.fs().write("customers/acme.json", b'{"active": true}')
print(await volume.fs().read_to_string("customers/acme.json"))

Volume.create()

async def create(
    name: str,
    *,
    kind: VolumeKind = VolumeKind.DIRECTORY,
    size_mib: int | None = None,
    quota_mib: int | None = None,
    labels: dict[str, str] | None = None,
) -> Volume

Example

from microsandbox import VolumeKind

await Volume.create("pip-cache", quota_mib=2048)
await Volume.create("docker-data", kind=VolumeKind.DISK, size_mib=20 * 1024)

Create a new named volume. VolumeKind.DIRECTORY creates a host directory; VolumeKind.DISK creates a backing disk image and requires size_mib.

Parameters

namestr

Volume name.

kindVolumeKind

Volume kind. Defaults to DIRECTORY.

size_mibint | None

Disk capacity in MiB; required with kind=VolumeKind.DISK.

quota_mibint | None

Quota in MiB recorded for directory volumes.

labelsdict[str, str] | None

Metadata labels.

Returns

Volume

Created volume, exposing name and path.

Volume.get()

async def get(name: str) -> VolumeHandle

Example

handle = await Volume.get("pip-cache")
print(handle.kind, handle.used_bytes)

Get a lightweight handle to an existing named volume, with its metadata and a direct filesystem handle.

Parameters

namestr

Volume name.

Returns

VolumeHandle

Handle with metadata and a filesystem accessor.

Volume.list()

async def list() -> list[VolumeHandle]

Example

for v in await Volume.list():
    print(v.name, v.used_bytes)

List all named volumes.

Returns

list[VolumeHandle]

All volume handles.

Volume.remove()

async def remove(name: str) -> None

Example

await Volume.remove("pip-cache")

Delete a named volume and its contents. Fails if the volume is currently mounted.

Parameters

namestr

Volume name.

Mount factories

Static factory methods on Volume that build a MountConfig. Pass the result as a value in the volumes dict when creating a sandbox, keyed by the guest mount point.

Volume.bind()

def bind(
    path: str,
    *,
    readonly: bool = False,
    noexec: bool = False,
    nosuid: bool = False,
    nodev: bool = False,
    stat_virtualization: StatVirtualization | None = None,
    host_permissions: HostPermissions | None = None,
    uid: int | None = None,
    gid: int | None = None,
) -> MountConfig

Example

sb = await Sandbox.create(
    "build",
    image="python",
    volumes={"/src": Volume.bind("/home/me/project", readonly=True)},
)

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

Parameters

pathstr

Directory path on the host.

readonlybool

Mount as read-only; virtiofs-backed mounts also reject writes in the host filesystem server.

noexecbool

Prevent direct execution from the mount.

nosuidbool

Ignore setuid and setgid privilege elevation from files on the mount.

nodevbool

Ignore device files on the mount.

stat_virtualizationStatVirtualization | None

Guest stat-virtualization policy.

host_permissionsHostPermissions | None

Host permission propagation policy.

uidint | None

Guest uid fallback for host files without a per-file stat override; set together with gid.

gidint | None

Guest gid fallback for host files without a per-file stat override; set together with uid.

Returns

MountConfig

Mount configuration.

Volume.named()

def named(
    name: str,
    *,
    mode: NamedVolumeMode | None = None,
    kind: VolumeKind | None = None,
    size_mib: int | None = None,
    quota_mib: int | None = None,
    readonly: bool = False,
    noexec: bool = False,
    nosuid: bool = False,
    nodev: bool = False,
    stat_virtualization: StatVirtualization | None = None,
    host_permissions: HostPermissions | None = None,
    uid: int | None = None,
    gid: int | None = None,
) -> MountConfig

Example

from microsandbox import NamedVolumeMode

sb = await Sandbox.create(
    "worker",
    image="python",
    volumes={
        "/root/.cache/pip": Volume.named("pip-cache"),
        "/etc/config": Volume.named(
            "shared-config",
            mode=NamedVolumeMode.ENSURE_EXISTS,
            readonly=True,
        ),
    },
)

Mount a named volume. By default the volume must already exist; set mode to control creation behavior and use kind, size_mib, and quota_mib when creating it.

Parameters

namestr

Volume name.

modeNamedVolumeMode | None

Whether to require, create, or ensure the named volume.

kindVolumeKind | None

Storage kind when the mount may create the volume.

size_mibint | None

Disk capacity when creating a disk volume.

quota_mibint | None

Quota when creating a directory volume.

readonlybool

Mount as read-only; virtiofs-backed mounts also reject writes in the host filesystem server.

noexecbool

Prevent direct execution from the mount.

nosuidbool

Ignore setuid and setgid privilege elevation from files on the mount.

nodevbool

Ignore device files on the mount.

stat_virtualizationStatVirtualization | None

Guest stat-virtualization policy for a directory-backed volume.

host_permissionsHostPermissions | None

Host permission propagation policy for a directory-backed volume.

uidint | None

Guest uid fallback; set together with gid and use only with directory-backed volumes.

gidint | None

Guest gid fallback; set together with uid and use only with directory-backed volumes.

Returns

MountConfig

Mount configuration.

Volume.tmpfs()

def tmpfs(
    *,
    size_mib: int | None = None,
    readonly: bool = False,
    noexec: bool = False,
    nosuid: bool = False,
    nodev: bool = False,
) -> MountConfig

Example

sb = await Sandbox.create(
    "scratch",
    image="python",
    volumes={"/tmp/work": Volume.tmpfs(size_mib=256)},
)

Use an in-memory filesystem. Contents are discarded when the sandbox stops.

Parameters

size_mibint | None

Maximum size in MiB.

readonlybool

Mount as read-only.

noexecbool

Prevent direct execution from the mount.

nosuidbool

Ignore setuid and setgid privilege elevation from files on the mount.

nodevbool

Ignore device files on the mount.

Returns

MountConfig

Mount configuration.

Volume.disk()

def disk(
    path: str,
    *,
    format: DiskImageFormat | None = None,
    fstype: str | None = None,
    readonly: bool = False,
    noexec: bool = False,
    nosuid: bool = False,
    nodev: bool = False,
) -> MountConfig

Example

sb = await Sandbox.create(
    "db",
    image="postgres",
    volumes={"/var/lib/postgresql": Volume.disk("/data/pg.qcow2", fstype="ext4")},
)

Mount a host disk image as a virtio-blk device. format is the disk image format ("qcow2", "raw", or "vmdk"); when omitted it is inferred from the file extension. fstype (e.g. "ext4") is the inner filesystem agentd mounts; when omitted, agentd probes /proc/filesystems for a type that mounts cleanly.

Parameters

pathstr

Host path to the disk image.

formatDiskImageFormat | None

Disk image format hint. See DiskImageFormat.

fstypestr | None

Inner filesystem type.

readonlybool

Mount as read-only.

noexecbool

Prevent direct execution from the mount.

nosuidbool

Ignore setuid and setgid privilege elevation from files on the mount.

nodevbool

Ignore device files on the mount.

Returns

MountConfig

Mount configuration.

VolumeHandle

Returned by Volume.get(), Volume.list()

A lightweight handle to a named volume, with its database metadata and a host-side filesystem accessor.

handle.name

str Volume name

handle.kind

VolumeKind Volume storage kind

handle.quota_mib

int \| None Storage quota in MiB

handle.used_bytes

int Current disk usage in bytes

handle.capacity_bytes

int \| None Disk capacity in bytes

handle.disk_format

DiskImageFormat \| None Disk image format

handle.disk_fstype

str \| None Disk filesystem type

handle.labels

dict[str, str] Metadata labels

handle.created_at

float \| None Creation timestamp (ms since epoch)

handle.fs

VolumeFs Host-side filesystem handle

handle.remove()

remove()

Delete this volume

Returns

(async) None

VolumeFs

Returned by VolumeHandle.fs

Host-side filesystem operations for a named volume.

fs.read()

async def read(path: str) -> bytes

Example

handle = await Volume.get("pip-cache")
data = await handle.fs.read("index.json")

Read the entire contents of a file as raw bytes.

Parameters

pathstr

Path relative to the volume root.

Returns

bytes

File contents as raw bytes.

fs.read_text()

async def read_text(path: str) -> str

Read the entire contents of a file and decode it as UTF-8.

Parameters

pathstr

Path relative to the volume root.

Returns

str

File contents as a string.

fs.write()

async def write(path: str, data: bytes) -> None

Example

handle = await Volume.get("pip-cache")
await handle.fs.write("seed.txt", b"hello")

Write content to a file, creating it if it doesn’t exist and overwriting if it does.

Parameters

pathstr

Path relative to the volume root.

databytes

File content.

fs.list()

async def list(path: str) -> list[FsEntry]

List the entries in a directory.

Parameters

pathstr

Path relative to the volume root.

Returns

list[FsEntry]

Directory entries.

fs.mkdir()

async def mkdir(path: str) -> None

Create a directory and all parent directories.

Parameters

pathstr

Path relative to the volume root.

fs.remove_file()

async def remove_file(path: str) -> None

Remove a file.

Parameters

pathstr

Path relative to the volume root.

fs.exists()

async def exists(path: str) -> bool

Check whether a path exists within the volume.

Parameters

pathstr

Path relative to the volume root.

Returns

bool

True if the path exists.

Types

MountConfig

Returned by Volume.bind(), Volume.named(), Volume.tmpfs(), Volume.disk()

Frozen dataclass representing a mount configuration. Build one with a mount factory and pass it as a value in the sandbox volumes dict. stat_virtualization, host_permissions, override_uid, and override_gid apply only to virtiofs-backed mounts (BIND and directory-backed NAMED). Owner IDs must be supplied together, must be integers from 0 through 4294967295, and cannot be combined with StatVirtualization.OFF.

Field	Type	Default	Description
kind	`MountKind`	-	Type of mount (required)
bind	`str \| None`	`None`	Host path for bind mounts
named	`str \| None`	`None`	Volume name for named mounts
named_mode	`NamedVolumeMode` `\| None`	`None`	Named-volume creation behavior
named_kind	`VolumeKind` `\| None`	`None`	Storage kind for created named volumes
quota_mib	`int \| None`	`None`	Quota in MiB for directory named volumes
size_mib	`int \| None`	`None`	Size limit for tmpfs, or capacity for disk named volumes
readonly	`bool`	`False`	Whether the mount is read-only
noexec	`bool`	`False`	Whether direct execution from the mount is disabled
nosuid	`bool`	`False`	Whether setuid/setgid privilege elevation is ignored
nodev	`bool`	`False`	Whether device files on the mount are ignored
disk	`str \| None`	`None`	Host path to a disk image for disk mounts
format	`DiskImageFormat` `\| None`	`None`	Disk image format for disk mounts
fstype	`str \| None`	`None`	Inner filesystem type for disk mounts
stat_virtualization	`StatVirtualization` `\| None`	`None`	Per-mount stat-virtualization policy (virtiofs-backed only)
host_permissions	`HostPermissions` `\| None`	`None`	Per-mount host-permission policy (virtiofs-backed only)
override_uid	`int \| None`	`None`	Guest uid fallback for host files without a per-file override; set through factory `uid=` with `gid=`
override_gid	`int \| None`	`None`	Guest gid fallback for host files without a per-file override; set through factory `gid=` with `uid=`

MountKind

Used by MountConfig

String enum (StrEnum) for the type of mount.

Member	Value	Description
`MountKind.BIND`	`"bind"`	Host bind mount
`MountKind.NAMED`	`"named"`	Named volume mount
`MountKind.TMPFS`	`"tmpfs"`	In-memory filesystem
`MountKind.DISK`	`"disk"`	Host disk image mount

VolumeKind

Used by Volume.create() · Volume.named() · VolumeHandle.kind

Storage kind for a named volume.

Member	Value	Description
`VolumeKind.DIRECTORY`	`"dir"`	Directory-backed volume mounted through virtiofs
`VolumeKind.DISK`	`"disk"`	Raw ext4 disk-image volume mounted through virtio-blk

NamedVolumeMode

Used by Volume.named(mode=…) · MountConfig.named_mode

Creation behavior for a named volume mount.

Member	Value	Description
`NamedVolumeMode.EXISTING`	`"existing"`	Require the named volume to exist
`NamedVolumeMode.CREATE`	`"create"`	Create a new named volume
`NamedVolumeMode.ENSURE_EXISTS`	`"ensure-exists"`	Reuse the named volume if present, otherwise create it

DiskImageFormat

Used by Volume.disk(), MountConfig

String enum (StrEnum) for the format of a backing disk image.

Member	Value	Description
`DiskImageFormat.QCOW2`	`"qcow2"`	QEMU copy-on-write v2 image
`DiskImageFormat.RAW`	`"raw"`	Raw disk image
`DiskImageFormat.VMDK`	`"vmdk"`	VMware disk image

StatVirtualization

Used by MountConfig.stat_virtualization

Stat virtualization policy for virtiofs-backed mounts.

Member	Value	Description
`StatVirtualization.STRICT`	`"strict"`	Fully virtualize guest-visible ownership and mode metadata
`StatVirtualization.RELAXED`	`"relaxed"`	Apply relaxed metadata virtualization
`StatVirtualization.OFF`	`"off"`	Expose host stat metadata directly

HostPermissions

Used by MountConfig.host_permissions

Host permission policy for virtiofs-backed mounts.

Member	Value	Description
`HostPermissions.PRIVATE`	`"private"`	Keep host-side permissions private to microsandbox
`HostPermissions.MIRROR`	`"mirror"`	Mirror relevant host permissions into the guest view

​Volume

​volume.name

​volume.path

​Volume.get_default()

​Volume.create()

​Volume.get()

​Volume.list()

​Volume.remove()

​Volume.bind()

​Volume.named()

​Volume.tmpfs()

​Volume.disk()

​VolumeHandle

​handle.name

​handle.kind

​handle.quota_mib

​handle.used_bytes

​handle.capacity_bytes

​handle.disk_format

​handle.disk_fstype

​handle.labels

​handle.created_at

​handle.fs

​handle.remove()

​VolumeFs

​fs.read()

​fs.read_text()

​fs.write()

​fs.list()

​fs.mkdir()

​fs.remove_file()

​fs.exists()

​Types

​MountConfig

​MountKind

​VolumeKind

​NamedVolumeMode

​DiskImageFormat

​StatVirtualization

​HostPermissions

Volume

volume.name

volume.path

Volume.get_default()

Volume.create()

Volume.get()

Volume.list()

Volume.remove()

Volume.bind()

Volume.named()

Volume.tmpfs()

Volume.disk()

VolumeHandle

handle.name

handle.kind

handle.quota_mib

handle.used_bytes

handle.capacity_bytes

handle.disk_format

handle.disk_fstype

handle.labels

handle.created_at

handle.fs

handle.remove()

VolumeFs

fs.read()

fs.read_text()

fs.write()

fs.list()

fs.mkdir()

fs.remove_file()

fs.exists()

Types

MountConfig

MountKind

VolumeKind

NamedVolumeMode

DiskImageFormat

StatVirtualization

HostPermissions