--- title: Volumes description: TypeScript SDK - Volume API reference --- Create, manage, and mount named volumes. See [Volumes](/sandboxes/volumes) for usage examples. ## Volume

Instance properties

#### volume.name ```typescript get name(): string ``` The volume's name.

Returns

string
Volume name.
#### volume.path ```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.

Static methods

#### Volume.getDefault() ```typescript static getDefault(): Promise ``` 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 a typed `Unsupported` error; it never substitutes a directory from the caller's machine. ```typescript const volume = await Volume.getDefault(); await volume.fs().write("customers/acme.json", JSON.stringify({ active: true })); console.log(await volume.fs().readToString("customers/acme.json")); ``` #### Volume.builder() ```typescript static builder(name: string): VolumeBuilder ``` ```typescript const data = await Volume.builder("my-data") .label("env", "prod") .create(); ``` 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.
#### Volume.get() ```typescript static get(name: string): Promise ``` ```typescript const handle = await Volume.get("my-data"); console.log(handle.usedBytes); ``` 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

Live handle with metadata, filesystem access, and removal.
#### Volume.list() ```typescript static list(): Promise ``` ```typescript for (const v of await Volume.list()) { console.log(`${v.name} - ${v.kind} - ${v.usedBytes} bytes`); } ``` 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

All volumes, as read-only handles.
#### Volume.remove() ```typescript static remove(name: string): Promise ``` ```typescript await Volume.remove("my-data"); ``` Delete a named volume and its contents. Fails if the volume is currently mounted by a sandbox.

Parameters

namestring
Volume name.

Instance methods

#### volume.fs() Local-only ```typescript fs(): VolumeFs ``` ```typescript const vfs = data.fs(); await vfs.write("seed.txt", "hello"); console.log(await vfs.readToString("seed.txt")); ``` Get a filesystem handle for this volume. Local reads and writes use the managed host directory; Cloud reads and writes use the authenticated volume API. No sandbox needs to be running. See [`VolumeFs`](#volumefs-methods) for the full API.

Returns

Host-side filesystem handle.
## 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. #### volumeBuilder.directory() ```typescript directory(): this ``` Create a directory-backed volume. This is the default, so calling it is only needed for clarity. #### volumeBuilder.disk() Local-only ```typescript disk(): this ``` ```typescript const dockerData = await Volume.builder("docker-data") .disk() .size(20 * 1024) .create(); ``` Create a raw ext4 disk-backed volume. Pair with [`size()`](#size) to set the capacity. #### volumeBuilder.size() Local-only ```typescript size(mib: number): this ``` Set the disk capacity in MiB. Required after [`disk()`](#disk).

Parameters

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

Parameters

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

Parameters

keystring
Label key.
valuestring
Label value.
#### volumeBuilder.build() ```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.
#### volumeBuilder.create() ```typescript create(): Promise ``` ```typescript const data = await Volume.builder("my-data").create(); ``` Build and create the volume on disk, returning a [`Volume`](#instance-methods).

Returns

The created volume.
## VolumeFs

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

Host-side filesystem operations for a named volume. #### vfs.read() Local-only ```typescript read(path: string): Promise ``` ```typescript const bytes = await vfs.read("data.bin"); ``` Read a file's full contents as bytes.

Parameters

pathstring
Path relative to the volume root.

Returns

Promise<Uint8Array>
File contents.
#### vfs.readToString() Local-only ```typescript readToString(path: string): Promise ``` ```typescript const text = await vfs.readToString("config.json"); ``` 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.
#### vfs.readStream() Local-only ```typescript readStream(path: string): Promise ``` ```typescript const stream = await vfs.readStream("large.bin"); for await (const chunk of stream) { console.log(chunk.byteLength); } ``` 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.
#### vfs.write() Local-only ```typescript write(path: string, data: Uint8Array | string): Promise ``` ```typescript await vfs.write("seed.txt", "hello"); ``` 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.
#### vfs.writeStream() Local-only ```typescript writeStream(path: string): Promise ``` ```typescript const sink = await vfs.writeStream("out.bin"); await sink.write(chunk); await sink.close(); ``` 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.
#### vfs.list() ```typescript list(path: string): Promise ``` ```typescript for (const e of await vfs.list("")) { console.log(e.path, e.kind, e.size); } ``` List the entries in a directory. Pass `""` for the volume root.

