Filesystem - microsandbox

Read and write files inside a running sandbox over the same host-guest channel as command execution: no SSH, no network. Obtain a handle with sandbox.fs(). See Filesystem for usage examples. For bulk transfers, consider a bind-mounted volume instead.

Typical flow

const fs = sandbox.fs();

await fs.write("/tmp/config.json", '{"debug": true}');     // write
const content = await fs.readToString("/tmp/config.json"); // read back
console.log(content);

for (const entry of await fs.list("/tmp")) {               // list
  console.log(entry.path);
}

SandboxFsOps

Filesystem handle for a running sandbox, obtained via sandbox.fs(). Every method is async and returns a Promise. Paths are absolute inside the guest.

fs.read()

read(path: string): Promise<Uint8Array>

Example

const bytes = await fs.read("/app/logo.png");
console.log(`${bytes.byteLength} bytes`);

Read the entire contents of a file as raw bytes.

Parameters

pathstring

Absolute path inside the guest (e.g. “/app/config.json”).

Returns

Promise<Uint8Array>

File contents as raw bytes.

fs.readToString()

readToString(path: string): Promise<string>

Example

const text = await fs.readToString("/etc/hostname");
console.log(text.trim());

Read the entire contents of a file and decode it as UTF-8.

Parameters

pathstring

Absolute path inside the guest.

Returns

Promise<string>

File contents as a string.

fs.write()

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

Example

await fs.write("/tmp/config.json", '{"debug": true}');

Write content to a file, creating it if it doesn’t exist and overwriting if it does. Parent directories must already exist. string payloads are encoded as UTF-8.

Parameters

pathstring

Absolute path inside the guest.

dataUint8Array | string

File content. Strings are written as UTF-8.

fs.readStream()

readStream(path: string): Promise<FsReadStream>

Example

for await (const chunk of await fs.readStream("/var/log/syslog")) {
  process.stdout.write(chunk); // chunk is a Uint8Array
}

Open a streaming reader for a file. Data is transferred in chunks. Use this for files too large to fit in memory. The returned FsReadStream is an AsyncIterable<Uint8Array>, so it works with for await...of.

Parameters

pathstring

Absolute path inside the guest.

Returns

Promise<FsReadStream>

Async stream that yields chunks of file data.

fs.writeStream()

writeStream(path: string): Promise<FsWriteSink>

Example

await using sink = await fs.writeStream("/tmp/big.bin");
await sink.write(new Uint8Array(1 << 20));

Open a streaming writer for a file. Use this for files too large to hold in memory; pair with await using so the FsWriteSink closes itself when the scope exits.

Parameters

pathstring

Absolute path inside the guest.

Returns

Promise<FsWriteSink>

Streaming writer.

fs.list()

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

Example

for (const entry of await fs.list("/app")) {
  console.log(`${entry.kind}\t${entry.path}`);
}

List the entries in a directory.

Parameters

pathstring

Absolute directory path inside the guest.

Returns

Promise<FsEntry[]>

Directory entries.

fs.mkdir()

mkdir(path: string): Promise<void>

Example

await fs.mkdir("/app/data");

Create a directory. Parent directories must already exist.

Parameters

pathstring

Absolute directory path.

fs.removeDir()

removeDir(path: string): Promise<void>

Example

await fs.removeDir("/app/data");

Remove a directory.

Parameters

pathstring

Absolute directory path.

fs.remove()

remove(path: string): Promise<void>

Example

await fs.remove("/tmp/config.json");

Remove a file.

Parameters

pathstring

Absolute file path.

fs.stat()

stat(path: string): Promise<FsMetadata>

Example

const meta = await fs.stat("/app/config.json");
console.log(`${meta.size} bytes, mode ${meta.mode.toString(8)}`);

Get detailed metadata for a file or directory.

Parameters

pathstring

Absolute path inside the guest.

Returns

Promise<FsMetadata>

File metadata.

fs.exists()

exists(path: string): Promise<boolean>

Example

if (await fs.exists("/app/config.json")) {
  console.log("config present");
}

Check whether a path exists inside the sandbox.

Parameters

pathstring

Absolute path inside the guest.

Returns

