docs/sdk/python/volumes.mdx
Create, manage, and mount named volumes. See Volumes for usage examples.
name: str
Volume name.
path: str
Host path to the volume's directory.
<p className="msb-member-group">Static methods</p>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"))
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
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.
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 direct 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> <p className="msb-member-group">Mount factories</p>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,
*,
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,
) -> MountConfig
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.
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: DiskImageFormat | 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.
A lightweight handle to a named volume, with its database metadata and a host-side filesystem accessor.
str
Volume name
Volume storage kind
int \| None
Storage quota in MiB
int
Current disk usage in bytes
int \| None
Disk capacity in bytes
DiskImageFormat \| None
Disk image format
str \| None
Disk filesystem type
dict[str, str]
Metadata labels
float \| None
Creation timestamp (ms since epoch)
Host-side filesystem handle
remove()
Delete this volume
<p className="msb-label">Returns</p>(async) None
Host-side filesystem operations for a named volume.
<Tooltip tip="Unmounted-volume filesystem access is not available on microsandbox cloud; mount the volume into a sandbox and use the sandbox filesystem."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
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><Tooltip tip="Unmounted-volume filesystem access is not available on microsandbox cloud; mount the volume into a sandbox and use the sandbox filesystem."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
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><Tooltip tip="Unmounted-volume filesystem access is not available on microsandbox cloud; mount the volume into a sandbox and use the sandbox filesystem."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
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>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 | 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) |
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 |
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 |
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 |
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 |
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 |
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 |