Volumes

TypeScript SDK - Volume API reference

See Volumes for usage examples and patterns.

Volume

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

import { Volume } from "microsandbox";

const data = await Volume.builder("my-data")
  .quota(100)
  .label("env", "prod")
  .create();

Static methods

---

Volume.builder()

static builder(name: string): VolumeBuilder

Begin building a named volume. Configure with .quota(...) and .label(...), then call .create().

Parameters

Name	Type	Description
name	string	Volume name

Returns

Type	Description
VolumeBuilder	Fluent builder

---

Volume.get()

static get(name: string): Promise<VolumeHandle>

Get a handle to an existing named volume.

Parameters

Name	Type	Description
name	string	Volume name

Returns

Type	Description
Promise<VolumeHandle>	Volume handle

---

Volume.list()

static list(): Promise<VolumeHandle[]>

List all named volumes. Handles returned from list() are read-only — call Volume.get(name) to get a live handle for .remove() / .fs().

Returns

Type	Description
Promise<VolumeHandle[]>	All volumes

---

Volume.remove()

static remove(name: string): Promise<void>

Delete a named volume and its contents. Fails if the volume is currently mounted.

Parameters

Name	Type	Description
name	string	Volume name

---

Instance properties

name

get name(): string

The volume’s name.

---

path

get path(): string

Absolute host path to the volume’s directory.

---

fs()

fs(): VolumeFs

Get a host-side filesystem handle for this volume — no sandbox required.

const vfs = data.fs();
await vfs.write("seed.txt", "hello");
console.log(await vfs.list(""));

---

Mounts

Volume mounts attach a host directory, named volume, tmpfs, or disk image to a guest path. Configure them via SandboxBuilder.volume(guestPath, m => ...):

await using sb = await Sandbox.builder("worker")
  .image("alpine")
  .volume("/host",    (m) => m.bind("/var/data"))
  .volume("/data",    (m) => m.named("my-data"))
  .volume("/scratch", (m) => m.tmpfs().size(128))
  .volume("/img",     (m) => m.disk("./data.qcow2").fstype("ext4").readonly())
  .create();

MountBuilder

Used inside SandboxBuilder.volume(guestPath, m => ...). Pick exactly one mount kind, then chain modifiers.

Method	Description
bind(host)	Mount a host directory into the guest.
named(name)	Mount a named volume created via Volume.builder.
tmpfs()	Mount an in-memory filesystem.
disk(host)	Mount a host disk image as a virtio-blk device.
format(fmt)	Disk image format ('qcow2' | 'raw' | 'vmdk'). Defaults to the file extension. Disk only.
fstype(fs)	Inner filesystem type (e.g. "ext4"). Disk only; omit to autodetect.
readonly()	Mount read-only.
size(mib)	Cap in MiB. Tmpfs only.
build()	Internal — produce a VolumeMount.

VolumeMount

Discriminated union produced by MountBuilder.build().

type VolumeMount =
  | { kind: "bind"; host: string; guest: string; readonly: boolean }
  | { kind: "named"; name: string; guest: string; readonly: boolean }
  | { kind: "tmpfs"; guest: string; sizeMib: number | null; readonly: boolean }
  | {
      kind: "disk";
      host: string;
      guest: string;
      format: DiskImageFormat;
      fstype: string | null;
      readonly: boolean;
    };

DiskImageFormat

type DiskImageFormat = "qcow2" | "raw" | "vmdk";

---

Types

VolumeBuilder

Method	Description
quota(mib)	Maximum storage size in MiB
label(key, value)	Add a metadata label
build()	Materialize a VolumeConfig
create()	Build and create the volume; returns a Volume

VolumeConfig

Frozen configuration produced by VolumeBuilder.build().

Field	Type	Description
name	string	Volume name
quotaMib	number | null	Maximum storage size in MiB
labels	ReadonlyArray<readonly [string, string]>	Metadata labels

VolumeHandle

Property / Method	Type	Description
name	string	Volume name
quotaMib	number | null	Storage quota
usedBytes	number	Current disk usage in bytes
labels	ReadonlyArray<readonly [string, string]>	Metadata labels
createdAt	Date | null	Creation timestamp
fs()	VolumeFs	Host-side filesystem on this volume (live handles only)
remove()	Promise<void>	Delete this volume (live handles only)

Handles in the array returned by Volume.list() are read-only: calling .fs() or .remove() throws. Use Volume.get(name) to upgrade.

VolumeFs

Host-side filesystem operations on a volume’s directory. Same surface area as SandboxFs (read, readToString, readStream, write, writeStream, list, mkdir, removeDir, remove, copy, rename, stat, exists) — but operates directly on the host without booting a sandbox.