Volumes

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 for usage examples and patterns.

Typical flow

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 builder(name: string): VolumeBuilder

Example

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 for all options.

Parameters

namestring

Volume name.

Returns

VolumeBuilder

Fluent builder for configuring the volume.

Volume.get()

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

Example

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().

Parameters

namestring

Volume name.

Returns

Promise<VolumeHandle>

Live handle with metadata, filesystem access, and removal.

Volume.list()

static list(): Promise<VolumeHandle[]>

Example

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) to upgrade to a live handle.

Returns

Promise<VolumeHandle[]>

All volumes, as read-only handles.

Volume.remove()

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

Example

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

get name(): string

The volume’s name.

Returns

string

Volume name.

volume.path

get path(): string

Absolute host path to the volume’s directory. By default volumes live under ~/.microsandbox/volumes/<name>/.

Returns

string

Absolute host directory path.

volume.fs()

fs(): VolumeFs

Example

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

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 for the full API.

Returns

VolumeFs

Host-side filesystem handle.

VolumeBuilder

Fluent builder for a named volume. Obtained via Volume.builder(name). Directory-backed volumes are the default; call disk() plus size() for a disk-backed volume. Every setter returns the builder, so calls chain.

.directory()

directory(): this

Create a directory-backed volume. This is the default, so calling it is only needed for clarity.

.disk()

disk(): this

Example

const dockerData = await Volume.builder("docker-data")
  .disk()
  .size(20 * 1024)
  .create();

Create a raw ext4 disk-backed volume. Pair with size() to set the capacity.

.size()

size(mib: number): this

Set the disk capacity in MiB. Required after disk().

Parameters

mibnumber

Disk capacity in MiB.

.quota()

quota(mib: number): this

Record a quota in MiB as metadata for directory-backed volumes.

Parameters

mibnumber

Quota in MiB.

.label()

label(key: string, value: string): this

Add a metadata label. Can be called multiple times.

Parameters

keystring

Label key.

valuestring

Label value.

.build()

build(): { name: string; kind: string; quotaMib?: number | null; capacityMib?: number | null; labels: Record<string, string> }

Materialize the volume configuration without creating the volume on disk. To create it, use create() instead. The returned config object is the internal NapiVolumeConfig shape (not a public export).

Returns

Frozen volume configuration object.

.create()

create(): Promise<Volume>

Example

const data = await Volume.builder("my-data").create();

Build and create the volume on disk, returning a Volume.

Returns

Promise<Volume>

The created volume.

VolumeFs methods

Host-side filesystem operations on a volume’s directory. Obtained via volume.fs() or VolumeHandle.fs(). 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()

read(path: string): Promise<Uint8Array>

Example

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

readToString(path: string): Promise<string>

Example

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

readStream(path: string): Promise<VolumeFsReadStream>

Example

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

Promise<VolumeFsReadStream>

Async-iterable read stream.

vfs.write()

write(path: string, data: Uint8Array | string): Promise<void>

Example

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

writeStream(path: string): Promise<VolumeFsWriteSink>

Example

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

Promise<VolumeFsWriteSink>

Write sink; call close() when done.

vfs.list()

list(path: string): Promise<FsEntry[]>

Example

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

Promise<FsEntry[]>

Directory entries.

vfs.mkdir()

mkdir(path: string): Promise<void>

Example

await vfs.mkdir("cache/images");

Create a directory, including any missing parents.

Parameters

pathstring

Directory path relative to the volume root.

vfs.removeDir()

removeDir(path: string): Promise<void>

Example

await vfs.removeDir("cache");

Recursively remove a directory and its contents.

Parameters

pathstring

Directory path relative to the volume root.

vfs.remove()

remove(path: string): Promise<void>

Example

await vfs.remove("seed.txt");

Remove a single file.

Parameters

pathstring

File path relative to the volume root.

vfs.copy()

copy(from: string, to: string): Promise<void>

Example

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

rename(from: string, to: string): Promise<void>

Example

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

stat(path: string): Promise<FsMetadata>

Example

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

Promise<FsMetadata>

Kind, size, mode, and timestamps.

vfs.exists()

exists(path: string): Promise<boolean>

Example

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.

Types

VolumeHandle

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

