Filesystem

Read and write files inside a running sandbox. See Filesystem for usage examples.

SandboxFsOps

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.

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.

stream.recv()

recv()

Receive the next chunk. Returns null when the file has been fully read.

Returns

Promise<Uint8Array \| null>

stream.collect()

collect()

Drain the stream into a single buffer

Returns

Promise<Uint8Array>

stream.Symbol.asyncIterator

[Symbol.asyncIterator]()

Iterate chunks with for await...of

Returns

AsyncIterator<Uint8Array>

stream.Symbol.asyncDispose

[Symbol.asyncDispose]()

Stop reading; runs on await using scope exit

Returns

Promise<void>

FsWriteSink

Returned by writeStream()

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

sink.write()

write(data)

Append a chunk. Strings are encoded as UTF-8.

Returns

Promise<void>

sink.close()

close()

Flush and close. Idempotent.

Returns

Promise<void>

sink.Symbol.asyncDispose

[Symbol.asyncDispose]()

Calls close() on await using scope exit

Returns

Promise<void>

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

Getting Started

SDKs

CLI

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

FsReadStream

stream.recv()

stream.collect()

stream.Symbol.asyncIterator

stream.Symbol.asyncDispose

FsWriteSink

sink.write()

sink.close()

sink.Symbol.asyncDispose

Types

FsEntry

FsMetadata

FsEntryKind

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

​FsReadStream

​stream.recv()

​stream.collect()

​stream.Symbol.asyncIterator

​stream.Symbol.asyncDispose

​FsWriteSink

​sink.write()

​sink.close()

​sink.Symbol.asyncDispose

​Types

​FsEntry

​FsMetadata

​FsEntryKind

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

FsReadStream

stream.recv()

stream.collect()

stream.Symbol.asyncIterator

stream.Symbol.asyncDispose

FsWriteSink

sink.write()

sink.close()

sink.Symbol.asyncDispose

Types

FsEntry

FsMetadata

FsEntryKind