/`. 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()
function
```go
func CreateVolume(ctx context.Context, name string, opts ...VolumeOption) (*Volume, error)
```
Create a named volume and return a populated [`*Volume`](#volume) with its name and host path. Configure the kind, quota, disk size, and labels with [option functions](#options). Returns `ErrVolumeAlreadyExists` if a volume with the given name already exists.
Parameters
ctxcontext.Context
Cancels the create.
Returns
Newly created volume with Name and Path.
```go
vol, err := m.CreateVolume(ctx, "docker-data",
m.WithVolumeKind(m.VolumeKindDisk),
m.WithVolumeSize(20*1024),
)
```
---
#### GetVolume()
function
```go
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.
Parameters
ctxcontext.Context
Cancels the lookup.
Returns
Metadata reference for the volume.
```go
h, err := m.GetVolume(ctx, "my-data")
fmt.Println(h.Path(), h.UsedBytes())
```
---
#### ListVolumes()
function
```go
func ListVolumes(ctx context.Context) ([]*VolumeHandle, error)
```
Return metadata for every named volume on the host.
Parameters
ctxcontext.Context
Cancels the listing.
Returns
All volume metadata handles.
```go
vols, err := m.ListVolumes(ctx)
for _, h := range vols {
fmt.Printf("%s — %s\n", h.Name(), h.Kind())
}
```
---
#### RemoveVolume()
function
```go
func RemoveVolume(ctx context.Context, name string) error
```
Delete a volume by name. All sandboxes referencing the volume must be stopped first.
Parameters
ctxcontext.Context
Cancels the removal.
```go
err := m.RemoveVolume(ctx, "my-data")
```
## Volume methods
A `Volume` is returned by [`CreateVolume`](#createvolume) and carries the volume's name and host path.
---
#### v.Name()
method
```go
func (v *Volume) Name() string
```
Return the volume's name.
---
#### v.Path()
method
```go
func (v *Volume) Path() string
```
Return the host filesystem path of the volume's data directory.
---
#### v.FS()
method
```go
func (v *Volume) FS() *VolumeFs
```
Return a [`*VolumeFs`](#volumefs) for direct host-side file operations on this volume.
Returns
Host-side filesystem accessor rooted at the volume directory.
```go
vfs := vol.FS()
err := vfs.WriteString("seed.txt", "hello")
```
---
#### v.Remove()
method
```go
func (v *Volume) Remove(ctx context.Context) error
```
Delete this volume. All sandboxes using it must be stopped. Equivalent to [`RemoveVolume(ctx, v.Name())`](#removevolume).
```go
err := vol.Remove(ctx)
```
## VolumeHandle methods
A `VolumeHandle` is the metadata reference returned by [`GetVolume`](#getvolume) and [`ListVolumes`](#listvolumes).
---
#### h.Name()
method
```go
func (h *VolumeHandle) Name() string
```
Return the volume name.
---
#### h.Path()
method
```go
func (h *VolumeHandle) Path() string
```
Return the host filesystem path of the volume's data directory.
---
#### h.Kind()
method
```go
func (h *VolumeHandle) Kind() VolumeKind
```
Return the volume storage kind: [`VolumeKindDir`](#volumekind) or [`VolumeKindDisk`](#volumekind).
Returns
Storage backing for the volume.
---
#### h.QuotaMiB()
method
```go
func (h *VolumeHandle) QuotaMiB() *uint32
```
Return the quota in MiB, or `nil` if unlimited.
---
#### h.UsedBytes()
method
```go
func (h *VolumeHandle) UsedBytes() uint64
```
Return the amount of space used by the volume, in bytes.
---
#### h.CapacityBytes()
method
```go
func (h *VolumeHandle) CapacityBytes() *uint64
```
Return the disk capacity in bytes for disk volumes, or `nil` for directory volumes.
---
#### h.DiskFormat()
method
```go
func (h *VolumeHandle) DiskFormat() *string
```
Return the disk image format for disk volumes, or `nil` for directory volumes.
---
#### h.DiskFstype()
method
```go
func (h *VolumeHandle) DiskFstype() *string
```
Return the inner filesystem type for disk volumes, or `nil` for directory volumes.
---
#### h.Labels()
method
```go
func (h *VolumeHandle) Labels() map[string]string
```
Return the labels attached to this volume.
---
#### h.CreatedAt()
method
```go
func (h *VolumeHandle) CreatedAt() time.Time
```
Return the creation timestamp, or the zero `time.Time` value if unknown.
---
#### h.FS()
method
```go
func (h *VolumeHandle) FS() *VolumeFs
```
Return a [`*VolumeFs`](#volumefs) for direct host-side file operations on this volume.
Returns
Host-side filesystem accessor rooted at the volume directory.
---
#### h.Remove()
method
```go
func (h *VolumeHandle) Remove(ctx context.Context) error
```
Delete this volume. All sandboxes using it must be stopped. Equivalent to [`RemoveVolume(ctx, h.Name())`](#removevolume).
## VolumeFs methods
Host-side filesystem operations on a named volume's data directory. Obtain via [`Volume.FS()`](#v-fs) or [`VolumeHandle.FS()`](#h-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`](#errpathescape).
```go
vfs := vol.FS()
if err := vfs.WriteString("seed.txt", "hello"); err != nil {
return err
}
content, err := vfs.ReadString("seed.txt")
```
---
#### vfs.Root()
method
```go
func (fs *VolumeFs) Root() string
```
Return the absolute host path of the volume's data directory.
---
#### vfs.Read()
method
```go
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
---
#### vfs.ReadString()
method
```go
func (fs *VolumeFs) ReadString(relPath string) (string, error)
```
Read a file and return its contents as a UTF-8 string.
---
#### vfs.Write()
method
```go
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()
method
```go
func (fs *VolumeFs) WriteString(relPath, content string) error
```
Write a string to a file. Created files use mode `0o644`.
---
#### vfs.Mkdir()
method
```go
func (fs *VolumeFs) Mkdir(relPath string) error
```
Create a directory and all missing parents (mode `0o755`).
---
#### vfs.Remove()
method
```go
func (fs *VolumeFs) Remove(relPath string) error
```
Delete a single file or empty directory.
---
#### vfs.RemoveAll()
method
```go
func (fs *VolumeFs) RemoveAll(relPath string) error
```
Delete a path and any children it contains (recursive).
---
#### vfs.Exists()
method
```go
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`](#createvolume), plus the [`Mount`](#mountconfig) factory helpers that attach a volume, bind mount, tmpfs, or disk image to a sandbox via [`WithMounts`](/sdk/go/sandbox#withmounts).
---
#### WithVolumeKind()
option
```go
func WithVolumeKind(kind VolumeKind) VolumeOption
```
Select the volume kind. Valid values are [`VolumeKindDir`](#volumekind) (default) and [`VolumeKindDisk`](#volumekind).
Parameters
Storage backing for the volume.
---
#### WithVolumeSize()
option
```go
func WithVolumeSize(mebibytes uint32) VolumeOption
```
Set disk volume capacity in MiB. Required when the kind is [`VolumeKindDisk`](#volumekind).
Parameters
mebibytesuint32
Disk capacity in MiB.
---
#### WithVolumeQuota()
option
```go
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()
option
```go
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()
option
```go
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. Returns a [`MountConfig`](#mountconfig) for use with [`WithMounts`](/sdk/go/sandbox#withmounts).
Parameters
hostPathstring
Host directory to bind.
Mount tuning (read-only, noexec, and so on).
```go
"/host": m.Mount.Bind("/var/data", m.MountOptions{Readonly: true})
```
---
#### Mount.Named()
option
```go
func (mountFactory) Named(name string, opts MountOptions) MountConfig
```
Mount an existing named persistent volume. The volume must already exist (create it with [`CreateVolume`](#createvolume)). Returns a [`MountConfig`](#mountconfig).
Parameters
namestring
Name of an existing volume.
```go
"/data": m.Mount.Named("my-data", m.MountOptions{})
```
---
#### Mount.NamedWith()
option
```go
func (mountFactory) NamedWith(name string, opts MountOptions, namedOpts NamedVolumeOptions) MountConfig
```
Mount a named persistent volume with explicit sandbox-time existence behavior. [`NamedVolumeOptions.Mode`](#namedvolumeoptions) 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
Provisioning mode, kind, size, and quota.
```go
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.Tmpfs()
option
```go
func (mountFactory) Tmpfs(opts TmpfsOptions) MountConfig
```
Mount an ephemeral in-memory filesystem. Contents are discarded when the sandbox stops. Returns a [`MountConfig`](#mountconfig).
Parameters
Size limit and mount flags.
```go
"/scratch": m.Mount.Tmpfs(m.TmpfsOptions{SizeMiB: 128})
```
---
#### Mount.Disk()
option
```go
func (mountFactory) Disk(hostPath string, opts DiskOptions) MountConfig
```
Mount a host disk image as a virtio-blk device. Supports raw, qcow2, and vmdk formats. Returns a [`MountConfig`](#mountconfig).
Parameters
hostPathstring
Host path to the disk image.
Format, inner filesystem, and mount flags.
```go
"/img": m.Mount.Disk("./data.qcow2", m.DiskOptions{
Format: "qcow2",
Fstype: "ext4",
Readonly: true,
})
```
## Types
---
### Volume
struct
A named persistent volume carrying its host-side path. Returned by [`CreateVolume`](#createvolume). Lookups via [`GetVolume`](#getvolume) and [`ListVolumes`](#listvolumes) yield richer [`VolumeHandle`](#volumehandle) values instead.
Returned by CreateVolume()
| Method | Returns | Description |
|--------|---------|-------------|
| [`Name()`](#v-name) | `string` | Volume name |
| [`Path()`](#v-path) | `string` | Host filesystem path of the data directory |
| [`FS()`](#v-fs) | [`*VolumeFs`](#volumefs) | Host-side filesystem accessor |
| [`Remove(ctx)`](#v-remove) | `error` | Delete this volume (all sandboxes using it must be stopped) |
---
### VolumeHandle
struct
Metadata reference for a named volume. Obtain via [`GetVolume`](#getvolume) or [`ListVolumes`](#listvolumes).
Returned by GetVolume() · ListVolumes()
| Method | Returns | Description |
|--------|---------|-------------|
| [`Name()`](#h-name) | `string` | Volume name |
| [`Path()`](#h-path) | `string` | Host filesystem path of the data directory |
| [`Kind()`](#h-kind) | [`VolumeKind`](#volumekind) | Volume kind: `VolumeKindDir` or `VolumeKindDisk` |
| [`QuotaMiB()`](#h-quotamib) | `*uint32` | Quota in MiB, or `nil` if unlimited |
| [`UsedBytes()`](#h-usedbytes) | `uint64` | Current disk usage in bytes |
| [`CapacityBytes()`](#h-capacitybytes) | `*uint64` | Disk capacity in bytes, or `nil` |
| [`DiskFormat()`](#h-diskformat) | `*string` | Disk image format, or `nil` |
| [`DiskFstype()`](#h-diskfstype) | `*string` | Disk filesystem type, or `nil` |
| [`Labels()`](#h-labels) | `map[string]string` | Metadata labels |
| [`CreatedAt()`](#h-createdat) | `time.Time` | Creation timestamp, zero value if unknown |
| [`FS()`](#h-fs) | [`*VolumeFs`](#volumefs) | Host-side filesystem accessor |
| [`Remove(ctx)`](#h-remove) | `error` | Delete this volume |
---
### VolumeFs
struct
Host-side filesystem operations on a volume's data directory. Obtain via [`Volume.FS()`](#v-fs) or [`VolumeHandle.FS()`](#h-fs). All path arguments are relative to the volume root; escaping paths are rejected with [`ErrPathEscape`](#errpathescape).
Returned by Volume.FS() · VolumeHandle.FS()
| Method | Returns | Description |
|--------|---------|-------------|
| [`Root()`](#vfs-root) | `string` | Absolute host path of the data directory |
| [`Read(relPath)`](#vfs-read) | `([]byte, error)` | Read file bytes |
| [`ReadString(relPath)`](#vfs-readstring) | `(string, error)` | Read file as a UTF-8 string |
| [`Write(relPath, data)`](#vfs-write) | `error` | Write bytes, creating or truncating |
| [`WriteString(relPath, content)`](#vfs-writestring) | `error` | Write a string |
| [`Mkdir(relPath)`](#vfs-mkdir) | `error` | Create a directory tree |
| [`Remove(relPath)`](#vfs-remove) | `error` | Delete a file or empty directory |
| [`RemoveAll(relPath)`](#vfs-removeall) | `error` | Recursive delete |
| [`Exists(relPath)`](#vfs-exists) | `(bool, error)` | Check for existence |
---
### ErrPathEscape
error
```go
var ErrPathEscape = errors.New("microsandbox: path escapes volume root")
```
Returned by every [`VolumeFs`](#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
```go
if _, err := vfs.Read("../etc/passwd"); errors.Is(err, m.ErrPathEscape) {
log.Println("nice try")
}
```
---
### VolumeConfig
struct
The config struct populated by [`VolumeOption`](#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`](#volumekind) | Volume kind (`VolumeKindDir` by default) |
| `SizeMiB` | `uint32` | Disk capacity in MiB for `VolumeKindDisk` |
| `Labels` | `map[string]string` | Metadata labels |
---
### VolumeOption
type
```go
type VolumeOption func(*VolumeConfig)
```
A functional option for [`CreateVolume`](#createvolume). Constructed by the [`WithVolume*`](#options) helpers.
Used by CreateVolume()
---
### VolumeKind
type
```go
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
struct
Discriminated mount configuration produced by the [`Mount`](#options) factory helpers and passed to [`WithMounts`](/sdk/go/sandbox#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`](#mountkind) | Which mount flavour this is |
---
### MountKind
type
```go
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
struct
Tuning struct for [`Mount.Bind`](#mount-bind), [`Mount.Named`](#mount-named), and [`Mount.NamedWith`](#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
struct
Tunes sandbox-time named volume provisioning for [`Mount.NamedWith`](#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
struct
Tuning struct for [`Mount.Tmpfs`](#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
struct
Tuning struct for [`Mount.Disk`](#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 |