--- title: Volumes description: TypeScript SDK - Volume API reference --- Create and manage named volumes: persistent storage that lives independently of any sandbox. Build a volume, look one up, read and write its files from the host, then delete it. See [Volumes](/sandboxes/volumes) for usage examples and patterns.

Static · Volume4

Volume.builder()configure a new volume Volume.get()handle to an existing one Volume.list()all volumes Volume.remove()delete a volume

Instance · Volume3

volume.namevolume name volume.pathhost directory path volume.fs()host-side filesystem

Builder · VolumeBuilder7

.directory() .disk() .size() .quota() .label() .build() .create()

Types

VolumeHandle VolumeFs VolumeFsReadStream VolumeFsWriteSink FsEntry FsMetadata

Typical flow

```typescript import { Volume } from "microsandbox"; const data = await Volume.builder("my-data") // 1. configure .label("env", "prod") .create(); // 2. create on disk const vfs = data.fs(); // 3. host-side I/O await vfs.write("seed.txt", "hello"); console.log(await vfs.list("")); await Volume.remove("my-data"); // 4. delete ``` ## Static methods --- #### Volume.builder()
static
```typescript static builder(name: string): VolumeBuilder ``` Begin building a named volume. Directory-backed volumes are the default. Call `.disk().size(...)` for a disk-backed volume. See [`VolumeBuilder`](#volumebuilder) for all options.

Parameters

namestring
Volume name.

Returns

VolumeBuilder
Fluent builder for configuring the volume.
```typescript const data = await Volume.builder("my-data") .label("env", "prod") .create(); ``` --- #### Volume.get()
staticasync
```typescript static get(name: string): Promise ``` Get a live handle to an existing named volume. A live handle supports `.fs()` and `.remove()`, unlike the read-only handles returned by [`list()`](#volume-list).

Parameters

namestring
Volume name.

Returns

Promise<VolumeHandle>
Live handle with metadata, filesystem access, and removal.
```typescript const handle = await Volume.get("my-data"); console.log(handle.usedBytes); ``` --- #### Volume.list()
staticasync
```typescript static list(): Promise ``` List all named volumes. Handles returned here are **read-only**: calling `.fs()` or `.remove()` on them throws. Call [`Volume.get(name)`](#volume-get) to upgrade to a live handle.

Returns

Promise<VolumeHandle[]>
All volumes, as read-only handles.
```typescript for (const v of await Volume.list()) { console.log(`${v.name} — ${v.kind} — ${v.usedBytes} bytes`); } ``` --- #### Volume.remove()
staticasync
```typescript static remove(name: string): Promise ``` Delete a named volume and its contents. Fails if the volume is currently mounted by a sandbox.

Parameters

namestring
Volume name.
```typescript await Volume.remove("my-data"); ``` --- ## Instance methods --- #### volume.name
getter
```typescript get name(): string ``` The volume's name.

Returns

string
Volume name.
--- #### volume.path
getter
```typescript get path(): string ``` Absolute host path to the volume's directory. By default volumes live under `~/.microsandbox/volumes//`.

Returns

string
Absolute host directory path.
--- #### volume.fs()
instance
```typescript fs(): VolumeFs ``` Get a host-side filesystem handle for this volume's directory. Reads and writes happen directly on the host, with no sandbox running. See [`VolumeFs`](#volumefs-methods) for the full API.

Returns

Host-side filesystem handle.
```typescript const vfs = data.fs(); await vfs.write("seed.txt", "hello"); console.log(await vfs.readToString("seed.txt")); ``` --- ## VolumeBuilder Fluent builder for a named volume. Obtained via [`Volume.builder(name)`](#volume-builder). Directory-backed volumes are the default; call [`disk()`](#disk) plus [`size()`](#size) for a disk-backed volume. Every setter returns the builder, so calls chain. --- #### .directory()
builder
```typescript directory(): this ``` Create a directory-backed volume. This is the default, so calling it is only needed for clarity. --- #### .disk()
builder
```typescript disk(): this ``` Create a raw ext4 disk-backed volume. Pair with [`size()`](#size) to set the capacity. ```typescript const dockerData = await Volume.builder("docker-data") .disk() .size(20 * 1024) .create(); ``` --- #### .size()
builder
```typescript size(mib: number): this ``` Set the disk capacity in MiB. Required after [`disk()`](#disk).

Parameters

mibnumber
Disk capacity in MiB.
--- #### .quota()
builder
```typescript quota(mib: number): this ``` Record a quota in MiB as metadata for directory-backed volumes.

Parameters

mibnumber
Quota in MiB.
--- #### .label()
builder
```typescript label(key: string, value: string): this ``` Add a metadata label. Can be called multiple times.

Parameters

keystring
Label key.
valuestring
Label value.
--- #### .build()
builder
```typescript build(): { name: string; kind: string; quotaMib?: number | null; capacityMib?: number | null; labels: Record } ``` Materialize the volume configuration without creating the volume on disk. To create it, use [`create()`](#create) instead. The returned config object is the internal `NapiVolumeConfig` shape (not a public export).

Returns

{`{ name, kind, quotaMib?, capacityMib?, labels }`}
Frozen volume configuration object.
--- #### .create()
builderasync
```typescript create(): Promise ``` Build and create the volume on disk, returning a [`Volume`](#instance-methods).

Returns

The created volume.
```typescript const data = await Volume.builder("my-data").create(); ``` --- ## VolumeFs methods Host-side filesystem operations on a volume's directory. Obtained via [`volume.fs()`](#volume-fs) or [`VolumeHandle.fs()`](#volumehandle). All operations run directly on the host without booting a sandbox. Paths are relative to the volume's root directory. Every method is async. --- #### vfs.read()
instanceasync
```typescript read(path: string): Promise ``` Read a file's full contents as bytes.

Parameters

pathstring
Path relative to the volume root.

Returns

Promise<Uint8Array>
File contents.
```typescript const bytes = await vfs.read("data.bin"); ``` --- #### vfs.readToString()
instanceasync
```typescript readToString(path: string): Promise ``` Read a file's full contents as a UTF-8 string.

Parameters

pathstring
Path relative to the volume root.

Returns

Promise<string>
Decoded file contents.
```typescript const text = await vfs.readToString("config.json"); ``` --- #### vfs.readStream()
instanceasync
```typescript readStream(path: string): Promise ``` Open a streaming reader for a file, for chunked reads of large files without loading them fully into memory.

Parameters

pathstring
Path relative to the volume root.

Returns

Async-iterable read stream.
```typescript const stream = await vfs.readStream("large.bin"); for await (const chunk of stream) { console.log(chunk.byteLength); } ``` --- #### vfs.write()
instanceasync
```typescript write(path: string, data: Uint8Array | string): Promise ``` Write a file, replacing any existing contents. Strings are encoded as UTF-8.

Parameters

pathstring
Path relative to the volume root.
dataUint8Array | string
Bytes, or a UTF-8 string.
```typescript await vfs.write("seed.txt", "hello"); ``` --- #### vfs.writeStream()
instanceasync
```typescript writeStream(path: string): Promise ``` Open a streaming writer for a file, for chunked writes of large files.

Parameters

pathstring
Path relative to the volume root.

Returns

Write sink; call close() when done.
```typescript const sink = await vfs.writeStream("out.bin"); await sink.write(chunk); await sink.close(); ``` --- #### vfs.list()
instanceasync
```typescript list(path: string): Promise ``` List the entries in a directory. Pass `""` for the volume root.

Parameters

pathstring
Directory path relative to the volume root.

Returns

Directory entries.
```typescript for (const e of await vfs.list("")) { console.log(e.path, e.kind, e.size); } ``` --- #### vfs.mkdir()
instanceasync
```typescript mkdir(path: string): Promise ``` Create a directory, including any missing parents.

Parameters

pathstring
Directory path relative to the volume root.
```typescript await vfs.mkdir("cache/images"); ``` --- #### vfs.removeDir()
instanceasync
```typescript removeDir(path: string): Promise ``` Recursively remove a directory and its contents.

Parameters

pathstring
Directory path relative to the volume root.
```typescript await vfs.removeDir("cache"); ``` --- #### vfs.remove()
instanceasync
```typescript remove(path: string): Promise ``` Remove a single file.

Parameters

pathstring
File path relative to the volume root.
```typescript await vfs.remove("seed.txt"); ``` --- #### vfs.copy()
instanceasync
```typescript copy(from: string, to: string): Promise ``` Copy a file or directory from one path to another.

Parameters

fromstring
Source path relative to the volume root.
tostring
Destination path relative to the volume root.
```typescript await vfs.copy("seed.txt", "backup/seed.txt"); ``` --- #### vfs.rename()
instanceasync
```typescript rename(from: string, to: string): Promise ``` Move or rename a file or directory.

Parameters

fromstring
Source path relative to the volume root.
tostring
Destination path relative to the volume root.
```typescript await vfs.rename("draft.txt", "final.txt"); ``` --- #### vfs.stat()
instanceasync
```typescript stat(path: string): Promise ``` Get metadata for a file or directory.

Parameters

pathstring
Path relative to the volume root.

Returns

Kind, size, mode, and timestamps.
```typescript const meta = await vfs.stat("seed.txt"); console.log(meta.size, meta.kind); ``` --- #### vfs.exists()
instanceasync
```typescript exists(path: string): Promise ``` Check whether a path exists.

Parameters

pathstring
Path relative to the volume root.

Returns

Promise<boolean>
true if the path exists.
```typescript if (await vfs.exists("seed.txt")) { await vfs.remove("seed.txt"); } ``` --- ## Types ### VolumeHandle
class

Returned by Volume.get() · Volume.list()

A handle to an existing named volume, carrying its metadata. Handles from [`Volume.get()`](#volume-get) are **live**: `.fs()` and `.remove()` work. Handles in the array from [`Volume.list()`](#volume-list) are **read-only**: those two methods throw, so call `Volume.get(name)` to upgrade. | Property / Method | Type | Description | |-------------------|------|-------------| | name | `string` | Volume name | | kind | `string` | Volume kind (`"dir"` or `"disk"`) | | quotaMib | `number \| null` | Recorded storage quota in MiB | | usedBytes | `number` | Current disk usage in bytes | | capacityBytes | `number \| null` | Disk capacity in bytes (disk volumes) | | diskFormat | `string \| null` | Disk image format (disk volumes) | | diskFstype | `string \| null` | Inner disk filesystem (disk volumes) | | labels | `ReadonlyArray` | Metadata labels | | createdAt | `Date \| null` | Creation timestamp | | fs() | [`VolumeFs`](#volumefs) | Host-side filesystem (live handles only; throws on read-only handles) | | remove() | `Promise` | Delete this volume (live handles only; throws on read-only handles) | ### VolumeFs
class

Returned by volume.fs() · VolumeHandle.fs()

Host-side filesystem operations on a volume's directory. The methods mirror [`SandboxFsOps`](/sdk/typescript/filesystem) but run directly on the host with no sandbox booted. See the [VolumeFs methods](#volumefs-methods) section above for full per-method details. | Method | Type | Description | |--------|------|-------------| | read(path) | `Promise` | Read a file as bytes | | readToString(path) | `Promise` | Read a file as a UTF-8 string | | readStream(path) | `Promise<`[`VolumeFsReadStream`](#volumefsreadstream)`>` | Open a streaming reader | | write(path, data) | `Promise` | Write a file (bytes or string) | | writeStream(path) | `Promise<`[`VolumeFsWriteSink`](#volumefswritesink)`>` | Open a streaming writer | | list(path) | `Promise<`[`FsEntry`](/sdk/typescript/filesystem#fsentry)`[]>` | List directory entries | | mkdir(path) | `Promise` | Create a directory, with parents | | removeDir(path) | `Promise` | Recursively remove a directory | | remove(path) | `Promise` | Remove a file | | copy(from, to) | `Promise` | Copy a file or directory | | rename(from, to) | `Promise` | Move or rename a file or directory | | stat(path) | `Promise<`[`FsMetadata`](/sdk/typescript/filesystem#fsmetadata)`>` | Get file metadata | | exists(path) | `Promise` | Check whether a path exists | ### VolumeFsReadStream
class

Returned by VolumeFs.readStream()

A streaming reader over a volume file. Implements `AsyncIterable` and `AsyncDisposable`, so it works with `for await` and `using`. | Method | Type | Description | |--------|------|-------------| | recv() | `Promise` | Read the next chunk; `null` when the stream is exhausted | | collect() | `Promise` | Drain the stream into a single byte array | | [Symbol.asyncIterator]() | `AsyncIterator` | Iterate chunks with `for await` | | [Symbol.asyncDispose]() | `Promise` | Mark the stream done (for `using`) | ### VolumeFsWriteSink
class

Returned by VolumeFs.writeStream()

A streaming writer for a volume file. Implements `AsyncDisposable`, so `await using` closes it automatically. | Method | Type | Description | |--------|------|-------------| | write(data) | `Promise` | Write a chunk (`Uint8Array` or UTF-8 string) | | close() | `Promise` | Flush and close the sink; idempotent | | [Symbol.asyncDispose]() | `Promise` | Close the sink (for `await using`) |