Filesystem

TypeScript SDK - Filesystem API reference

See Filesystem for usage examples and extensible backends.

SandboxFs

Filesystem handle for a running sandbox. Obtained via sb.fs(). All operations go through the same host-guest channel as command execution — no SSH, no network involved. For bulk file operations, consider using volumes instead.

const fs = sandbox.fs();

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

---

copy()

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

Copy a file within the sandbox.

Parameters

Name	Type	Description
from	string	Source path
to	string	Destination path

---

copyFromHost()

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

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

Parameters

Name	Type	Description
hostPath	string	Path on the host filesystem
guestPath	string	Destination path inside the sandbox

---

copyToHost()

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

Copy a file from the sandbox to the host machine.

Parameters

Name	Type	Description
guestPath	string	Path inside the sandbox
hostPath	string	Destination path on the host

---

exists()

exists(path: string): Promise<boolean>

Check whether a path exists inside the sandbox.

Parameters

Name	Type	Description
path	string	Absolute path inside the guest

Returns

Type	Description
Promise<boolean>	true if the path exists

---

list()

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

List the entries in a directory.

Parameters

Name	Type	Description
path	string	Absolute directory path inside the guest

Returns

Type	Description
Promise<FsEntry[]>	Directory entries

---

mkdir()

mkdir(path: string): Promise<void>

Create a directory. Parent directories must already exist.

Parameters

Name	Type	Description
path	string	Absolute directory path

---

read()

read(path: string): Promise<Uint8Array>

Read the entire contents of a file as raw bytes.

Parameters

Name	Type	Description
path	string	Absolute path inside the guest (e.g. "/app/config.json")

Returns

Type	Description
Promise<Uint8Array>	File contents as raw bytes

---

readStream()

readStream(path: string): Promise<FsReadStream>

Open a streaming reader for a file. Data is transferred in chunks of approximately 3 MiB each. Use this for files too large to fit in memory.

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

Parameters

Name	Type	Description
path	string	Absolute path inside the guest

Returns

Type	Description
Promise<FsReadStream>	Async stream that yields chunks of file data

---

readToString()

readToString(path: string): Promise<string>

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

Parameters

Name	Type	Description
path	string	Absolute path inside the guest

Returns

Type	Description
Promise<string>	File contents as a string

---

remove()

remove(path: string): Promise<void>

Remove a file.

Parameters

Name	Type	Description
path	string	Absolute file path

---

removeDir()

removeDir(path: string): Promise<void>

Remove a directory.

Parameters

Name	Type	Description
path	string	Absolute directory path

---

rename()

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

Rename or move a file or directory within the sandbox.

Parameters

Name	Type	Description
from	string	Current path
to	string	New path

---

stat()

stat(path: string): Promise<FsMetadata>

Get detailed metadata for a file or directory.

Parameters

Name	Type	Description
path	string	Absolute path inside the guest

Returns

Type	Description
Promise<FsMetadata>	File metadata

---

write()

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

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

Name	Type	Description
path	string	Absolute path inside the guest
data	Uint8Array | string	File content

---

writeStream()

writeStream(path: string): Promise<FsWriteSink>

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

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

Parameters

Name	Type	Description
path	string	Absolute path inside the guest

Returns

Type	Description
Promise<FsWriteSink>	Streaming writer

---

Types

FsEntry

Metadata for a single directory entry, returned by list().

Field	Type	Description
path	string	File path
kind	FsEntryKind	Type of entry
size	number	File size in bytes
mode	number	Unix permission bits
modified	Date | null	Last modified timestamp

FsEntryKind

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

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

FsMetadata

Detailed file metadata, returned by stat().

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
created	Date | null	Creation timestamp

FsReadStream

Async stream for reading a file in chunks. Obtained via readStream(). AsyncIterable<Uint8Array> and AsyncDisposable.

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>	Use with for await...of
[Symbol.asyncDispose]()	Promise<void>	Stop reading; safe to use with await using

FsWriteSink

Streaming writer returned by writeStream(). AsyncDisposable.

Method	Parameters	Description
write(data)	Uint8Array | string	Append a chunk
close()	-	Flush and close. Idempotent.
[Symbol.asyncDispose]()	-	Calls close()