docs/sdk/go/volumes.mdx
Create, manage, and mount named volumes. See Volumes for usage examples.
func GetDefaultVolume(ctx context.Context) (*VolumeHandle, error)
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 returns ErrUnsupportedOperation; it never substitutes a directory from the caller's machine.
volume, err := m.GetDefaultVolume(ctx)
err = volume.FS().WriteString(ctx, "customers/acme.json", `{"active":true}`)
contents, err := volume.FS().ReadString(ctx, "customers/acme.json")
func CreateVolume(ctx context.Context, name string, opts ...VolumeOption) (*Volume, error)
vol, err := m.CreateVolume(ctx, "docker-data",
m.WithVolumeKind(m.VolumeKindDisk),
m.WithVolumeSize(20*1024),
)
Create a named volume and return a populated *Volume with its name and host path. Configure the kind, quota, disk size, and labels with option functions. Returns ErrVolumeAlreadyExists if a volume with the given name already exists.
func GetVolume(ctx context.Context, name string) (*VolumeHandle, error)
h, err := m.GetVolume(ctx, "my-data")
fmt.Println(h.Path(), h.UsedBytes())
Look up a volume by name and return its metadata. Returns ErrVolumeNotFound if no such volume exists.
func ListVolumes(ctx context.Context) ([]*VolumeHandle, error)
vols, err := m.ListVolumes(ctx)
for _, h := range vols {
fmt.Printf("%s - %s\n", h.Name(), h.Kind())
}
Return metadata for every named volume on the host.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div> <div className="msb-param-desc">Cancels the listing.</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">All volume metadata handles.</div> </div> </div>func RemoveVolume(ctx context.Context, name string) error
err := m.RemoveVolume(ctx, "my-data")
Delete a volume by name. All sandboxes referencing the volume must be stopped first.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div> <div className="msb-param-desc">Cancels the removal.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>name</code><span className="msb-type">string</span></div> <div className="msb-param-desc">Volume name.</div> </div> </div>A named persistent volume.
func (v *Volume) Name() string
Return the volume's name.
func (v *Volume) Path() string
Return the host filesystem path of the volume's data directory.
<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>
func (v *Volume) FS() *VolumeFs
vfs := vol.FS()
err := vfs.WriteString(ctx, "seed.txt", "hello")
Return a *VolumeFs for direct file operations. Local calls use the managed host directory; Cloud calls use the authenticated volume API.
func (v *Volume) Remove(ctx context.Context) error
err := vol.Remove(ctx)
Delete this volume. All sandboxes using it must be stopped. Equivalent to RemoveVolume(ctx, v.Name()).
Metadata reference for a named volume. Obtain via GetVolume or ListVolumes.
A VolumeHandle is the metadata reference returned by GetVolume and ListVolumes.
func (h *VolumeHandle) Name() string
Return the volume name.
func (h *VolumeHandle) Path() string
Return the host filesystem path of the volume's data directory.
func (h *VolumeHandle) Kind() VolumeKind
Return the volume storage kind: VolumeKindDir or VolumeKindDisk.
func (h *VolumeHandle) QuotaMiB() *uint32
Return the quota in MiB, or nil if unlimited.
func (h *VolumeHandle) UsedBytes() uint64
Return the amount of space used by the volume, in bytes.
func (h *VolumeHandle) CapacityBytes() *uint64
Return the disk capacity in bytes for disk volumes, or nil for directory volumes.
func (h *VolumeHandle) DiskFormat() *string
Return the disk image format for disk volumes, or nil for directory volumes.
func (h *VolumeHandle) DiskFstype() *string
Return the inner filesystem type for disk volumes, or nil for directory volumes.
func (h *VolumeHandle) Labels() map[string]string
Return the labels attached to this volume.
func (h *VolumeHandle) CreatedAt() time.Time
Return the creation timestamp, or the zero time.Time value if unknown.
<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>
func (h *VolumeHandle) FS() *VolumeFs
Return a *VolumeFs for direct host-side file operations on this volume.
func (h *VolumeHandle) Remove(ctx context.Context) error
Delete this volume. All sandboxes using it must be stopped. Equivalent to RemoveVolume(ctx, h.Name()).
Host-side filesystem operations for a named volume.
func (fs *VolumeFs) Root() string
Return the absolute host path of the volume's data directory.
<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>
func (fs *VolumeFs) Read(ctx context.Context, relPath string) ([]byte, error)
Read the contents of a file relative to the volume root.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>relPath</code><span className="msb-type">string</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">[]byte</span></div> <div className="msb-param-desc">File contents.</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>
func (fs *VolumeFs) ReadString(ctx context.Context, relPath string) (string, error)
Read a file and return its contents as a UTF-8 string.
<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>
func (fs *VolumeFs) Write(ctx context.Context, relPath string, data []byte) error
Write data to a file, creating or truncating it. Created files use mode 0o644.
<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>
func (fs *VolumeFs) WriteString(ctx context.Context, relPath, content string) error
Write a string to a file. Created files use mode 0o644.
func (fs *VolumeFs) Mkdir(ctx context.Context, relPath string) error
Create a directory and all missing parents (mode 0o755).
func (fs *VolumeFs) Remove(ctx context.Context, relPath string) error
Delete a single file or empty directory.
func (fs *VolumeFs) RemoveAll(ctx context.Context, relPath string) error
Delete a path and any children it contains (recursive).
func (fs *VolumeFs) Exists(ctx context.Context, relPath string) (bool, error)
Report whether a file or directory exists at the given path.
<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 a file or directory exists at the path.</div> </div> </div>Functional options passed to CreateVolume, plus the Mount factory helpers that attach a volume, bind mount, tmpfs, or disk image to a sandbox via WithMounts.
<Tooltip tip="Disk-kind volumes are not available on microsandbox cloud; use a directory-backed named volume."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
func WithVolumeKind(kind VolumeKind) VolumeOption
Select the volume kind. Valid values are VolumeKindDir (default) and VolumeKindDisk.
<Tooltip tip="Disk-kind volumes are not available on microsandbox cloud; use a directory-backed named volume."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
func WithVolumeSize(mebibytes uint32) VolumeOption
Set disk volume capacity in MiB. Required when the kind is VolumeKindDisk.
func WithVolumeQuota(mebibytes uint32) VolumeOption
Set the recorded quota in MiB for directory volumes. Zero means unlimited.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>mebibytes</code><span className="msb-type">uint32</span></div> <div className="msb-param-desc">Quota in MiB; zero means unlimited.</div> </div> </div>func WithVolumeLabels(labels map[string]string) VolumeOption
Attach key-value labels to the volume. When called repeatedly, the maps merge; later keys overwrite earlier ones.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>labels</code><span className="msb-type">map[string]string</span></div> <div className="msb-param-desc">Metadata labels to attach.</div> </div> </div>func (mountFactory) Bind(hostPath string, opts MountOptions) MountConfig
Bind-mount a host directory into the sandbox. Changes in the guest are reflected on the host and vice versa. Set MountOptions.QuotaMiB to bound how much the guest may write beyond the host directory's existing contents, overriding the runtime's protective default. Returns a MountConfig for use with WithMounts.
"/host": m.Mount.Bind("/var/data", m.MountOptions{Readonly: true})
"/out": m.Mount.Bind("./output", m.MountOptions{QuotaMiB: 2048})
func (mountFactory) Named(name string, opts MountOptions) MountConfig
"/data": m.Mount.Named("my-data", m.MountOptions{})
Mount an existing named persistent volume. The volume must already exist (create it with CreateVolume). Returns a MountConfig.
func (mountFactory) NamedWith(name string, opts MountOptions, namedOpts NamedVolumeOptions) MountConfig
sb, err := m.CreateSandbox(ctx, "worker",
m.WithImage("python"),
m.WithMounts(map[string]m.MountConfig{
"/cache": m.Mount.NamedWith("pip-cache", m.MountOptions{}, m.NamedVolumeOptions{
Mode: "ensure-exists",
}),
"/var/lib/docker": m.Mount.NamedWith("docker-data", m.MountOptions{}, m.NamedVolumeOptions{
Mode: "ensure-exists",
Kind: "disk",
SizeMiB: 20 * 1024,
}),
}),
)
Mount a named persistent volume with explicit sandbox-time existence behavior. NamedVolumeOptions.Mode accepts "existing" (default), "create", or "ensure-exists". Mode: "create" fails when the named volume already exists. Mode: "ensure-exists" creates the volume if it is missing and reuses a compatible existing volume; it errors when the existing volume has a different kind, quota, or capacity than requested, and never mutates existing volume metadata.
func (mountFactory) Tmpfs(opts TmpfsOptions) MountConfig
"/scratch": m.Mount.Tmpfs(m.TmpfsOptions{SizeMiB: 128})
Mount an ephemeral in-memory filesystem. Contents are discarded when the sandbox stops. Returns a MountConfig.
<Tooltip tip="On microsandbox cloud, the disk-image path resolves against your organization's host volume, not the computer running the SDK or CLI."><span className="msb-badge-note">On cloud <Icon icon="circle-info" size={11} /></span></Tooltip>
func (mountFactory) Disk(hostPath string, opts DiskOptions) MountConfig
"/img": m.Mount.Disk("./data.qcow2", m.DiskOptions{
Format: "qcow2",
Fstype: "ext4",
Readonly: true,
})
Mount a host disk image as a virtio-blk device. Supports raw, qcow2, and vmdk formats. Returns a MountConfig.
Mount configuration produced by the Mount factory.
string
Host path for bind mounts
string
Volume name for named mounts
string
Provisioning mode for named mounts ("existing", "create", "ensure-exists")
string
Kind for provisioned named mounts ("dir" or "disk")
uint32
Quota in MiB for provisioned directory volumes
bool
Set for tmpfs mounts
string
Host path for disk images
string
Disk format
string
Inner filesystem type
bool
Whether the mount is read-only
bool
Whether direct execution from the mount is disabled
bool
Whether setuid/setgid elevation from files on the mount is ignored
bool
Whether device files on the mount are ignored
uint32
Size limit for tmpfs / capacity for provisioned disk volumes
StatVirtualization
Per-mount stat-virtualization policy (bind / named only)
HostPermissions
Per-mount host-permission propagation policy (bind / named only)
Kind()
Which mount flavour this is
<p className="msb-label">Returns</p>var ErrPathEscape = errors.New("microsandbox: path escapes volume root")
Returned by every VolumeFs method when relPath is absolute, contains a .. sequence that resolves outside the volume root, or otherwise escapes the volume's directory after filepath.Clean.
if _, err := vfs.Read(ctx, "../etc/passwd"); errors.Is(err, m.ErrPathEscape) {
log.Println("nice try")
}
The config struct populated by VolumeOption functions. Most callers go through CreateVolume(ctx, name, opts...); VolumeConfig is exported for callers that prefer to construct one directly.
| Field | Type | Description |
|---|---|---|
QuotaMiB | uint32 | Maximum storage size in MiB (zero = unlimited) |
Kind | VolumeKind | Volume kind (VolumeKindDir by default) |
SizeMiB | uint32 | Disk capacity in MiB for VolumeKindDisk |
Labels | map[string]string | Metadata labels |
type VolumeOption func(*VolumeConfig)
A functional option for CreateVolume. Constructed by the WithVolume* helpers.
type VolumeKind string
Describes the storage backing for a named volume.
<p className="msb-backref">Used by <a href="#volumeconfig">VolumeConfig</a> · <a href="#withvolumekind">WithVolumeKind()</a> · <a href="#h-kind">VolumeHandle.Kind()</a></p>| Constant | Value | Description |
|---|---|---|
VolumeKindDir | "dir" | Directory-backed named volume |
VolumeKindDisk | "disk" | Raw ext4 disk-backed named volume |
type MountKind uint8
Discriminates between the four mount flavours. Inspect via mount.Kind().
| Constant | Description |
|---|---|
MountKindBind | Host bind mount |
MountKindNamed | Named persistent volume |
MountKindTmpfs | In-memory tmpfs |
MountKindDisk | Host disk image |
Tuning struct for Mount.Bind, Mount.Named, and Mount.NamedWith. StatVirtualization and HostPermissions are virtiofs-only and rejected at build time if combined with a tmpfs or disk-image mount; their zero values preserve the conservative defaults (strict, private).
| Field | Type | Description |
|---|---|---|
Readonly | bool | Mount as read-only; virtiofs-backed mounts also reject writes in the host filesystem server |
Noexec | bool | Prevent direct execution from the mount |
Nosuid | bool | Ignore setuid and setgid privilege elevation from files on the mount |
Nodev | bool | Ignore device files on the mount |
QuotaMiB | uint32 | Guest-write quota in MiB, bounding growth beyond the host directory's existing contents; zero keeps the protective default (bind mounts only; named volumes use NamedVolumeOptions.QuotaMiB) |
StatVirtualization | StatVirtualization | Per-mount stat-virtualization policy (virtiofs only) |
HostPermissions | HostPermissions | Per-mount host-permission propagation policy (virtiofs only) |
Tunes sandbox-time named volume provisioning for Mount.NamedWith.
| Field | Type | Description |
|---|---|---|
Mode | string | "existing", "create", or "ensure-exists"; empty means "existing" |
Kind | string | "dir" or "disk"; empty means "dir" |
SizeMiB | uint32 | Disk capacity in MiB; required when creating or ensuring a missing disk volume |
QuotaMiB | uint32 | Directory volume quota in MiB |
Tuning struct for Mount.Tmpfs.
| Field | Type | Description |
|---|---|---|
SizeMiB | uint32 | Maximum size in MiB |
Readonly | bool | Mount as read-only |
Noexec | bool | Prevent direct execution from the mount |
Nosuid | bool | Ignore setuid and setgid privilege elevation from files on the mount |
Nodev | bool | Ignore device files on the mount |
Tuning struct for Mount.Disk.
| Field | Type | Description |
|---|---|---|
Format | string | Format hint ("raw", "qcow2", "vmdk"). Optional; the runtime can usually probe |
Fstype | string | Inner filesystem type (e.g. "ext4", "xfs"). Optional; omitted means auto-detect |
Readonly | bool | Mount as read-only |
Noexec | bool | Prevent direct execution from the mount |
Nosuid | bool | Ignore setuid and setgid privilege elevation from files on the mount |
Nodev | bool | Ignore device files on the mount |