Volumes - microsandbox

Create, manage, and mount named volumes. See Volumes for usage examples.

Functions

GetDefaultVolume()

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")

CreateVolume()

func CreateVolume(ctx context.Context, name string, opts ...VolumeOption) (*Volume, error)

Example

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.

Parameters

ctxcontext.Context

Cancels the create.

namestring

Volume name.

opts…VolumeOption

Functional options, see Options.

Returns

*Volume

Newly created volume with Name and Path.

GetVolume()

func GetVolume(ctx context.Context, name string) (*VolumeHandle, error)

Example

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.

Parameters

ctxcontext.Context

Cancels the lookup.

namestring

Volume name.

Returns

*VolumeHandle

Metadata reference for the volume.

ListVolumes()

func ListVolumes(ctx context.Context) ([]*VolumeHandle, error)

Example

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.

Parameters

ctxcontext.Context

Cancels the listing.

Returns

[]*VolumeHandle

All volume metadata handles.

RemoveVolume()

func RemoveVolume(ctx context.Context, name string) error

Example

err := m.RemoveVolume(ctx, "my-data")

Delete a volume by name. All sandboxes referencing the volume must be stopped first.

Parameters

ctxcontext.Context

Cancels the removal.

namestring

Volume name.

Volume

Returned by CreateVolume()

A named persistent volume.

v.Name()

func (v *Volume) Name() string

Return the volume’s name.

v.Path()

func (v *Volume) Path() string

Return the host filesystem path of the volume’s data directory.

v.FS()

func (v *Volume) FS() *VolumeFs

Example

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.

Returns

*VolumeFs

Filesystem accessor rooted at the volume directory.

v.Remove()

func (v *Volume) Remove(ctx context.Context) error

Example

err := vol.Remove(ctx)

Delete this volume. All sandboxes using it must be stopped. Equivalent to RemoveVolume(ctx, v.Name()).

VolumeHandle

Metadata reference for a named volume. Obtain via GetVolume or ListVolumes.

Returned by GetVolume() · ListVolumes()

A VolumeHandle is the metadata reference returned by GetVolume and ListVolumes.

h.Name()

func (h *VolumeHandle) Name() string

Return the volume name.

h.Path()

func (h *VolumeHandle) Path() string

Return the host filesystem path of the volume’s data directory.

h.Kind()

func (h *VolumeHandle) Kind() VolumeKind

Return the volume storage kind: VolumeKindDir or VolumeKindDisk.

Returns

VolumeKind

Storage backing for the volume.

h.QuotaMiB()

func (h *VolumeHandle) QuotaMiB() *uint32

Return the quota in MiB, or nil if unlimited.

h.UsedBytes()

func (h *VolumeHandle) UsedBytes() uint64

Return the amount of space used by the volume, in bytes.

h.CapacityBytes()

func (h *VolumeHandle) CapacityBytes() *uint64

Return the disk capacity in bytes for disk volumes, or nil for directory volumes.

h.DiskFormat()

func (h *VolumeHandle) DiskFormat() *string

Return the disk image format for disk volumes, or nil for directory volumes.

h.DiskFstype()

func (h *VolumeHandle) DiskFstype() *string

Return the inner filesystem type for disk volumes, or nil for directory volumes.

h.Labels()

func (h *VolumeHandle) Labels() map[string]string

Return the labels attached to this volume.

h.CreatedAt()

func (h *VolumeHandle) CreatedAt() time.Time

Return the creation timestamp, or the zero time.Time value if unknown.

h.FS()

func (h *VolumeHandle) FS() *VolumeFs

Return a *VolumeFs for direct host-side file operations on this volume.

Returns

*VolumeFs

Filesystem accessor rooted at the volume directory.

h.Remove()

func (h *VolumeHandle) Remove(ctx context.Context) error

Delete this volume. All sandboxes using it must be stopped. Equivalent to RemoveVolume(ctx, h.Name()).

VolumeFs

Returned by Volume.FS() · VolumeHandle.FS()

Host-side filesystem operations for a named volume.

vfs.Root()

func (fs *VolumeFs) Root() string

Return the absolute host path of the volume’s data directory.

vfs.Read()

func (fs *VolumeFs) Read(ctx context.Context, relPath string) ([]byte, error)

Read the contents of a file relative to the volume root.

Parameters

relPathstring

Path relative to the volume root.

Returns

[]byte

File contents.

vfs.ReadString()

func (fs *VolumeFs) ReadString(ctx context.Context, relPath string) (string, error)

Read a file and return its contents as a UTF-8 string.

vfs.Write()

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.

Parameters

relPathstring

Path relative to the volume root.

data[]byte

Bytes to write.

vfs.WriteString()

func (fs *VolumeFs) WriteString(ctx context.Context, relPath, content string) error

Write a string to a file. Created files use mode 0o644.

vfs.Mkdir()

func (fs *VolumeFs) Mkdir(ctx context.Context, relPath string) error

Create a directory and all missing parents (mode 0o755).

