Volumes

See Volumes for usage examples and patterns.

Volume

Named volumes are managed by microsandbox and stored at ~/.microsandbox/volumes/<name>/. They persist independently of any sandbox.

vol, err := m.CreateVolume(ctx, "my-data",
    m.WithVolumeQuota(100),
    m.WithVolumeLabels(map[string]string{"env": "prod"}),
)

There is no Rust-side resource to release — Remove deletes the on-disk state and the DB record.

Top-level functions

CreateVolume()

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

Create a named volume.

Parameters

Returns

Returns ErrVolumeAlreadyExists if a volume with the given name already exists.

GetVolume()

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

Look up a volume by name and return its metadata.

Returns ErrVolumeNotFound if no such volume exists.

ListVolumes()

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

Return metadata for every named volume on the host.

RemoveVolume()

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

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

Options

WithVolumeQuota()

func WithVolumeQuota(mebibytes uint32) VolumeOption

Set the volume's maximum storage size in MiB. Zero means unlimited.

WithVolumeLabels()

func WithVolumeLabels(labels map[string]string) VolumeOption

Attach key-value labels to the volume. Called repeatedly, maps merge; later keys overwrite earlier ones.

VolumeHandle

Metadata reference returned by GetVolume and ListVolumes.

VolumeFs

Host-side filesystem operations on a named volume's data directory. Obtained 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")

Root()

func (fs *VolumeFs) Root() string

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

Read()

func (fs *VolumeFs) Read(relPath string) ([]byte, error)

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

ReadString()

func (fs *VolumeFs) ReadString(relPath string) (string, error)

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

Write()

func (fs *VolumeFs) Write(relPath string, data []byte) error

Write data to a file, creating or truncating it. Created files use mode 0o644.

WriteString()

func (fs *VolumeFs) WriteString(relPath, content string) error

Write a string to a file.

Mkdir()

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

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

Remove()

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

Delete a single file or empty directory.

RemoveAll()

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

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

Exists()

func (fs *VolumeFs) Exists(relPath string) (bool, error)

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

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.

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

Mounts

Volume mounts attach a host directory, named volume, tmpfs, or disk image to a guest path. Configure them via WithMounts on the sandbox:

sb, err := m.CreateSandbox(ctx, "worker",
    m.WithImage("alpine"),
    m.WithMounts(map[string]m.MountConfig{
        "/host":    m.Mount.Bind("/var/data", m.MountOptions{}),
        "/data":    m.Mount.Named("my-data", m.MountOptions{}),
        "/scratch": m.Mount.Tmpfs(m.TmpfsOptions{SizeMiB: 128}),
        "/img":     m.Mount.Disk("./data.qcow2", m.DiskOptions{
            Format:   "qcow2",
            Fstype:   "ext4",
            Readonly: true,
        }),
    }),
)

Each Mount.X(...) helper returns a MountConfig. The kind discriminator is set internally; callers should always use these helpers rather than constructing the struct manually.

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.

Mount.Named()

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

Mount a named persistent volume. The volume must already exist (create it with CreateVolume).

Mount.Tmpfs()

func (mountFactory) Tmpfs(opts TmpfsOptions) MountConfig

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

Mount.Disk()

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

Mount a host disk image as a virtio-blk device. Supports raw, qcow2, and vmdk formats.

Mount option types

MountOptions

Tuning struct for Mount.Bind and Mount.Named.

TmpfsOptions

Tuning struct for Mount.Tmpfs.

DiskOptions

Tuning struct for Mount.Disk.

MountConfig

Discriminated mount configuration produced by Mount helpers. Inspect the kind via Kind().

MountKind

type MountKind uint8

Inspect via mount.Kind().

Types

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.

VolumeOption

type VolumeOption func(*VolumeConfig)

A functional option for CreateVolume.