Parameters

pathstring
Directory path relative to the volume root.

Returns

Directory entries.
#### vfs.mkdir() ```typescript mkdir(path: string): Promise ``` ```typescript await vfs.mkdir("cache/images"); ``` Create a directory, including any missing parents.

Parameters

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

Parameters

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

Parameters

pathstring
File path relative to the volume root.
#### vfs.copy() ```typescript copy(from: string, to: string): Promise ``` ```typescript await vfs.copy("seed.txt", "backup/seed.txt"); ``` 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.
#### vfs.rename() ```typescript rename(from: string, to: string): Promise ``` ```typescript await vfs.rename("draft.txt", "final.txt"); ``` Move or rename a file or directory.

Parameters

fromstring
Source path relative to the volume root.
tostring
Destination path relative to the volume root.
#### vfs.stat() ```typescript stat(path: string): Promise ``` ```typescript const meta = await vfs.stat("seed.txt"); console.log(meta.size, meta.kind); ``` Get metadata for a file or directory.

Parameters

pathstring
Path relative to the volume root.

Returns

Kind, size, mode, and timestamps.
#### vfs.exists() ```typescript exists(path: string): Promise ``` ```typescript if (await vfs.exists("seed.txt")) { await vfs.remove("seed.txt"); } ``` Check whether a path exists.

Parameters

pathstring
Path relative to the volume root.

Returns

Promise<boolean>
true if the path exists.
## VolumeHandle

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

A metadata and lifecycle handle for an existing volume. #### handle.name `string` Volume name #### handle.kind `string` Volume kind (`"dir"` or `"disk"`) #### handle.quotaMib `number \| null` Recorded storage quota in MiB #### handle.usedBytes `number` Current disk usage in bytes #### handle.capacityBytes `number \| null` Disk capacity in bytes (disk volumes) #### handle.diskFormat `string \| null` Disk image format (disk volumes) #### handle.diskFstype `string \| null` Inner disk filesystem (disk volumes) #### handle.labels `ReadonlyArray` Metadata labels #### handle.createdAt `Date \| null` Creation timestamp #### handle.fs() ```typescript fs() ``` Host-side filesystem (live handles only; throws on read-only handles)

Returns

[`VolumeFs`](#volumefs) #### handle.remove() ```typescript remove() ``` Delete this volume (live handles only; throws on read-only handles)

Returns

`Promise` ## VolumeFsReadStream

Returned by VolumeFs.readStream()

A streaming reader over a volume file. Implements `AsyncIterable` and `AsyncDisposable`, so it works with `for await` and `using`. #### stream.recv() ```typescript recv() ``` Read the next chunk; `null` when the stream is exhausted

Returns

`Promise` #### stream.collect() ```typescript collect() ``` Drain the stream into a single byte array

Returns

`Promise` #### stream.[Symbol.asyncIterator]() ```typescript [Symbol.asyncIterator]() ``` Iterate chunks with `for await`

Returns

`AsyncIterator` #### stream.[Symbol.asyncDispose]() ```typescript [Symbol.asyncDispose]() ``` Mark the stream done (for `using`)

Returns

`Promise` ## VolumeFsWriteSink

Returned by VolumeFs.writeStream()

A streaming writer for a volume file. Implements `AsyncDisposable`, so `await using` closes it automatically. #### sink.write() ```typescript write(data) ``` Write a chunk (`Uint8Array` or UTF-8 string)

Returns

`Promise` #### sink.close() ```typescript close() ``` Flush and close the sink; idempotent

Returns

`Promise` #### sink.[Symbol.asyncDispose]() ```typescript [Symbol.asyncDispose]() ``` Close the sink (for `await using`)

Returns

`Promise`