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

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

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

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

<Tooltip tip="Unmounted-volume filesystem access is not available on microsandbox cloud; mount the volume into a sandbox and use the sandbox filesystem."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

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

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

<Tooltip tip="Unmounted-volume filesystem access is not available on microsandbox cloud; mount the volume into a sandbox and use the sandbox filesystem."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

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

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

<Tooltip tip="Unmounted-volume filesystem access is not available on microsandbox cloud; mount the volume into a sandbox and use the sandbox filesystem."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

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

<Tooltip tip="Unmounted-volume filesystem access is not available on microsandbox cloud; mount the volume into a sandbox and use the sandbox filesystem."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

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

<Tooltip tip="Unmounted-volume filesystem access is not available on microsandbox cloud; mount the volume into a sandbox and use the sandbox filesystem."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

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

<Tooltip tip="Unmounted-volume filesystem access is not available on microsandbox cloud; mount the volume into a sandbox and use the sandbox filesystem."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

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

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

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

## Mount

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

<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-note">On cloud <Icon icon="circle-info" size={11} /></span></Tooltip>

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

## 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">Kind()</span>

```go
Kind()
```

Which mount flavour this is

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

[`MountKind`](#mountkind)

## Types

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

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