> ## Documentation Index
> Fetch the complete documentation index at: https://microsanbox-staging-appcypher-sdk-runtime-bootstrap.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Volumes

> Go SDK - Volume API reference

Create, manage, and mount named volumes. See [Volumes](/sandboxes/volumes) for usage examples.

## Functions

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

<Tooltip tip="Available only on microsandbox cloud; the local backend has no default volume."><span className="msb-badge-cloud">Cloud-only <Icon icon="circle-info" size={11} /></span></Tooltip>

```go theme={null}
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 theme={null}
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 className="msb-hn">CreateVolume()</span>

<Tooltip tip="Microsandbox cloud creates directory volumes only; size is unavailable and quota must be a nonzero whole number of GiB."><span className="msb-badge-limited">Limited on cloud <Icon icon="circle-info" size={11} /></span></Tooltip>

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

<Accordion title="Example">
  ```go theme={null}
  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 className="msb-hn">GetVolume()</span>

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

<Accordion title="Example">
  ```go theme={null}
  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 className="msb-hn">ListVolumes()</span>

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

<Accordion title="Example">
  ```go theme={null}
  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 className="msb-hn">RemoveVolume()</span>

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

<Accordion title="Example">
  ```go theme={null}
  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

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

A named persistent volume.

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

```go theme={null}
func (v *Volume) Name() string
```

Return the volume's name.

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

<Tooltip tip="Only local volumes expose a path on the computer running the SDK."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

```go theme={null}
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 theme={null}
func (v *Volume) FS() *VolumeFs
```

<Accordion title="Example">
  ```go theme={null}
  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 theme={null}
func (v *Volume) Remove(ctx context.Context) error
```

<Accordion title="Example">
  ```go theme={null}
  err := vol.Remove(ctx)
  ```
</Accordion>

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

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

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 theme={null}
func (h *VolumeHandle) Name() string
```

Return the volume name.

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

<Tooltip tip="Only local volume handles expose a path on the computer running the SDK."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

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

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

Host-side filesystem operations for a named volume.

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

```go theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 className="msb-hn">WithVolumeKind()</span>

<Tooltip tip="Disk-kind volumes are not available on microsandbox cloud; use a directory-backed named volume."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

```go theme={null}
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 className="msb-hn">WithVolumeSize()</span>

<Tooltip tip="Disk-kind volumes are not available on microsandbox cloud; use a directory-backed named volume."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

```go theme={null}
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 className="msb-hn">WithVolumeQuota()</span>

<Tooltip tip="On microsandbox cloud, quota must be a nonzero whole number of GiB."><span className="msb-badge-limited">Limited on cloud <Icon icon="circle-info" size={11} /></span></Tooltip>

```go theme={null}
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 className="msb-hn">WithVolumeLabels()</span>

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

## Mount

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

<Tooltip tip="On microsandbox cloud, the host path resolves against your organization's host volume, not the computer running the SDK."><span className="msb-badge-limited">Limited on cloud <Icon icon="circle-info" size={11} /></span></Tooltip>

```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. 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 theme={null}
  "/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 theme={null}
func (mountFactory) Named(name string, opts MountOptions) MountConfig
```

<Accordion title="Example">
  ```go theme={null}
  "/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>

<Tooltip tip="On microsandbox cloud, create the named volume before mounting; create-on-mount, disk-kind, and size are unavailable."><span className="msb-badge-limited">Limited on cloud <Icon icon="circle-info" size={11} /></span></Tooltip>

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

<Accordion title="Example">
  ```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,
          }),
      }),
  )
  ```
</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 theme={null}
func (mountFactory) Tmpfs(opts TmpfsOptions) MountConfig
```

<Accordion title="Example">
  ```go theme={null}
  "/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>

<Tooltip tip="On microsandbox cloud, the disk-image path resolves against your organization's host volume, not the computer running the SDK or CLI."><span className="msb-badge-limited">Limited on cloud <Icon icon="circle-info" size={11} /></span></Tooltip>

```go theme={null}
func (mountFactory) Disk(hostPath string, opts DiskOptions) MountConfig
```

<Accordion title="Example">
  ```go theme={null}
  "/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>