A handle to an existing named volume, carrying its metadata. Handles from Volume.get() are live: .fs() and .remove() work. Handles in the array from 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<readonly [string, string]>`	Metadata labels
createdAt	`Date \| null`	Creation timestamp
fs()	`VolumeFs`	Host-side filesystem (live handles only; throws on read-only handles)
remove()	`Promise<void>`	Delete this volume (live handles only; throws on read-only handles)

VolumeFs

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

Host-side filesystem operations on a volume’s directory. The methods mirror SandboxFsOps but run directly on the host with no sandbox booted. See the VolumeFs methods section above for full per-method details.

Method	Type	Description
read(path)	`Promise<Uint8Array>`	Read a file as bytes
readToString(path)	`Promise<string>`	Read a file as a UTF-8 string
readStream(path)	`Promise<VolumeFsReadStream>`	Open a streaming reader
write(path, data)	`Promise<void>`	Write a file (bytes or string)
writeStream(path)	`Promise<VolumeFsWriteSink>`	Open a streaming writer
list(path)	`Promise<FsEntry[]>`	List directory entries
mkdir(path)	`Promise<void>`	Create a directory, with parents
removeDir(path)	`Promise<void>`	Recursively remove a directory
remove(path)	`Promise<void>`	Remove a file
copy(from, to)	`Promise<void>`	Copy a file or directory
rename(from, to)	`Promise<void>`	Move or rename a file or directory
stat(path)	`Promise<FsMetadata>`	Get file metadata
exists(path)	`Promise<boolean>`	Check whether a path exists

VolumeFsReadStream

Returned by VolumeFs.readStream()

A streaming reader over a volume file. Implements AsyncIterable<Uint8Array> and AsyncDisposable, so it works with for await and using.

Method	Type	Description
recv()	`Promise<Uint8Array \| null>`	Read the next chunk; `null` when the stream is exhausted
collect()	`Promise<Uint8Array>`	Drain the stream into a single byte array
Symbol.asyncIterator	`AsyncIterator<Uint8Array>`	Iterate chunks with `for await`
Symbol.asyncDispose	`Promise<void>`	Mark the stream done (for `using`)

VolumeFsWriteSink

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<void>`	Write a chunk (`Uint8Array` or UTF-8 string)
close()	`Promise<void>`	Flush and close the sink; idempotent
Symbol.asyncDispose	`Promise<void>`	Close the sink (for `await using`)

Getting Started

SDKs

CLI

Static methods

Volume.builder()

Volume.get()

Volume.list()

Volume.remove()

Instance methods

volume.name

volume.path

volume.fs()

VolumeBuilder

.directory()

.disk()

.size()

.quota()

.label()

.build()

.create()

VolumeFs methods

vfs.read()

vfs.readToString()

vfs.readStream()

vfs.write()

vfs.writeStream()

vfs.list()

vfs.mkdir()

vfs.removeDir()

vfs.remove()

vfs.copy()

vfs.rename()

vfs.stat()

vfs.exists()

Types

VolumeHandle

VolumeFs

VolumeFsReadStream

VolumeFsWriteSink

​Static methods

​Volume.builder()

​Volume.get()

​Volume.list()

​Volume.remove()

​Instance methods

​volume.name

​volume.path

​volume.fs()

​VolumeBuilder

​.directory()

​.disk()

​.size()

​.quota()

​.label()

​.build()

​.create()

​VolumeFs methods

​vfs.read()

​vfs.readToString()

​vfs.readStream()

​vfs.write()

​vfs.writeStream()

​vfs.list()

​vfs.mkdir()

​vfs.removeDir()

​vfs.remove()

​vfs.copy()

​vfs.rename()

​vfs.stat()

​vfs.exists()

​Types

​VolumeHandle

​VolumeFs

​VolumeFsReadStream

​VolumeFsWriteSink

Static methods

Volume.builder()

Volume.get()

Volume.list()

Volume.remove()

Instance methods

volume.name

volume.path

volume.fs()

VolumeBuilder

.directory()

.disk()

.size()

.quota()

.label()

.build()

.create()

VolumeFs methods

vfs.read()

vfs.readToString()

vfs.readStream()

vfs.write()

vfs.writeStream()

vfs.list()

vfs.mkdir()

vfs.removeDir()

vfs.remove()

vfs.copy()

vfs.rename()

vfs.stat()

vfs.exists()

Types

VolumeHandle

VolumeFs

VolumeFsReadStream

VolumeFsWriteSink