vfs.Remove()

func (fs *VolumeFs) Remove(ctx context.Context, relPath string) error

Delete a single file or empty directory.

vfs.RemoveAll()

func (fs *VolumeFs) RemoveAll(ctx context.Context, relPath string) error

Delete a path and any children it contains (recursive).

vfs.Exists()

func (fs *VolumeFs) Exists(ctx context.Context, relPath string) (bool, error)

Report whether a file or directory exists at the given path.

Returns

bool

true if a file or directory exists at the path.

Options

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.

WithVolumeKind()

func WithVolumeKind(kind VolumeKind) VolumeOption

Select the volume kind. Valid values are VolumeKindDir (default) and VolumeKindDisk.

Parameters

kindVolumeKind

Storage backing for the volume.

WithVolumeSize()

func WithVolumeSize(mebibytes uint32) VolumeOption

Set disk volume capacity in MiB. Required when the kind is VolumeKindDisk.

Parameters

mebibytesuint32

Disk capacity in MiB.

WithVolumeQuota()

func WithVolumeQuota(mebibytes uint32) VolumeOption

Set the recorded quota in MiB for directory volumes. Zero means unlimited.

Parameters

mebibytesuint32

Quota in MiB; zero means unlimited.

WithVolumeLabels()

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.

Parameters

labelsmap[string]string

Metadata labels to attach.

Mount

Mount.Bind()

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.

Parameters

hostPathstring

Host directory to bind.

optsMountOptions

Mount tuning (read-only, noexec, and so on).

Example

"/host": m.Mount.Bind("/var/data", m.MountOptions{Readonly: true})
"/out":  m.Mount.Bind("./output", m.MountOptions{QuotaMiB: 2048})

Mount.Named()

func (mountFactory) Named(name string, opts MountOptions) MountConfig

Example

"/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.

Parameters

namestring

Name of an existing volume.

optsMountOptions

Mount tuning.

Mount.NamedWith()

func (mountFactory) NamedWith(name string, opts MountOptions, namedOpts NamedVolumeOptions) MountConfig

Example

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.

Parameters

namestring

Volume name.

optsMountOptions

Mount tuning.

namedOptsNamedVolumeOptions

Provisioning mode, kind, size, and quota.

Mount.Tmpfs()

func (mountFactory) Tmpfs(opts TmpfsOptions) MountConfig

Example

"/scratch": m.Mount.Tmpfs(m.TmpfsOptions{SizeMiB: 128})

Mount an ephemeral in-memory filesystem. Contents are discarded when the sandbox stops. Returns a MountConfig.

Parameters

optsTmpfsOptions

Size limit and mount flags.

Mount.Disk()

func (mountFactory) Disk(hostPath string, opts DiskOptions) MountConfig

Example

"/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.

Parameters

hostPathstring

Host path to the disk image.

optsDiskOptions

Format, inner filesystem, and mount flags.

MountConfig

Mount configuration produced by the Mount factory.

Returned by Mount.Bind() · Mount.Named() · Mount.NamedWith() · Mount.Tmpfs() · Mount.Disk()

mount.Bind

string Host path for bind mounts

mount.Named

string Volume name for named mounts

mount.NamedMode

string Provisioning mode for named mounts ("existing", "create", "ensure-exists")

mount.NamedKind

string Kind for provisioned named mounts ("dir" or "disk")

mount.QuotaMiB

uint32 Quota in MiB for provisioned directory volumes

mount.Tmpfs

bool Set for tmpfs mounts

mount.Disk

string Host path for disk images

mount.Format

string Disk format

mount.Fstype

string Inner filesystem type

mount.Readonly

bool Whether the mount is read-only

mount.Noexec

bool Whether direct execution from the mount is disabled

mount.Nosuid

bool Whether setuid/setgid elevation from files on the mount is ignored

mount.Nodev

bool Whether device files on the mount are ignored

mount.SizeMiB

uint32 Size limit for tmpfs / capacity for provisioned disk volumes

mount.StatVirtualization

StatVirtualization Per-mount stat-virtualization policy (bind / named only)

mount.HostPermissions

HostPermissions Per-mount host-permission propagation policy (bind / named only)

mount.Owner

*MountOwner Guest owner fallback for host files without a per-file stat override (bind / directory-backed named only)

mount.Kind()

Kind()

Which mount flavour this is

Returns

MountKind

Types

ErrPathEscape

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.

Returned by VolumeFs methods

if _, err := vfs.Read(ctx, "../etc/passwd"); errors.Is(err, m.ErrPathEscape) {
    log.Println("nice try")
}

VolumeConfig

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.

Mutated by VolumeOption

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

VolumeOption

type VolumeOption func(*VolumeConfig)

A functional option for CreateVolume. Constructed by the WithVolume* helpers.

Used by CreateVolume()

VolumeKind

type VolumeKind string

Describes the storage backing for a named volume.

Used by VolumeConfig · WithVolumeKind() · VolumeHandle.Kind()