## MountConfig

Mount configuration produced by the [`Mount`](#options) factory.

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

#### <span className="msb-recv">mount.</span><span className="msb-hn">Bind</span>

`string`

Host path for bind mounts

#### <span className="msb-recv">mount.</span><span className="msb-hn">Named</span>

`string`

Volume name for named mounts

#### <span className="msb-recv">mount.</span><span className="msb-hn">NamedMode</span>

`string`

Provisioning mode for named mounts (`"existing"`, `"create"`, `"ensure-exists"`)

#### <span className="msb-recv">mount.</span><span className="msb-hn">NamedKind</span>

`string`

Kind for provisioned named mounts (`"dir"` or `"disk"`)

#### <span className="msb-recv">mount.</span><span className="msb-hn">QuotaMiB</span>

`uint32`

Quota in MiB for provisioned directory volumes

#### <span className="msb-recv">mount.</span><span className="msb-hn">Tmpfs</span>

`bool`

Set for tmpfs mounts

#### <span className="msb-recv">mount.</span><span className="msb-hn">Disk</span>

`string`

Host path for disk images

#### <span className="msb-recv">mount.</span><span className="msb-hn">Format</span>

`string`

Disk format

#### <span className="msb-recv">mount.</span><span className="msb-hn">Fstype</span>

`string`

Inner filesystem type

#### <span className="msb-recv">mount.</span><span className="msb-hn">Readonly</span>

`bool`

Whether the mount is read-only

#### <span className="msb-recv">mount.</span><span className="msb-hn">Noexec</span>

`bool`

Whether direct execution from the mount is disabled

#### <span className="msb-recv">mount.</span><span className="msb-hn">Nosuid</span>

`bool`

Whether setuid/setgid elevation from files on the mount is ignored

#### <span className="msb-recv">mount.</span><span className="msb-hn">Nodev</span>

`bool`

Whether device files on the mount are ignored

#### <span className="msb-recv">mount.</span><span className="msb-hn">SizeMiB</span>

`uint32`

Size limit for tmpfs / capacity for provisioned disk volumes

#### <span className="msb-recv">mount.</span><span className="msb-hn">StatVirtualization</span>

`StatVirtualization`

Per-mount stat-virtualization policy (bind / named only)

#### <span className="msb-recv">mount.</span><span className="msb-hn">HostPermissions</span>

`HostPermissions`

Per-mount host-permission propagation policy (bind / named only)

#### <span className="msb-recv">mount.</span><span className="msb-hn">Owner</span>

`*MountOwner`

Guest owner fallback for host files without a per-file stat override (bind / directory-backed named only)

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

```go theme={null}
Kind()
```

Which mount flavour this is

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

[`MountKind`](#mountkind)

## Types

### ErrPathEscape

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

### MountKind

```go theme={null}
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`, `HostPermissions`, and `Owner` are virtiofs-only; owner is rejected for disk-backed named volumes and when stat virtualization is off. Zero policy values preserve the conservative defaults (strict, private), while a nil owner keeps the runtime fallback identity.

<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)                                                                                                                                                          |
| `Owner`              | `*MountOwner`        | Paired guest uid/gid fallback for host files without a per-file override; nil keeps the runtime fallback                                                                                                              |

### MountOwner

An inseparable guest ownership pair used by [`MountOptions.Owner`](#mountoptions). UID and GID may include zero; using a pointer to `MountOwner` keeps an unset owner distinct from root.

```go theme={null}
Owner: &m.MountOwner{UID: 1000, GID: 1000}
```

| Field | Type     | Description    |
| ----- | -------- | -------------- |
| `UID` | `uint32` | Guest user ID  |
| `GID` | `uint32` | Guest group ID |

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