Volumes - microsandbox

Create and manage named persistent volumes, read and write their data directly on the host, and attach them (or bind mounts, tmpfs, and disk images) to sandboxes. See Volumes for usage examples and patterns.

Typical flow

import m "github.com/superradcompany/microsandbox/sdk/go"

vol, err := m.CreateVolume(ctx, "my-data",         // 1. create a named volume
    m.WithVolumeQuota(64),
    m.WithVolumeLabels(map[string]string{"env": "prod"}),
)

vfs := vol.FS()                                    // 2. seed it from the host
err = vfs.WriteString("seed.txt", "hello")

sb, err := m.CreateSandbox(ctx, "worker",          // 3. attach it to a sandbox
    m.WithImage("alpine"),
    m.WithMounts(map[string]m.MountConfig{
        "/data": m.Mount.Named("my-data", m.MountOptions{}),
    }),
)

Named volumes are managed by microsandbox and stored by default under ~/.microsandbox/volumes/<name>/. They persist independently of any sandbox. There is no Rust-side resource to release: Remove deletes the on-disk state and the DB record.

Functions

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 methods

A Volume is returned by CreateVolume and carries the volume’s name and host path.

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("seed.txt", "hello")

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

Returns

*VolumeFs

Host-side 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 methods

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

Host-side 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 methods

Host-side filesystem operations on a named volume’s data directory. Obtain via Volume.FS() or VolumeHandle.FS(). These operations run directly on the host filesystem: no running sandbox is required and no agent protocol is involved. All path arguments are relative to the volume root. Paths that would escape the root via .., absolute components, or stray symlink chains are rejected with ErrPathEscape.

vfs := vol.FS()

if err := vfs.WriteString("seed.txt", "hello"); err != nil {
    return err
}
content, err := vfs.ReadString("seed.txt")

vfs.Root()

func (fs *VolumeFs) Root() string

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

vfs.Read()

