---
title: Volumes
description: Go SDK - Volume API reference
---

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](/sandboxes/volumes) for usage examples and patterns.

<p className="msb-label" id="typical-flow">Typical flow</p>

```go
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(ctx, "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

#### <span className="msb-recv"></span><span className="msb-hn">GetDefaultVolume()</span>

```go
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.

```go
volume, err := m.GetDefaultVolume(ctx)
err = volume.FS().WriteString(ctx, "customers/acme.json", `{"active":true}`)
contents, err := volume.FS().ReadString(ctx, "customers/acme.json")
```

#### <span className="msb-recv"></span><span className="msb-hn">CreateVolume()</span>

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

<Accordion title="Example">

```go
vol, err := m.CreateVolume(ctx, "docker-data",
    m.WithVolumeKind(m.VolumeKindDisk),
    m.WithVolumeSize(20*1024),
)
```

</Accordion>

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.

<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 create.</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 className="msb-param">
    <div className="msb-param-key"><code>opts</code><a className="msb-type" href="#volumeoption">...VolumeOption</a></div>
    <div className="msb-param-desc">Functional options, see <a href="#options">Options</a>.</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="#volume">*Volume</a></div>
    <div className="msb-param-desc">Newly created volume with <code>Name</code> and <code>Path</code>.</div>
  </div>
</div>

#### <span className="msb-recv"></span><span className="msb-hn">GetVolume()</span>

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

<Accordion title="Example">

```go
h, err := m.GetVolume(ctx, "my-data")
fmt.Println(h.Path(), h.UsedBytes())
```

</Accordion>

Look up a volume by name and return its metadata. Returns `ErrVolumeNotFound` if no such volume exists.

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

<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">Metadata reference for the volume.</div>
  </div>
</div>

#### <span className="msb-recv"></span><span className="msb-hn">ListVolumes()</span>

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

<Accordion title="Example">

```go
vols, err := m.ListVolumes(ctx)
for _, h := range vols {
    fmt.Printf("%s - %s\n", h.Name(), h.Kind())
}
```

</Accordion>

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>

#### <span className="msb-recv"></span><span className="msb-hn">RemoveVolume()</span>

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

<Accordion title="Example">

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

</Accordion>

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>

## Volume methods

