> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Volumes

> Go SDK - Volume API reference

See [Volumes](/sandboxes/volumes) for usage examples and patterns.

## Volume

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

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

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

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

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

***

## Top-level functions

***

#### CreateVolume()

```go theme={null}
func CreateVolume(
    ctx context.Context,
    name string,
    opts ...VolumeOption,
) (*Volume, error)
```

Create a named volume.

**Parameters**

| Name | Type              | Description                                  |
| ---- | ----------------- | -------------------------------------------- |
| ctx  | `context.Context` | Cancels the create                           |
| name | `string`          | Volume name                                  |
| opts | `...VolumeOption` | Functional options — see [Options](#options) |

**Returns**

| Type                 | Description                                 |
| -------------------- | ------------------------------------------- |
| [`*Volume`](#volume) | Newly created volume with `Name` and `Path` |

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

***

#### GetVolume()

```go theme={null}
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()

```go theme={null}
func ListVolumes(ctx context.Context) ([]*VolumeHandle, error)
```

Return metadata for every named volume on the host.

***

#### RemoveVolume()

```go theme={null}
func RemoveVolume(ctx context.Context, name string) error
```

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

***

## Options

***

#### WithVolumeQuota()

```go theme={null}
func WithVolumeQuota(mebibytes uint32) VolumeOption
```

Set recorded quota metadata for directory volumes. Zero means unlimited.

***

#### WithVolumeKind()

```go theme={null}
func WithVolumeKind(kind VolumeKind) VolumeOption
```

Select the volume kind. Valid values are `VolumeKindDir` and `VolumeKindDisk`.

***

#### WithVolumeSize()

```go theme={null}
func WithVolumeSize(mebibytes uint32) VolumeOption
```

Set disk volume capacity in MiB. Required with `VolumeKindDisk`.

***

#### WithVolumeLabels()

```go theme={null}
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`](#getvolume) and [`ListVolumes`](#listvolumes).

| Method            | Returns                  | Description                                         |
| ----------------- | ------------------------ | --------------------------------------------------- |
| `Name()`          | `string`                 | Volume name                                         |
| `Path()`          | `string`                 | Host filesystem path of the volume's 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                              |
| `DiskFormat()`    | `*string`                | Disk image format                                   |
| `DiskFstype()`    | `*string`                | Disk filesystem type                                |
| `Labels()`        | `map[string]string`      | Metadata labels                                     |
| `CreatedAt()`     | `time.Time`              | Creation timestamp, zero value if unknown           |
| `FS()`            | [`*VolumeFs`](#volumefs) | Host-side filesystem accessor                       |
| `Remove(ctx)`     | `error`                  | Delete this volume                                  |

***

## VolumeFs

Host-side filesystem operations on a named volume's data directory. Obtained via [`Volume.FS()`](#volume) or [`VolumeHandle.FS()`](#volumehandle). 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 theme={null}
vfs := vol.FS()

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

***

#### Root()

```go theme={null}
func (fs *VolumeFs) Root() string
```

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

***

#### Read()

```go theme={null}
func (fs *VolumeFs) Read(relPath string) ([]byte, error)
```

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

***

#### ReadString()

```go theme={null}
func (fs *VolumeFs) ReadString(relPath string) (string, error)
```

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

***

#### Write()

```go theme={null}
func (fs *VolumeFs) Write(relPath string, data []byte) error
```

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

***

#### WriteString()

```go theme={null}
func (fs *VolumeFs) WriteString(relPath, content string) error
```

Write a string to a file.

***

#### Mkdir()

```go theme={null}
func (fs *VolumeFs) Mkdir(relPath string) error
```

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

***

#### Remove()

```go theme={null}
func (fs *VolumeFs) Remove(relPath string) error
```

Delete a single file or empty directory.

***

#### RemoveAll()

```go theme={null}
func (fs *VolumeFs) RemoveAll(relPath string) error
```

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

***

#### Exists()

```go theme={null}
func (fs *VolumeFs) Exists(relPath string) (bool, error)
```

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

***

#### ErrPathEscape

```go theme={null}
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`.

```go theme={null}
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`](/sdk/go/sandbox#withmounts) on the sandbox:

```go theme={null}
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`](#mountconfig). The `kind` discriminator is set internally; callers should always use these helpers rather than constructing the struct manually.

***

#### Mount.Bind()

```go theme={null}
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()

```go theme={null}
func (mountFactory) Named(name string, opts MountOptions) MountConfig
```

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

***

#### Mount.NamedWith()

```go theme={null}
func (mountFactory) NamedWith(name string, opts MountOptions, namedOpts NamedVolumeOptions) MountConfig
```

Mount a named persistent volume with explicit sandbox-time existence behavior. `NamedVolumeOptions.Mode` accepts `"existing"` (default), `"create"`, or `"ensure-exists"`. `NamedVolumeOptions.Kind` accepts `"dir"` (default) or `"disk"`.

```go theme={null}
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,
        }),
    }),
)
```

`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. The ensure-exists mode errors when the existing volume has a different kind, quota, or capacity than the requested configuration; it does not mutate existing volume metadata.

**NamedVolumeOptions**

| Field      | Description                                                                    |
| ---------- | ------------------------------------------------------------------------------ |
| `Mode`     | `"existing"`, `"create"`, or `"ensure-exists"`; empty means `"existing"`       |
| `Kind`     | `"dir"` or `"disk"`; empty means `"dir"`                                       |
| `SizeMiB`  | Disk capacity in MiB; required when creating or ensuring a missing disk volume |
| `QuotaMiB` | Directory volume quota in MiB                                                  |

***

#### Mount.Tmpfs()

```go theme={null}
func (mountFactory) Tmpfs(opts TmpfsOptions) MountConfig
```

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

***

#### Mount.Disk()

```go theme={null}
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`.

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

### TmpfsOptions

Tuning struct for `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`.

| Field    | Type     | Description                                                                            |
| -------- | -------- | -------------------------------------------------------------------------------------- |
| Format   | `string` | Format hint (`"raw"`, `"qcow2"`, `"vmdk"`). Optional; defaults from the file extension |
| 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                                                       |

### MountConfig

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

| Field    | Type     | Description                                                                  |
| -------- | -------- | ---------------------------------------------------------------------------- |
| Bind     | `string` | Host path for bind mounts                                                    |
| Named    | `string` | Volume name for named mounts                                                 |
| 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 privilege elevation from files on the mount is ignored |
| Nodev    | `bool`   | Whether device files on the mount are ignored                                |
| SizeMiB  | `uint32` | Size limit for tmpfs mounts                                                  |

### MountKind

```go theme={null}
type MountKind uint8
```

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

Inspect via `mount.Kind()`.

***

## Types

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

| Field    | Type                | Description                                    |
| -------- | ------------------- | ---------------------------------------------- |
| Kind     | `VolumeKind`        | Volume kind (`VolumeKindDir` by default)       |
| QuotaMiB | `uint32`            | Maximum storage size in MiB (zero = unlimited) |
| SizeMiB  | `uint32`            | Disk capacity in MiB for `VolumeKindDisk`      |
| Labels   | `map[string]string` | Metadata labels                                |

### VolumeOption

```go theme={null}
type VolumeOption func(*VolumeConfig)
```

A functional option for [`CreateVolume`](#createvolume).