--- title: Volumes description: Python SDK - Volume API reference --- Create and manage named persistent volumes, and build the mount configs that attach storage to a sandbox. See [Volumes](/sandboxes/volumes) for usage examples and patterns.

Static · Volume4

Volume.create()create a named volume Volume.get()handle to an existing one Volume.list()all volumes Volume.remove()delete a volume

Mount factories · Volume4

Volume.bind()mount a host directory Volume.named()mount a named volume Volume.tmpfs()in-memory filesystem Volume.disk()mount a disk image

Instance · Volume2

volume.namevolume name volume.pathhost path

Instance · VolumeFs7

fs.read()read bytes fs.read_text()read UTF-8 text fs.write()write bytes fs.list()list a directory fs.mkdir()create a directory fs.remove_file()remove a file fs.exists()check a path exists

Types

VolumeHandle VolumeFs MountConfig MountKind DiskImageFormat

Typical flow

```python 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//`. --- #### Volume.create()
staticasync
```python 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 ``` 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.
```python await Volume.create("pip-cache", quota_mib=2048) await Volume.create("docker-data", kind="disk", size_mib=20 * 1024) ``` --- #### Volume.get()
staticasync
```python async def get(name: str) -> VolumeHandle ``` 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.
```python handle = await Volume.get("pip-cache") print(handle.kind, handle.used_bytes) ``` --- #### Volume.list()
staticasync
```python async def list() -> list[VolumeHandle] ``` List all named volumes.

Returns

list[VolumeHandle]
All volume handles.
```python for v in await Volume.list(): print(v.name, v.used_bytes) ``` --- #### Volume.remove()
staticasync
```python async def remove(name: str) -> None ``` Delete a named volume and its contents. Fails if the volume is currently mounted.

Parameters

namestr
Volume name.
```python await Volume.remove("pip-cache") ``` --- ## Mount factories Static factory methods on `Volume` that build a [`MountConfig`](#mountconfig). Pass the result as a value in the `volumes` dict when creating a sandbox, keyed by the guest mount point. --- #### Volume.bind()
static
```python def bind( path: str, *, readonly: bool = False, noexec: bool = False, nosuid: bool = False, nodev: bool = False, ) -> MountConfig ``` 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.
```python sb = await Sandbox.create( "build", image="python", volumes={"/src": Volume.bind("/home/me/project", readonly=True)}, ) ``` --- #### Volume.named()
static
```python def named( name: str, *, readonly: bool = False, noexec: bool = False, nosuid: bool = False, nodev: bool = False, ) -> MountConfig ``` Mount an existing named volume. The volume must already exist; create it first with [`Volume.create()`](#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.
```python sb = await Sandbox.create( "worker", image="python", volumes={ "/root/.cache/pip": Volume.named("pip-cache"), "/etc/config": Volume.named("shared-config", readonly=True), }, ) ``` --- #### Volume.tmpfs()
static
```python def tmpfs( *, size_mib: int | None = None, readonly: bool = False, noexec: bool = False, nosuid: bool = False, nodev: bool = False, ) -> MountConfig ``` 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.
```python sb = await Sandbox.create( "scratch", image="python", volumes={"/tmp/work": Volume.tmpfs(size_mib=256)}, ) ``` --- #### Volume.disk()
static
```python 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 ``` 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.
```python sb = await Sandbox.create( "db", image="postgres", volumes={"/var/lib/postgresql": Volume.disk("/data/pg.qcow2", fstype="ext4")}, ) ``` --- ## Instance properties Read-only properties on a [`Volume`](#volume-create) returned by [`Volume.create()`](#volume-create). --- #### volume.name
property
```python name: str ``` Volume name. --- #### volume.path
property
```python 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`](#volumehandle). These run directly on the host filesystem; no running sandbox is required. All paths are relative to the volume root. --- #### fs.read()
instanceasync
```python async def read(path: str) -> bytes ``` 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.
```python handle = await Volume.get("pip-cache") data = await handle.fs.read("index.json") ``` --- #### fs.read_text()
instanceasync
```python 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()
instanceasync
```python 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

pathstr
Path relative to the volume root.
databytes
File content.
```python handle = await Volume.get("pip-cache") await handle.fs.write("seed.txt", b"hello") ``` --- #### fs.list()
instanceasync
```python 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()
instanceasync
```python async def mkdir(path: str) -> None ``` Create a directory and all parent directories.

Parameters

pathstr
Path relative to the volume root.
--- #### fs.remove_file()
instanceasync
```python async def remove_file(path: str) -> None ``` Remove a file.

Parameters

pathstr
Path relative to the volume root.
--- #### fs.exists()
instanceasync
```python 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
class

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`](#volumefs) | Host-side filesystem handle | | remove() | *(async)* `None` | Delete this volume | ### VolumeFs
class

Returned by VolumeHandle.fs

Host-side filesystem operations on a named volume. No running sandbox is required. See the [VolumeFs methods](#volumefs-methods) above for the full API. | Method | Signature | Description | |--------|-----------|-------------| | [read](#fs-read) | `read(path) -> bytes` | Read a file as raw bytes | | [read_text](#fs-read_text) | `read_text(path) -> str` | Read a file as UTF-8 text | | [write](#fs-write) | `write(path, data) -> None` | Write bytes to a file | | [list](#fs-list) | `list(path) -> list[FsEntry]` | List a directory | | [mkdir](#fs-mkdir) | `mkdir(path) -> None` | Create a directory | | [remove_file](#fs-remove_file) | `remove_file(path) -> None` | Remove a file | | [exists](#fs-exists) | `exists(path) -> bool` | Check a path exists | ### MountConfig
dataclass

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

Frozen dataclass representing a mount configuration. Build one with a [mount factory](#mount-factories) 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`](#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`](#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
enum

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
enum

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 |