Volume
Instance properties
volume.name
str
Volume name.
volume.path
str
Host path to the volume’s directory.
Static methods
Volume.owned()
Volume.owned() to configure local storage allocated for one sandbox. It starts empty, survives stop/start and reboot, and is deleted with the sandbox. Owned mounts do not appear in Volume.list() and cannot be shared or removed independently. Cloud rejects owned mounts.
Volume.owned() returns a MountConfig. kind defaults to VolumeKind.DIRECTORY; quota_mib applies only to directories. VolumeKind.DISK creates raw ext4 and requires positive size_mib. Common flags are readonly, noexec, nosuid, and nodev. stat_virtualization, host_permissions, and paired uid/gid apply only to directories. No host path or volume name is accepted. Mounting over an existing image directory hides its contents without copying them.
Volume.get_default()
.fs(). The local backend raises a typed unsupported error; it never substitutes a directory from the caller’s machine.
Example
Example
Volume.create()
Example
Example
VolumeKind. Disk volumes require size_mib.
Parameters
namestrkindVolumeKindDIRECTORY.size_mibint | Nonekind=VolumeKind.DISK.quota_mibint | Nonelabelsdict[str, str] | NoneReturns
name and path.Volume.get()
Example
Example
Parameters
namestrReturns
Volume.list()
Example
Example
Returns
Volume.remove()
Example
Example
Parameters
namestrMount factories
Static factory methods onVolume 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()
Example
Example
Parameters
pathstrreadonlyboolnoexecboolnosuidboolnodevboolstat_virtualizationStatVirtualization | Nonehost_permissionsHostPermissions | Noneuidint | Nonegid.gidint | Noneuid.Returns
Volume.named()
Example
Example
mode to control creation behavior and use kind, size_mib, and quota_mib when creating it.
Parameters
namestrsize_mibint | Nonequota_mibint | Nonereadonlyboolnoexecboolnosuidboolnodevboolstat_virtualizationStatVirtualization | Nonehost_permissionsHostPermissions | Noneuidint | Nonegid and use only with directory-backed volumes.gidint | Noneuid and use only with directory-backed volumes.Returns
Volume.tmpfs()
Example
Example
Parameters
size_mibint | NonereadonlyboolnoexecboolnosuidboolnodevboolReturns
Volume.disk()
Example
Example
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
pathstrformatDiskImageFormat | Nonefstypestr | NonereadonlyboolnoexecboolnosuidboolnodevboolReturns
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()
Returns
(async)None
VolumeFs
Returned by VolumeHandle.fs
Host-side filesystem operations for a named volume.fs.read()
Example
Example
Parameters
pathstrReturns
fs.read_text()
Parameters
pathstrReturns
fs.write()
Example
Example
Parameters
pathstrdatabytesfs.list()
Parameters
pathstrReturns
fs.mkdir()
Parameters
pathstrfs.remove_file()
Parameters
pathstrfs.exists()
Parameters
pathstrReturns
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 sandboxvolumes 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.
MountKind
Used by MountConfig
String enum (StrEnum) for the type of mount.
VolumeKind
Used by Volume.create() · Volume.named() · VolumeHandle.kind
Storage kind for a named volume.NamedVolumeMode
Used by Volume.named(mode=…) · MountConfig.named_mode
Creation behavior for a named volume mount.DiskImageFormat
Used by Volume.disk(), MountConfig
String enum (StrEnum) for the format of a backing disk image.
StatVirtualization
Used by MountConfig.stat_virtualization
Stat virtualization policy for virtiofs-backed mounts.HostPermissions
Used by MountConfig.host_permissions
Host permission policy for virtiofs-backed mounts.