TypeScript SDK Volumes reference

See Volumes for usage examples.

Volume

Instance properties

Field	Type	Description
`name`	`string`	The volume’s name.
`path`	`string`	Absolute host path to the volume’s directory. By default volumes live under `~/.microsandbox/volumes/<name>/`.

Static methods

Volume.getDefault()

static getDefault(): Promise<VolumeHandle>

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.

Example

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

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

fs(): VolumeFs

Example

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

volumeBuilder.directory()

directory(): this

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

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

volumeBuilder.size()

size(mib: number): this

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

Parameters

mibnumber

Disk capacity in MiB.

volumeBuilder.quota()

quota(mib: number): this

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

Parameters

mibnumber

Quota in MiB.

volumeBuilder.label()

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

Add a metadata label. Can be called multiple times.

Parameters

keystring

Label key.

valuestring

Label value.

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

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

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

Host-side filesystem operations for a named volume.

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.

VolumeHandle

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

A metadata and lifecycle handle for an existing volume.

Field	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

handle.fs()

fs()

Host-side filesystem (live handles only; throws on read-only handles)

Returns

VolumeFs

handle.remove()

remove()

Delete this volume (live handles only; throws on read-only handles)

Returns

Promise<void>

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.

stream.recv()

recv()

Read the next chunk; null when the stream is exhausted

Returns

Promise<Uint8Array \| null>

stream.collect()

collect()

Drain the stream into a single byte array

Returns

Promise<Uint8Array>

stream.Symbol.asyncIterator

[Symbol.asyncIterator]()

Iterate chunks with for await

Returns

AsyncIterator<Uint8Array>

stream.Symbol.asyncDispose

[Symbol.asyncDispose]()

Mark the stream done (for using)

Returns

Promise<void>

VolumeFsWriteSink

Returned by VolumeFs.writeStream()

A streaming writer for a volume file. Implements AsyncDisposable, so await using closes it automatically.

sink.write()

write(data)

Write a chunk (Uint8Array or UTF-8 string)

Returns

Promise<void>

sink.close()

close()

Flush and close the sink; idempotent

Returns

Promise<void>

sink.Symbol.asyncDispose

[Symbol.asyncDispose]()

Close the sink (for await using)

Returns

Promise<void>

MountBuilder

mount.owned()

owned(options?: OwnedVolumeOptions): this

Allocate local storage for this sandbox. The storage survives stop/start and is deleted with the sandbox. Cloud does not support owned mounts. See Volumes for usage. OwnedVolumeOptions accepts kind ("dir" by default or "disk"), quotaMib for directories, and sizeMib for disks. Disks require a positive capacity and use raw ext4. Common mount flags remain on MountBuilder; owner() and metadata policies apply only to directories.

mount.owner()

owner(uid: number, gid: number): this

Set the guest owner for bind and directory-backed named mounts when no per-file stat override exists. Both values must be integers from 0 through 4294967295. Host inode ownership is unchanged. Unsupported for tmpfs, disk mounts, and statVirtualization("off").

​Volume

​Volume.getDefault()

​Volume.builder()

​Volume.get()

​Volume.list()

​Volume.remove()

​volume.fs()

​VolumeBuilder

​volumeBuilder.directory()

​volumeBuilder.disk()

​volumeBuilder.size()

​volumeBuilder.quota()

​volumeBuilder.label()

​volumeBuilder.build()

​volumeBuilder.create()

​VolumeFs

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

​VolumeHandle

​handle.fs()

​handle.remove()

​VolumeFsReadStream

​stream.recv()

​stream.collect()

​stream.Symbol.asyncIterator

​stream.Symbol.asyncDispose

​VolumeFsWriteSink

​sink.write()

​sink.close()

​sink.Symbol.asyncDispose

​MountBuilder

​mount.owned()

​mount.owner()

Volume

Volume.getDefault()

Volume.builder()

Volume.get()

Volume.list()

Volume.remove()

volume.fs()

VolumeBuilder

volumeBuilder.directory()

volumeBuilder.disk()

volumeBuilder.size()

volumeBuilder.quota()

volumeBuilder.label()

volumeBuilder.build()

volumeBuilder.create()

VolumeFs

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

VolumeHandle

handle.fs()

handle.remove()

VolumeFsReadStream

stream.recv()

stream.collect()

stream.Symbol.asyncIterator

stream.Symbol.asyncDispose

VolumeFsWriteSink

sink.write()

sink.close()

sink.Symbol.asyncDispose

MountBuilder

mount.owned()

mount.owner()