Constant	Value	Description
`VolumeKindDir`	`"dir"`	Directory-backed named volume
`VolumeKindDisk`	`"disk"`	Raw ext4 disk-backed named volume

MountKind

type MountKind uint8

Discriminates between the four mount flavours. Inspect via mount.Kind().

Returned by MountConfig.Kind()

Constant	Description
`MountKindBind`	Host bind mount
`MountKindNamed`	Named persistent volume
`MountKindTmpfs`	In-memory tmpfs
`MountKindDisk`	Host disk image

MountOptions

Tuning struct for Mount.Bind, Mount.Named, and Mount.NamedWith. StatVirtualization, HostPermissions, and Owner are virtiofs-only; owner is rejected for disk-backed named volumes and when stat virtualization is off. Zero policy values preserve the conservative defaults (strict, private), while a nil owner keeps the runtime fallback identity.

Used by Mount.Bind() · Mount.Named() · Mount.NamedWith()

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)
`Owner`	`*MountOwner`	Paired guest uid/gid fallback for host files without a per-file override; nil keeps the runtime fallback

MountOwner

An inseparable guest ownership pair used by MountOptions.Owner. UID and GID may include zero; using a pointer to MountOwner keeps an unset owner distinct from root.

Owner: &m.MountOwner{UID: 1000, GID: 1000}

Field	Type	Description
`UID`	`uint32`	Guest user ID
`GID`	`uint32`	Guest group ID

NamedVolumeOptions

Tunes sandbox-time named volume provisioning for Mount.NamedWith.

Used by 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

TmpfsOptions

Tuning struct for Mount.Tmpfs.

Used by 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

DiskOptions

Tuning struct for Mount.Disk.

Used by 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

​Functions

​GetDefaultVolume()

​CreateVolume()

​GetVolume()

​ListVolumes()

​RemoveVolume()

​Volume

​v.Name()

​v.Path()

​v.FS()

​v.Remove()

​VolumeHandle

​h.Name()

​h.Path()

​h.Kind()

​h.QuotaMiB()

​h.UsedBytes()

​h.CapacityBytes()

​h.DiskFormat()

​h.DiskFstype()

​h.Labels()

​h.CreatedAt()

​h.FS()

​h.Remove()

​VolumeFs

​vfs.Root()

​vfs.Read()

​vfs.ReadString()

​vfs.Write()

​vfs.WriteString()

​vfs.Mkdir()

​vfs.Remove()

​vfs.RemoveAll()

​vfs.Exists()

​Options

​WithVolumeKind()

​WithVolumeSize()

​WithVolumeQuota()

​WithVolumeLabels()

​Mount

​Mount.Bind()

​Mount.Named()

​Mount.NamedWith()

​Mount.Tmpfs()

​Mount.Disk()

​MountConfig

​mount.Bind

​mount.Named

​mount.NamedMode

​mount.NamedKind

​mount.QuotaMiB

​mount.Tmpfs

​mount.Disk

​mount.Format

​mount.Fstype

​mount.Readonly

​mount.Noexec

​mount.Nosuid

​mount.Nodev

​mount.SizeMiB

​mount.StatVirtualization

​mount.HostPermissions

​mount.Owner

​mount.Kind()

​Types

​ErrPathEscape

​VolumeConfig

​VolumeOption

​VolumeKind

​MountKind

​MountOptions

​MountOwner

​NamedVolumeOptions

​TmpfsOptions

​DiskOptions

Functions

GetDefaultVolume()

CreateVolume()

GetVolume()

ListVolumes()

RemoveVolume()

Volume

v.Name()

v.Path()

v.FS()

v.Remove()

VolumeHandle

h.Name()

h.Path()

h.Kind()

h.QuotaMiB()

h.UsedBytes()

h.CapacityBytes()

h.DiskFormat()

h.DiskFstype()

h.Labels()

h.CreatedAt()

h.FS()

h.Remove()

VolumeFs

vfs.Root()

vfs.Read()

vfs.ReadString()

vfs.Write()

vfs.WriteString()

vfs.Mkdir()

vfs.Remove()

vfs.RemoveAll()

vfs.Exists()

Options

WithVolumeKind()

WithVolumeSize()

WithVolumeQuota()

WithVolumeLabels()

Mount

Mount.Bind()

Mount.Named()

Mount.NamedWith()

Mount.Tmpfs()

Mount.Disk()

MountConfig

mount.Bind

mount.Named

mount.NamedMode

mount.NamedKind

mount.QuotaMiB

mount.Tmpfs

mount.Disk

mount.Format

mount.Fstype

mount.Readonly

mount.Noexec

mount.Nosuid

mount.Nodev

mount.SizeMiB

mount.StatVirtualization

mount.HostPermissions

mount.Owner

mount.Kind()

Types

ErrPathEscape

VolumeConfig

VolumeOption

VolumeKind

MountKind

MountOptions

MountOwner

NamedVolumeOptions

TmpfsOptions

DiskOptions