A `Volume` is returned by [`CreateVolume`](#createvolume) and carries the volume's name and host path.

#### <span className="msb-recv">v.</span><span className="msb-hn">Name()</span>

```go
func (v *Volume) Name() string
```

Return the volume's name.

#### <span className="msb-recv">v.</span><span className="msb-hn">Path()</span>

```go
func (v *Volume) Path() string
```

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

#### <span className="msb-recv">v.</span><span className="msb-hn">FS()</span>

```go
func (v *Volume) FS() *VolumeFs
```

<Accordion title="Example">

```go
vfs := vol.FS()
err := vfs.WriteString(ctx, "seed.txt", "hello")
```

</Accordion>

Return a [`*VolumeFs`](#volumefs) for direct file operations. Local calls use the managed host directory; Cloud calls use the authenticated volume API.

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#volumefs">*VolumeFs</a></div>
    <div className="msb-param-desc">Filesystem accessor rooted at the volume directory.</div>
  </div>
</div>

#### <span className="msb-recv">v.</span><span className="msb-hn">Remove()</span>

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

<Accordion title="Example">

```go
err := vol.Remove(ctx)
```

</Accordion>

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

## VolumeHandle methods

A `VolumeHandle` is the metadata reference returned by [`GetVolume`](#getvolume) and [`ListVolumes`](#listvolumes).

#### <span className="msb-recv">h.</span><span className="msb-hn">Name()</span>

```go
func (h *VolumeHandle) Name() string
```

Return the volume name.

#### <span className="msb-recv">h.</span><span className="msb-hn">Path()</span>

```go
func (h *VolumeHandle) Path() string
```

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

#### <span className="msb-recv">h.</span><span className="msb-hn">Kind()</span>

```go
func (h *VolumeHandle) Kind() VolumeKind
```

Return the volume storage kind: [`VolumeKindDir`](#volumekind) or [`VolumeKindDisk`](#volumekind).

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#volumekind">VolumeKind</a></div>
    <div className="msb-param-desc">Storage backing for the volume.</div>
  </div>
</div>

#### <span className="msb-recv">h.</span><span className="msb-hn">QuotaMiB()</span>

```go
func (h *VolumeHandle) QuotaMiB() *uint32
```

Return the quota in MiB, or `nil` if unlimited.

#### <span className="msb-recv">h.</span><span className="msb-hn">UsedBytes()</span>

```go
func (h *VolumeHandle) UsedBytes() uint64
```

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

#### <span className="msb-recv">h.</span><span className="msb-hn">CapacityBytes()</span>

```go
func (h *VolumeHandle) CapacityBytes() *uint64
```

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

#### <span className="msb-recv">h.</span><span className="msb-hn">DiskFormat()</span>

```go
func (h *VolumeHandle) DiskFormat() *string
```

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

#### <span className="msb-recv">h.</span><span className="msb-hn">DiskFstype()</span>

```go
func (h *VolumeHandle) DiskFstype() *string
```

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

#### <span className="msb-recv">h.</span><span className="msb-hn">Labels()</span>

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

Return the labels attached to this volume.

#### <span className="msb-recv">h.</span><span className="msb-hn">CreatedAt()</span>

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

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

#### <span className="msb-recv">h.</span><span className="msb-hn">FS()</span>

```go
func (h *VolumeHandle) FS() *VolumeFs
```

Return a [`*VolumeFs`](#volumefs) for direct host-side file operations on this volume.

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#volumefs">*VolumeFs</a></div>
    <div className="msb-param-desc">Filesystem accessor rooted at the volume directory.</div>
  </div>
</div>

#### <span className="msb-recv">h.</span><span className="msb-hn">Remove()</span>

```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

Filesystem operations on a volume's data directory. Obtain via [`Volume.FS()`](#v-fs) or [`VolumeHandle.FS()`](#h-fs). Local operations run directly on the host filesystem, while Cloud operations use the authenticated Cloud API. No running sandbox or agent protocol is required.

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

Every operation except `Root` accepts a `context.Context`. Cloud operations use it to cancel or time out the underlying network request; local operations check it before accessing the host filesystem.

```go
vfs := vol.FS()

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

#### <span className="msb-recv">vfs.</span><span className="msb-hn">Root()</span>

```go
func (fs *VolumeFs) Root() string
```

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

#### <span className="msb-recv">vfs.</span><span className="msb-hn">Read()</span>

```go
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>

#### <span className="msb-recv">vfs.</span><span className="msb-hn">ReadString()</span>

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

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

#### <span className="msb-recv">vfs.</span><span className="msb-hn">Write()</span>

```go
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`.

<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 className="msb-param">
    <div className="msb-param-key"><code>data</code><span className="msb-type">[]byte</span></div>
    <div className="msb-param-desc">Bytes to write.</div>
  </div>
</div>

#### <span className="msb-recv">vfs.</span><span className="msb-hn">WriteString()</span>

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

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

#### <span className="msb-recv">vfs.</span><span className="msb-hn">Mkdir()</span>

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

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

#### <span className="msb-recv">vfs.</span><span className="msb-hn">Remove()</span>

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

Delete a single file or empty directory.

#### <span className="msb-recv">vfs.</span><span className="msb-hn">RemoveAll()</span>

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

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

#### <span className="msb-recv">vfs.</span><span className="msb-hn">Exists()</span>

```go
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>

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

#### <span className="msb-recv"></span><span className="msb-hn">WithVolumeKind()</span>

```go
func WithVolumeKind(kind VolumeKind) VolumeOption
```

Select the volume kind. Valid values are [`VolumeKindDir`](#volumekind) (default) and [`VolumeKindDisk`](#volumekind).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>kind</code><a className="msb-type" href="#volumekind">VolumeKind</a></div>
    <div className="msb-param-desc">Storage backing for the volume.</div>
  </div>
</div>

#### <span className="msb-recv"></span><span className="msb-hn">WithVolumeSize()</span>

```go
func WithVolumeSize(mebibytes uint32) VolumeOption
```

Set disk volume capacity in MiB. Required when the kind is [`VolumeKindDisk`](#volumekind).

<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">Disk capacity in MiB.</div>
  </div>
</div>

#### <span className="msb-recv"></span><span className="msb-hn">WithVolumeQuota()</span>

```go
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>

#### <span className="msb-recv"></span><span className="msb-hn">WithVolumeLabels()</span>

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

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

#### <span className="msb-recv">Mount.</span><span className="msb-hn">Bind()</span>

```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. Set [`MountOptions.QuotaMiB`](#mountoptions) to bound how much the guest may write beyond the host directory's existing contents, overriding the runtime's protective default. Returns a [`MountConfig`](#mountconfig) for use with [`WithMounts`](/sdk/go/sandbox#withmounts).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>hostPath</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Host directory to bind.</div>
  </div>
  <div className="msb-param">
    <div className="msb-param-key"><code>opts</code><a className="msb-type" href="#mountoptions">MountOptions</a></div>
    <div className="msb-param-desc">Mount tuning (read-only, noexec, and so on).</div>
  </div>
</div>

<Accordion title="Example">

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

</Accordion>

---

#### <span className="msb-recv">Mount.</span><span className="msb-hn">Named()</span>

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

<Accordion title="Example">

```go
"/data": m.Mount.Named("my-data", m.MountOptions{})
```

</Accordion>

Mount an existing named persistent volume. The volume must already exist (create it with [`CreateVolume`](#createvolume)). Returns a [`MountConfig`](#mountconfig).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>name</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Name of an existing volume.</div>
  </div>
  <div className="msb-param">
    <div className="msb-param-key"><code>opts</code><a className="msb-type" href="#mountoptions">MountOptions</a></div>
    <div className="msb-param-desc">Mount tuning.</div>
  </div>
</div>

#### <span className="msb-recv">Mount.</span><span className="msb-hn">NamedWith()</span>

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

<Accordion title="Example">

```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,
        }),
    }),
)
```

</Accordion>

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.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <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 className="msb-param">
    <div className="msb-param-key"><code>opts</code><a className="msb-type" href="#mountoptions">MountOptions</a></div>
    <div className="msb-param-desc">Mount tuning.</div>
  </div>
  <div className="msb-param">
    <div className="msb-param-key"><code>namedOpts</code><a className="msb-type" href="#namedvolumeoptions">NamedVolumeOptions</a></div>
    <div className="msb-param-desc">Provisioning mode, kind, size, and quota.</div>
  </div>
</div>

#### <span className="msb-recv">Mount.</span><span className="msb-hn">Tmpfs()</span>

```go
func (mountFactory) Tmpfs(opts TmpfsOptions) MountConfig
```

<Accordion title="Example">

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

</Accordion>

Mount an ephemeral in-memory filesystem. Contents are discarded when the sandbox stops. Returns a [`MountConfig`](#mountconfig).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>opts</code><a className="msb-type" href="#tmpfsoptions">TmpfsOptions</a></div>
    <div className="msb-param-desc">Size limit and mount flags.</div>
  </div>
</div>

#### <span className="msb-recv">Mount.</span><span className="msb-hn">Disk()</span>

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

<Accordion title="Example">

```go
"/img": m.Mount.Disk("./data.qcow2", m.DiskOptions{
    Format:   "qcow2",
    Fstype:   "ext4",
    Readonly: true,
})
```

</Accordion>

Mount a host disk image as a virtio-blk device. Supports raw, qcow2, and vmdk formats. Returns a [`MountConfig`](#mountconfig).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>hostPath</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Host path to the disk image.</div>
  </div>
  <div className="msb-param">
    <div className="msb-param-key"><code>opts</code><a className="msb-type" href="#diskoptions">DiskOptions</a></div>
    <div className="msb-param-desc">Format, inner filesystem, and mount flags.</div>
  </div>
</div>

## Types

### Volume

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.

<p className="msb-backref">Returned by <a href="#createvolume">CreateVolume()</a></p>

| 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) | Filesystem accessor |
| [`Remove(ctx)`](#v-remove) | `error` | Delete this volume (all sandboxes using it must be stopped) |

### VolumeHandle

Metadata reference for a named volume. Obtain via [`GetVolume`](#getvolume) or [`ListVolumes`](#listvolumes).

<p className="msb-backref">Returned by <a href="#getvolume">GetVolume()</a> · <a href="#listvolumes">ListVolumes()</a></p>

| 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) | Filesystem accessor |
| [`Remove(ctx)`](#h-remove) | `error` | Delete this volume |

### VolumeFs

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

<p className="msb-backref">Returned by <a href="#v-fs">Volume.FS()</a> · <a href="#h-fs">VolumeHandle.FS()</a></p>

| Method | Returns | Description |
|--------|---------|-------------|
| [`Root()`](#vfs-root) | `string` | Absolute host path of the data directory |
| [`Read(ctx, relPath)`](#vfs-read) | `([]byte, error)` | Read file bytes |
| [`ReadString(ctx, relPath)`](#vfs-readstring) | `(string, error)` | Read file as a UTF-8 string |
| [`Write(ctx, relPath, data)`](#vfs-write) | `error` | Write bytes, creating or truncating |
| [`WriteString(ctx, relPath, content)`](#vfs-writestring) | `error` | Write a string |
| [`Mkdir(ctx, relPath)`](#vfs-mkdir) | `error` | Create a directory tree |
| [`Remove(ctx, relPath)`](#vfs-remove) | `error` | Delete a file or empty directory |
| [`RemoveAll(ctx, relPath)`](#vfs-removeall) | `error` | Recursive delete |
| [`Exists(ctx, relPath)`](#vfs-exists) | `(bool, error)` | Check for existence |

### ErrPathEscape

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

<p className="msb-backref">Returned by <a href="#volumefs">VolumeFs</a> methods</p>

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

### VolumeConfig

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.

<p className="msb-backref">Mutated by <a href="#volumeoption">VolumeOption</a></p>

| 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

```go
type VolumeOption func(*VolumeConfig)
```

A functional option for [`CreateVolume`](#createvolume). Constructed by the [`WithVolume*`](#options) helpers.

<p className="msb-backref">Used by <a href="#createvolume">CreateVolume()</a></p>

### VolumeKind

```go
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 |

### MountConfig

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

<p className="msb-backref">Returned by <a href="#mount-bind">Mount.Bind()</a> · <a href="#mount-named">Mount.Named()</a> · <a href="#mount-namedwith">Mount.NamedWith()</a> · <a href="#mount-tmpfs">Mount.Tmpfs()</a> · <a href="#mount-disk">Mount.Disk()</a></p>

| 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

```go
type MountKind uint8
```

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

<p className="msb-backref">Returned by <a href="#mountconfig">MountConfig.Kind()</a></p>

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

<p className="msb-backref">Used by <a href="#mount-bind">Mount.Bind()</a> · <a href="#mount-named">Mount.Named()</a> · <a href="#mount-namedwith">Mount.NamedWith()</a></p>

| 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`](#namedvolumeoptions)) |
| `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`](#mount-namedwith).

<p className="msb-backref">Used by <a href="#mount-namedwith">Mount.NamedWith()</a></p>

| 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`](#mount-tmpfs).

<p className="msb-backref">Used by <a href="#mount-tmpfs">Mount.Tmpfs()</a></p>

| 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`](#mount-disk).

<p className="msb-backref">Used by <a href="#mount-disk">Mount.Disk()</a></p>

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