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

> Create and mount persistent sandbox volumes with the Go SDK.

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

## Local filesystem paths

Local operations stay inside the selected volume directory. Symlinked volume roots and links that ultimately resolve inside that directory remain supported. Each operation pins its root so replacing the root path cannot redirect an operation already in progress.

Go previously cleaned `..` components before filesystem lookup. Paths where a symlink followed by `..` would select a different destination now return an error. Use the destination explicitly:

```go theme={null}
// link -> nested/deep; config and nested/config are different files.
err = fs.Write(ctx, "link/../config", data) // Error: ambiguous destination.
err = fs.Write(ctx, "config", data)         // Select the original Go destination.
err = fs.Write(ctx, "nested/config", data)  // Explicitly select the other file.
```

Ordinary contained `..` paths remain supported. `RemoveAll(ctx, ".")` and `RemoveAll(ctx, "")` delete the local volume directory and its contents. If the root itself is a symlink, they unlink that root link and preserve its target, matching Go's previous behavior. Descendant links never cause deletion outside the volume.

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

<Accordion title="Example">
  ```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")
  ```
</Accordion>

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

Local operations follow paths through an opened volume directory, including symlink targets and missing parents. Paths that escape the volume return `ErrPathEscape`; valid in-volume symlinks remain usable. Removing a final symlink unlinks the link itself. `Remove(ctx, ".")` and `Remove(ctx, "")` delete an empty root; `RemoveAll` also deletes its contents. After the root disappears, `Exists` returns `false, nil`, and `Mkdir` can recreate the root and missing parents. Local OS failures retain `*os.PathError` and their native error number, so `errors.Is` checks against `syscall.Errno` and the standard `os` error predicates continue to work. Local operations require the matching updated native SDK library; older libraries return `ErrUnsupportedOperation` with an upgrade instruction.

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

| Field | Type | Description |
| - | - | - |
| <span id="mount-bind-2" />`Bind` | `string` | Host path for bind mounts |
| <span id="mount-named-2" />`Named` | `string` | Volume name for named mounts |
| <span id="mount-namedmode" />`NamedMode` | `string` | Provisioning mode for named mounts (`"existing"`, `"create"`, `"ensure-exists"`) |
| <span id="mount-namedkind" />`NamedKind` | `string` | Kind for provisioned named mounts (`"dir"` or `"disk"`) |
| <span id="mount-quotamib" />`QuotaMiB` | `uint32` | Quota in MiB for provisioned directory volumes |
| <span id="mount-tmpfs-2" />`Tmpfs` | `bool` | Set for tmpfs mounts |
| <span id="mount-disk-2" />`Disk` | `string` | Host path for disk images |
| <span id="mount-format" />`Format` | `string` | Disk format |
| <span id="mount-fstype" />`Fstype` | `string` | Inner filesystem type |
| <span id="mount-readonly" />`Readonly` | `bool` | Whether the mount is read-only |
| <span id="mount-noexec" />`Noexec` | `bool` | Whether direct execution from the mount is disabled |
| <span id="mount-nosuid" />`Nosuid` | `bool` | Whether setuid/setgid elevation from files on the mount is ignored |
| <span id="mount-nodev" />`Nodev` | `bool` | Whether device files on the mount are ignored |
| <span id="mount-sizemib" />`SizeMiB` | `uint32` | Size limit for tmpfs / capacity for provisioned disk volumes |
| <span id="mount-statvirtualization" />`StatVirtualization` | `StatVirtualization` | Per-mount stat-virtualization policy (bind / named only) |
| <span id="mount-hostpermissions" />`HostPermissions` | `HostPermissions` | Per-mount host-permission propagation policy (bind / named only) |
| <span id="mount-owner" />`Owner` | `*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 traverses a symlink outside the volume's directory.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.