Promise<boolean>

true if the path exists.

fs.copy()

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

Example

await fs.copy("/app/config.json", "/app/config.bak.json");

Copy a file within the sandbox.

Parameters

fromstring

Source path.

tostring

Destination path.

fs.rename()

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

Example

await fs.rename("/tmp/draft.txt", "/tmp/final.txt");

Rename or move a file or directory within the sandbox.

Parameters

fromstring

Current path.

tostring

New path.

fs.copyFromHost()

copyFromHost(hostPath: string, guestPath: string): Promise<void>

Example

await fs.copyFromHost("./seed.db", "/app/data/seed.db");

Copy a file from the host machine into the sandbox. For transferring many files, consider a bind-mounted volume instead.

Parameters

hostPathstring

Path on the host filesystem.

guestPathstring

Destination path inside the sandbox.

fs.copyToHost()

copyToHost(guestPath: string, hostPath: string): Promise<void>

Example

await fs.copyToHost("/app/out/report.pdf", "./report.pdf");

Copy a file from the sandbox to the host machine.

Parameters

guestPathstring

Path inside the sandbox.

hostPathstring

Destination path on the host.

Types

FsEntry

Returned by list()

Metadata for a single directory entry.

Field	Type	Description
path	`string`	Entry path
kind	`FsEntryKind`	Type of entry
size	`number`	File size in bytes
mode	`number`	Unix permission bits
modified	`Date \| null`	Last modified timestamp, or `null` if unavailable

FsMetadata

Returned by stat()

Detailed file metadata.

Field	Type	Description
kind	`FsEntryKind`	Type of entry
size	`number`	File size in bytes
mode	`number`	Unix permission bits
readonly	`boolean`	Whether the file is read-only
modified	`Date \| null`	Last modified timestamp, or `null` if unavailable
created	`Date \| null`	Creation timestamp, or `null` if unavailable

FsEntryKind

Used by FsEntry.kind · FsMetadata.kind

type FsEntryKind = "file" | "directory" | "symlink" | "other";

Value	Description
`"file"`	Regular file
`"directory"`	Directory
`"symlink"`	Symbolic link
`"other"`	Other entry type

FsReadStream

Returned by readStream()

Async stream for reading a file in chunks. Implements AsyncIterable<Uint8Array> and AsyncDisposable, so it works with for await...of and await using.

Method	Returns	Description
`recv()`	`Promise<Uint8Array \| null>`	Receive the next chunk. Returns `null` when the file has been fully read.
`collect()`	`Promise<Uint8Array>`	Drain the stream into a single buffer
`[Symbol.asyncIterator]()`	`AsyncIterator<Uint8Array>`	Iterate chunks with `for await...of`
`[Symbol.asyncDispose]()`	`Promise<void>`	Stop reading; runs on `await using` scope exit

FsWriteSink

Returned by writeStream()

Streaming writer for a file. Implements AsyncDisposable, so it can be paired with await using.

Method	Parameters	Returns	Description
`write(data)`	`Uint8Array \| string`	`Promise<void>`	Append a chunk. Strings are encoded as UTF-8.
`close()`	-	`Promise<void>`	Flush and close. Idempotent.
`[Symbol.asyncDispose]()`	-	`Promise<void>`	Calls `close()` on `await using` scope exit

​SandboxFsOps

​fs.read()

​fs.readToString()

​fs.write()

​fs.readStream()

​fs.writeStream()

​fs.list()

​fs.mkdir()

​fs.removeDir()

​fs.remove()

​fs.stat()

​fs.exists()

​fs.copy()

​fs.rename()

​fs.copyFromHost()

​fs.copyToHost()

​Types

​FsEntry

​FsMetadata

​FsEntryKind

​FsReadStream

​FsWriteSink

SandboxFsOps

fs.read()

fs.readToString()

fs.write()

fs.readStream()

fs.writeStream()

fs.list()

fs.mkdir()

fs.removeDir()

fs.remove()

fs.stat()

fs.exists()

fs.copy()

fs.rename()

fs.copyFromHost()

fs.copyToHost()

Types

FsEntry

FsMetadata

FsEntryKind

FsReadStream

FsWriteSink