docs/sdk/python/volumes.mdx
Create and manage named persistent volumes, and build the mount configs that attach storage to a sandbox. See Volumes for usage examples and patterns.
<p className="msb-label" id="typical-flow">Typical flow</p>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 on Volume that manage named persistent volumes. Volumes live independently of any sandbox, stored by default under ~/.microsandbox/volumes/<name>/.
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
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.
async def get(name: str) -> VolumeHandle
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>name</code><span className="msb-type">str</span></div> <div className="msb-param-desc">Volume name.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#volumehandle">VolumeHandle</a></div> <div className="msb-param-desc">Handle with metadata and a filesystem accessor.</div> </div> </div>async def list() -> list[VolumeHandle]
for v in await Volume.list():
print(v.name, v.used_bytes)
List all named volumes.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#volumehandle">list[VolumeHandle]</a></div> <div className="msb-param-desc">All volume handles.</div> </div> </div>async def remove(name: str) -> None
await Volume.remove("pip-cache")
Delete a named volume and its contents. Fails if the volume is currently mounted.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>name</code><span className="msb-type">str</span></div> <div className="msb-param-desc">Volume name.</div> </div> </div>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.
def bind(
path: str,
*,
readonly: bool = False,
noexec: bool = False,
nosuid: bool = False,
nodev: bool = False,
) -> MountConfig
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div> <div className="msb-param-desc">Directory path on the host.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>readonly</code><span className="msb-type">bool</span></div> <div className="msb-param-desc">Mount as read-only; virtiofs-backed mounts also reject writes in the host filesystem server.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>noexec</code><span className="msb-type">bool</span></div> <div className="msb-param-desc">Prevent direct execution from the mount.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>nosuid</code><span className="msb-type">bool</span></div> <div className="msb-param-desc">Ignore setuid and setgid privilege elevation from files on the mount.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>nodev</code><span className="msb-type">bool</span></div> <div className="msb-param-desc">Ignore device files on the mount.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#mountconfig">MountConfig</a></div> <div className="msb-param-desc">Mount configuration.</div> </div> </div>def named(
name: str,
*,
readonly: bool = False,
noexec: bool = False,
nosuid: bool = False,
nodev: bool = False,
) -> MountConfig
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().
def tmpfs(
*,
size_mib: int | None = None,
readonly: bool = False,
noexec: bool = False,
nosuid: bool = False,
nodev: bool = False,
) -> MountConfig
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>size_mib</code><span className="msb-type">int | None</span></div> <div className="msb-param-desc">Maximum size in MiB.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>readonly</code><span className="msb-type">bool</span></div> <div className="msb-param-desc">Mount as read-only.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>noexec</code><span className="msb-type">bool</span></div> <div className="msb-param-desc">Prevent direct execution from the mount.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>nosuid</code><span className="msb-type">bool</span></div> <div className="msb-param-desc">Ignore setuid and setgid privilege elevation from files on the mount.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>nodev</code><span className="msb-type">bool</span></div> <div className="msb-param-desc">Ignore device files on the mount.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#mountconfig">MountConfig</a></div> <div className="msb-param-desc">Mount configuration.</div> </div> </div>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
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.
Read-only properties on a Volume returned by Volume.create().
name: str
Volume name.
path: str
Host path to the volume's directory.
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.
async def read(path: str) -> bytes
handle = await Volume.get("pip-cache")
data = await handle.fs.read("index.json")
Read the entire contents of a file as raw bytes.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div> <div className="msb-param-desc">Path relative to the volume root.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">bytes</span></div> <div className="msb-param-desc">File contents as raw bytes.</div> </div> </div>async def read_text(path: str) -> str
Read the entire contents of a file and decode it as UTF-8.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div> <div className="msb-param-desc">Path relative to the volume root.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">str</span></div> <div className="msb-param-desc">File contents as a string.</div> </div> </div>async def write(path: str, data: bytes) -> None
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div> <div className="msb-param-desc">Path relative to the volume root.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>data</code><span className="msb-type">bytes</span></div> <div className="msb-param-desc">File content.</div> </div> </div>async def list(path: str) -> list[FsEntry]
List the entries in a directory.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div> <div className="msb-param-desc">Path relative to the volume root.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="/sdk/python/filesystem#fsentry">list[FsEntry]</a></div> <div className="msb-param-desc">Directory entries.</div> </div> </div>async def mkdir(path: str) -> None
Create a directory and all parent directories.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div> <div className="msb-param-desc">Path relative to the volume root.</div> </div> </div>async def remove_file(path: str) -> None
Remove a file.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div> <div className="msb-param-desc">Path relative to the volume root.</div> </div> </div>async def exists(path: str) -> bool
Check whether a path exists within the volume.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div> <div className="msb-param-desc">Path relative to the volume root.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">bool</span></div> <div className="msb-param-desc"><code>True</code> if the path exists.</div> </div> </div>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 |
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 |
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) |
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 |
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 |