Volumes - microsandbox

Create, manage, and mount named volumes. See Volumes for usage examples.

Volume

Instance properties

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.

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.

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.

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<readonly [string, string]> Metadata labels

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

​Volume

​volume.name

​volume.path

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

​handle.kind

​handle.quotaMib

​handle.usedBytes

​handle.capacityBytes

​handle.diskFormat

​handle.diskFstype

​handle.labels

​handle.createdAt

​handle.fs()

​handle.remove()

​VolumeFsReadStream

​stream.recv()

​stream.collect()

​stream.Symbol.asyncIterator

​stream.Symbol.asyncDispose

​VolumeFsWriteSink

​sink.write()

​sink.close()

​sink.Symbol.asyncDispose

Volume

volume.name

volume.path

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

handle.kind

handle.quotaMib

handle.usedBytes

handle.capacityBytes

handle.diskFormat

handle.diskFstype

handle.labels

handle.createdAt

handle.fs()

handle.remove()

VolumeFsReadStream

stream.recv()

stream.collect()

stream.Symbol.asyncIterator

stream.Symbol.asyncDispose

VolumeFsWriteSink

sink.write()

sink.close()

sink.Symbol.asyncDispose