func (fs *VolumeFs) Read(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(relPath string) (string, error)

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

vfs.Write()

func (fs *VolumeFs) Write(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(relPath, content string) error

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

vfs.Mkdir()

func (fs *VolumeFs) Mkdir(relPath string) error

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

vfs.Remove()

func (fs *VolumeFs) Remove(relPath string) error

Delete a single file or empty directory.

vfs.RemoveAll()

func (fs *VolumeFs) RemoveAll(relPath string) error

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

vfs.Exists()

func (fs *VolumeFs) Exists(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.Bind()

func (mountFactory) Bind(hostPath string, opts MountOptions) MountConfig

Example

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

Bind-mount a host directory into the sandbox. Changes in the guest are reflected on the host and vice versa. Returns a MountConfig for use with WithMounts.

Parameters

hostPathstring

Host directory to bind.

optsMountOptions

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

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.

Types

Volume

A named persistent volume carrying its host-side path. Returned by CreateVolume. Lookups via GetVolume and ListVolumes yield richer VolumeHandle values instead.

Returned by CreateVolume()

Method	Returns	Description
`Name()`	`string`	Volume name
`Path()`	`string`	Host filesystem path of the data directory
`FS()`	`*VolumeFs`	Host-side filesystem accessor
`Remove(ctx)`	`error`	Delete this volume (all sandboxes using it must be stopped)

VolumeHandle

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

Returned by GetVolume() · ListVolumes()

Method	Returns	Description
`Name()`	`string`	Volume name
`Path()`	`string`	Host filesystem path of the data directory
`Kind()`	`VolumeKind`	Volume kind: `VolumeKindDir` or `VolumeKindDisk`
`QuotaMiB()`	`*uint32`	Quota in MiB, or `nil` if unlimited
`UsedBytes()`	`uint64`	Current disk usage in bytes
`CapacityBytes()`	`*uint64`	Disk capacity in bytes, or `nil`
`DiskFormat()`	`*string`	Disk image format, or `nil`
`DiskFstype()`	`*string`	Disk filesystem type, or `nil`
`Labels()`	`map[string]string`	Metadata labels
`CreatedAt()`	`time.Time`	Creation timestamp, zero value if unknown
`FS()`	`*VolumeFs`	Host-side filesystem accessor
`Remove(ctx)`	`error`	Delete this volume

VolumeFs

Host-side filesystem operations on a volume’s data directory. Obtain via Volume.FS() or VolumeHandle.FS(). All path arguments are relative to the volume root; escaping paths are rejected with ErrPathEscape.

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

Method	Returns	Description
`Root()`	`string`	Absolute host path of the data directory
`Read(relPath)`	`([]byte, error)`	Read file bytes
`ReadString(relPath)`	`(string, error)`	Read file as a UTF-8 string
`Write(relPath, data)`	`error`	Write bytes, creating or truncating
`WriteString(relPath, content)`	`error`	Write a string
`Mkdir(relPath)`	`error`	Create a directory tree
`Remove(relPath)`	`error`	Delete a file or empty directory
`RemoveAll(relPath)`	`error`	Recursive delete
`Exists(relPath)`	`(bool, error)`	Check for existence

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

MountConfig

Discriminated mount configuration produced by the Mount factory helpers and passed to WithMounts. Construct it with the factory rather than by hand: the factory sets the internal kind discriminator and enforces the mutually-exclusive flavours. Inspect the flavour via Kind().

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

Field	Type	Description
`Bind`	`string`	Host path for bind mounts
`Named`	`string`	Volume name for named mounts
`NamedMode`	`string`	Provisioning mode for named mounts (`"existing"`, `"create"`, `"ensure-exists"`)
`NamedKind`	`string`	Kind for provisioned named mounts (`"dir"` or `"disk"`)
`QuotaMiB`	`uint32`	Quota in MiB for provisioned directory volumes
`Tmpfs`	`bool`	Set for tmpfs mounts
`Disk`	`string`	Host path for disk images
`Format`	`string`	Disk format
`Fstype`	`string`	Inner filesystem type
`Readonly`	`bool`	Whether the mount is read-only
`Noexec`	`bool`	Whether direct execution from the mount is disabled
`Nosuid`	`bool`	Whether setuid/setgid elevation from files on the mount is ignored
`Nodev`	`bool`	Whether device files on the mount are ignored
`SizeMiB`	`uint32`	Size limit for tmpfs / capacity for provisioned disk volumes
`StatVirtualization`	`StatVirtualization`	Per-mount stat-virtualization policy (bind / named only)
`HostPermissions`	`HostPermissions`	Per-mount host-permission propagation policy (bind / named only)

Method	Returns	Description
`Kind()`	`MountKind`	Which mount flavour this is

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

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
`StatVirtualization`	`StatVirtualization`	Per-mount stat-virtualization policy (virtiofs only)
`HostPermissions`	`HostPermissions`	Per-mount host-permission propagation policy (virtiofs only)

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

​CreateVolume()

​GetVolume()

​ListVolumes()

​RemoveVolume()

​Volume methods

​v.Name()

​v.Path()

​v.FS()

​v.Remove()

​VolumeHandle methods

​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 methods

​vfs.Root()

​vfs.Read()

​vfs.ReadString()

​vfs.Write()

​vfs.WriteString()

​vfs.Mkdir()

​vfs.Remove()

​vfs.RemoveAll()

​vfs.Exists()

​Options

​WithVolumeKind()

​WithVolumeSize()

​WithVolumeQuota()

​WithVolumeLabels()

​Mount.Bind()

​Mount.Named()

​Mount.NamedWith()

​Mount.Tmpfs()

​Mount.Disk()

​Types

​Volume

​VolumeHandle

​VolumeFs

​ErrPathEscape

​VolumeConfig

​VolumeOption

​VolumeKind

​MountConfig

​MountKind

​MountOptions

​NamedVolumeOptions

​TmpfsOptions

​DiskOptions

Functions

CreateVolume()

GetVolume()

ListVolumes()

RemoveVolume()

Volume methods

v.Name()

v.Path()

v.FS()

v.Remove()

VolumeHandle methods

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 methods

vfs.Root()

vfs.Read()

vfs.ReadString()

vfs.Write()

vfs.WriteString()

vfs.Mkdir()

vfs.Remove()

vfs.RemoveAll()

vfs.Exists()

Options

WithVolumeKind()

WithVolumeSize()

WithVolumeQuota()

WithVolumeLabels()

Mount.Bind()

Mount.Named()

Mount.NamedWith()

Mount.Tmpfs()

Mount.Disk()

Types

Volume

VolumeHandle

VolumeFs

ErrPathEscape

VolumeConfig

VolumeOption

VolumeKind

MountConfig

MountKind

MountOptions

NamedVolumeOptions

TmpfsOptions

DiskOptions