Volumes - microsandbox

Create and manage named persistent volumes, and build the mount configs that attach storage to a sandbox. See Volumes for usage examples and patterns.

Typical flow

from microsandbox import Sandbox, Volume

# 1. create a persistent named volume
await Volume.create("pip-cache", quota_mib=2048)

# 2. mount it into a sandbox via a mount factory
sb = await Sandbox.create(
    "worker",
    image="python",
    volumes={"/root/.cache/pip": Volume.named("pip-cache")},
)

# 3. inspect or edit the volume from the host, no sandbox required
handle = await Volume.get("pip-cache")
print(handle.used_bytes)

Static methods

Static methods on Volume that manage named persistent volumes. Volumes live independently of any sandbox, stored by default under ~/.microsandbox/volumes/<name>/.

Volume.create()

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

Example

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

Create a new named volume. A "dir" volume is a host directory; a "disk" volume is a backing disk image that requires size_mib.

Parameters

namestr

Volume name.

kindstr

Volume kind: “dir” (default) or “disk”.

size_mibint | None

Disk capacity in MiB; required with kind=“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 host-side 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,
) -> 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.

Returns

MountConfig

Mount configuration.

Volume.named()

def named(
    name: str,
    *,
    readonly: bool = False,
    noexec: bool = False,
    nosuid: bool = False,
    nodev: bool = False,
) -> MountConfig

Example

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

Mount an existing named volume. The volume must already exist; create it first with Volume.create().

Parameters

namestr

Volume name.

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.

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: str | 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.

formatstr | 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.

Instance properties

Read-only properties on a Volume returned by Volume.create().

volume.name

name: str

Volume name.

volume.path

path: str

Host path to the volume’s directory.

VolumeFs methods

Host-side filesystem operations on a named volume, obtained via the fs property on a VolumeHandle. These run directly on the host filesystem; no running sandbox is required. All paths are relative to the volume root.

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

VolumeHandle

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

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

Property / Method	Type	Description
name	`str`	Volume name
kind	`str`	Volume kind: `dir` or `disk`
quota_mib	`int \| None`	Storage quota in MiB
used_bytes	`int`	Current disk usage in bytes
capacity_bytes	`int \| None`	Disk capacity in bytes
disk_format	`str \| None`	Disk image format
disk_fstype	`str \| None`	Disk filesystem type
labels	`dict[str, str]`	Metadata labels
created_at	`float \| None`	Creation timestamp (ms since epoch)
fs	`VolumeFs`	Host-side filesystem handle
remove()	(async) `None`	Delete this volume

VolumeFs

Returned by VolumeHandle.fs

Host-side filesystem operations on a named volume. No running sandbox is required. See the VolumeFs methods above for the full API.

Method	Signature	Description
read	`read(path) -> bytes`	Read a file as raw bytes
read_text	`read_text(path) -> str`	Read a file as UTF-8 text
write	`write(path, data) -> None`	Write bytes to a file
list	`list(path) -> list[FsEntry]`	List a directory
mkdir	`mkdir(path) -> None`	Create a directory
remove_file	`remove_file(path) -> None`	Remove a file
exists	`exists(path) -> bool`	Check a path exists

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 and host_permissions apply only to virtiofs-backed mounts (BIND and NAMED); setting either on a TMPFS or DISK mount raises ValueError.

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	`"existing" \| "create" \| "ensure-exists" \| None`	`None`	Named-volume creation behavior
named_kind	`"dir" \| "directory" \| "disk" \| 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` `\| str \| None`	`None`	Disk image format for disk mounts
fstype	`str \| None`	`None`	Inner filesystem type for disk mounts
stat_virtualization	`StatVirtualization \| str \| None`	`None`	Per-mount stat-virtualization policy (virtiofs-backed only)
host_permissions	`HostPermissions \| str \| None`	`None`	Per-mount host-permission policy (virtiofs-backed only)

MountKind

Used by MountConfig

String enum (StrEnum) for the type of mount.

Value	Description
`"bind"`	Host bind mount
`"named"`	Named volume mount
`"tmpfs"`	In-memory filesystem
`"disk"`	Host disk image mount

DiskImageFormat

Used by Volume.disk(), MountConfig

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

Value	Description
`"qcow2"`	QEMU copy-on-write v2 image
`"raw"`	Raw disk image
`"vmdk"`	VMware disk image

​Static methods

​Volume.create()

​Volume.get()

​Volume.list()

​Volume.remove()

​Mount factories

​Volume.bind()

​Volume.named()

​Volume.tmpfs()

​Volume.disk()

​Instance properties

​volume.name

​volume.path

​VolumeFs methods

​fs.read()

​fs.read_text()

​fs.write()

​fs.list()

​fs.mkdir()

​fs.remove_file()

​fs.exists()

​Types

​VolumeHandle

​VolumeFs

​MountConfig

​MountKind

​DiskImageFormat

Static methods

Volume.create()

Volume.get()

Volume.list()

Volume.remove()

Mount factories

Volume.bind()

Volume.named()

Volume.tmpfs()

Volume.disk()

Instance properties

volume.name

volume.path

VolumeFs methods

fs.read()

fs.read_text()

fs.write()

fs.list()

fs.mkdir()

fs.remove_file()

fs.exists()

Types

VolumeHandle

VolumeFs

MountConfig

MountKind

DiskImageFormat