---
title: Filesystem
description: TypeScript SDK - Filesystem API reference
---
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](/sandboxes/filesystem) for usage examples. For bulk transfers, consider a [bind-mounted volume](/sandboxes/volumes) instead.
Typical flow
```typescript
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()`](/sdk/typescript/sandbox#sandboxfs). Every method is async and returns a `Promise`. Paths are absolute inside the guest.
---
#### fs.read()
instanceasync
```typescript
read(path: string): Promise
```
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.
```typescript
const bytes = await fs.read("/app/logo.png");
console.log(`${bytes.byteLength} bytes`);
```
---
#### fs.readToString()
instanceasync
```typescript
readToString(path: string): Promise
```
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.
```typescript
const text = await fs.readToString("/etc/hostname");
console.log(text.trim());
```
---
#### fs.write()
instanceasync
```typescript
write(path: string, data: Uint8Array | string): Promise
```
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.
```typescript
await fs.write("/tmp/config.json", '{"debug": true}');
```
---
#### fs.readStream()
instanceasync
```typescript
readStream(path: string): Promise
```
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`](#fsreadstream) is an `AsyncIterable`, so it works with `for await...of`.
Parameters
pathstring
Absolute path inside the guest.
Returns
Async stream that yields chunks of file data.
```typescript
for await (const chunk of await fs.readStream("/var/log/syslog")) {
process.stdout.write(chunk); // chunk is a Uint8Array
}
```
---
#### fs.writeStream()
instanceasync
```typescript
writeStream(path: string): Promise
```
Open a streaming writer for a file. Use this for files too large to hold in memory; pair with `await using` so the [`FsWriteSink`](#fswritesink) closes itself when the scope exits.
Parameters
pathstring
Absolute path inside the guest.
Returns
```typescript
await using sink = await fs.writeStream("/tmp/big.bin");
await sink.write(new Uint8Array(1 << 20));
```
---
#### fs.list()
instanceasync
```typescript
list(path: string): Promise
```
List the entries in a directory.
Parameters
pathstring
Absolute directory path inside the guest.
Returns
```typescript
for (const entry of await fs.list("/app")) {
console.log(`${entry.kind}\t${entry.path}`);
}
```
---
#### fs.mkdir()
instanceasync
```typescript
mkdir(path: string): Promise
```
Create a directory. Parent directories must already exist.
Parameters
pathstring
Absolute directory path.
```typescript
await fs.mkdir("/app/data");
```
---
#### fs.removeDir()
instanceasync
```typescript
removeDir(path: string): Promise
```
Remove a directory.
Parameters
pathstring
Absolute directory path.
```typescript
await fs.removeDir("/app/data");
```
---
#### fs.remove()
instanceasync
```typescript
remove(path: string): Promise
```
Remove a file.
Parameters
pathstring
Absolute file path.
```typescript
await fs.remove("/tmp/config.json");
```
---
#### fs.stat()
instanceasync
```typescript
stat(path: string): Promise
```
Get detailed metadata for a file or directory.
Parameters
pathstring
Absolute path inside the guest.
Returns
```typescript
const meta = await fs.stat("/app/config.json");
console.log(`${meta.size} bytes, mode ${meta.mode.toString(8)}`);
```
---
#### fs.exists()
instanceasync
```typescript
exists(path: string): Promise
```
Check whether a path exists inside the sandbox.
Parameters
pathstring
Absolute path inside the guest.
Returns
Promise<boolean>
true if the path exists.
```typescript
if (await fs.exists("/app/config.json")) {
console.log("config present");
}
```
---
#### fs.copy()
instanceasync
```typescript
copy(from: string, to: string): Promise
```
Copy a file within the sandbox.
Parameters
tostring
Destination path.
```typescript
await fs.copy("/app/config.json", "/app/config.bak.json");
```
---
#### fs.rename()
instanceasync
```typescript
rename(from: string, to: string): Promise
```
Rename or move a file or directory within the sandbox.
Parameters
```typescript
await fs.rename("/tmp/draft.txt", "/tmp/final.txt");
```
---
#### fs.copyFromHost()
instanceasync
```typescript
copyFromHost(hostPath: string, guestPath: string): Promise
```
Copy a file from the host machine into the sandbox. For transferring many files, consider a [bind-mounted volume](/sandboxes/volumes) instead.
Parameters
hostPathstring
Path on the host filesystem.
guestPathstring
Destination path inside the sandbox.
```typescript
await fs.copyFromHost("./seed.db", "/app/data/seed.db");
```
---
#### fs.copyToHost()
instanceasync
```typescript
copyToHost(guestPath: string, hostPath: string): Promise
```
Copy a file from the sandbox to the host machine.
Parameters
guestPathstring
Path inside the sandbox.
hostPathstring
Destination path on the host.
```typescript
await fs.copyToHost("/app/out/report.pdf", "./report.pdf");
```
---
## Types
### FsEntry
interface
Returned by list()
Metadata for a single directory entry.
| Field | Type | Description |
|-------|------|-------------|
| path | `string` | Entry path |
| kind | [`FsEntryKind`](#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
interface
Returned by stat()
Detailed file metadata.
| Field | Type | Description |
|-------|------|-------------|
| kind | [`FsEntryKind`](#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
type
Used by FsEntry.kind · FsMetadata.kind
```typescript
type FsEntryKind = "file" | "directory" | "symlink" | "other";
```
| Value | Description |
|-------|-------------|
| `"file"` | Regular file |
| `"directory"` | Directory |
| `"symlink"` | Symbolic link |
| `"other"` | Other entry type |
### FsReadStream
class
Returned by readStream()
Async stream for reading a file in chunks. Implements `AsyncIterable` and `AsyncDisposable`, so it works with `for await...of` and `await using`.
| Method | Returns | Description |
|--------|---------|-------------|
| `recv()` | `Promise` | Receive the next chunk. Returns `null` when the file has been fully read. |
| `collect()` | `Promise` | Drain the stream into a single buffer |
| `[Symbol.asyncIterator]()` | `AsyncIterator` | Iterate chunks with `for await...of` |
| `[Symbol.asyncDispose]()` | `Promise` | Stop reading; runs on `await using` scope exit |
### FsWriteSink
class
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` | Append a chunk. Strings are encoded as UTF-8. |
| `close()` | - | `Promise` | Flush and close. Idempotent. |
| `[Symbol.asyncDispose]()` | - | `Promise` | Calls `close()` on `await using` scope exit |