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

See [Volumes](/sandboxes/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.

```typescript
import { Volume } from "microsandbox";

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

## Static methods

---

#### Volume.builder()

```typescript
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`](#volumebuilder) | Fluent builder |

---

#### Volume.get()

```typescript
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`](#volumehandle)`>` | Volume handle |

---

#### Volume.list()

```typescript
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`](#volumehandle)`[]>` | All volumes |

---

#### Volume.remove()

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

```typescript
get name(): string
```

The volume's name.

---

#### path

```typescript
get path(): string
```

Absolute host path to the volume's directory.

---

#### fs()

```typescript
fs(): VolumeFs
```

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

```typescript
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 => ...)`:

```typescript
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`](#volumebuilder). |
| `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; virtiofs-backed mounts also reject writes in the host filesystem server. |
| `noexec()` | Prevent direct execution from the mount. Interpreters can still read scripts from it. |
| `size(mib)` | Cap in MiB. Tmpfs only. |
| `build()` | Internal — produce a `VolumeMount`. |

### VolumeMount

Discriminated union produced by `MountBuilder.build()`.

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

### DiskImageFormat

```typescript
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`](#volumeconfig) |
| `create()` | Build and create the volume; returns a [`Volume`](#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`](#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`](/sdk/typescript/filesystem) (read, readToString, readStream, write, writeStream, list, mkdir, removeDir, remove, copy, rename, stat, exists) — but operates directly on the host without booting a sandbox.
