> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Filesystem

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

<p className="msb-label" id="typical-flow">Typical flow</p>

```typescript theme={null}
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.

#### <span className="msb-recv">fs.</span><span className="msb-hn">read()</span>

```typescript theme={null}
read(path: string): Promise<Uint8Array>
```

<Accordion title="Example">
  ```typescript theme={null}
  const bytes = await fs.read("/app/logo.png");
  console.log(`${bytes.byteLength} bytes`);
  ```
</Accordion>

Read the entire contents of a file as raw bytes.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Absolute path inside the guest (e.g. <code>"/app/config.json"</code>).</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Promise\<Uint8Array></span></div>
    <div className="msb-param-desc">File contents as raw bytes.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">readToString()</span>

```typescript theme={null}
readToString(path: string): Promise<string>
```

<Accordion title="Example">
  ```typescript theme={null}
  const text = await fs.readToString("/etc/hostname");
  console.log(text.trim());
  ```
</Accordion>

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

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Absolute path inside the guest.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Promise\<string></span></div>
    <div className="msb-param-desc">File contents as a string.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">write()</span>

```typescript theme={null}
write(path: string, data: Uint8Array | string): Promise<void>
```

<Accordion title="Example">
  ```typescript theme={null}
  await fs.write("/tmp/config.json", '{"debug": true}');
  ```
</Accordion>

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.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Absolute path inside the guest.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>data</code><span className="msb-type">Uint8Array | string</span></div>
    <div className="msb-param-desc">File content. Strings are written as UTF-8.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">readStream()</span>

```typescript theme={null}
readStream(path: string): Promise<FsReadStream>
```

<Accordion title="Example">
  ```typescript theme={null}
  for await (const chunk of await fs.readStream("/var/log/syslog")) {
    process.stdout.write(chunk); // chunk is a Uint8Array
  }
  ```
</Accordion>

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<Uint8Array>`, so it works with `for await...of`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Absolute path inside the guest.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#fsreadstream">Promise\<FsReadStream></a></div>
    <div className="msb-param-desc">Async stream that yields chunks of file data.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">writeStream()</span>

```typescript theme={null}
writeStream(path: string): Promise<FsWriteSink>
```

<Accordion title="Example">
  ```typescript theme={null}
  await using sink = await fs.writeStream("/tmp/big.bin");
  await sink.write(new Uint8Array(1 << 20));
  ```
</Accordion>

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.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Absolute path inside the guest.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#fswritesink">Promise\<FsWriteSink></a></div>
    <div className="msb-param-desc">Streaming writer.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">list()</span>

```typescript theme={null}
list(path: string): Promise<FsEntry[]>
```

<Accordion title="Example">
  ```typescript theme={null}
  for (const entry of await fs.list("/app")) {
    console.log(`${entry.kind}\t${entry.path}`);
  }
  ```
</Accordion>

List the entries in a directory.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Absolute directory path inside the guest.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#fsentry">Promise\<FsEntry\[]></a></div>
    <div className="msb-param-desc">Directory entries.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">mkdir()</span>

```typescript theme={null}
mkdir(path: string): Promise<void>
```

<Accordion title="Example">
  ```typescript theme={null}
  await fs.mkdir("/app/data");
  ```
</Accordion>

Create a directory. Parent directories must already exist.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Absolute directory path.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">removeDir()</span>

```typescript theme={null}
removeDir(path: string): Promise<void>
```

<Accordion title="Example">
  ```typescript theme={null}
  await fs.removeDir("/app/data");
  ```
</Accordion>

Remove a directory.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Absolute directory path.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">remove()</span>

```typescript theme={null}
remove(path: string): Promise<void>
```

<Accordion title="Example">
  ```typescript theme={null}
  await fs.remove("/tmp/config.json");
  ```
</Accordion>

Remove a file.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Absolute file path.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">stat()</span>

```typescript theme={null}
stat(path: string): Promise<FsMetadata>
```

<Accordion title="Example">
  ```typescript theme={null}
  const meta = await fs.stat("/app/config.json");
  console.log(`${meta.size} bytes, mode ${meta.mode.toString(8)}`);
  ```
</Accordion>

Get detailed metadata for a file or directory.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Absolute path inside the guest.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#fsmetadata">Promise\<FsMetadata></a></div>
    <div className="msb-param-desc">File metadata.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">exists()</span>

```typescript theme={null}
exists(path: string): Promise<boolean>
```

<Accordion title="Example">
  ```typescript theme={null}
  if (await fs.exists("/app/config.json")) {
    console.log("config present");
  }
  ```
</Accordion>

Check whether a path exists inside the sandbox.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Absolute path inside the guest.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Promise\<boolean></span></div>
    <div className="msb-param-desc"><code>true</code> if the path exists.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">copy()</span>

```typescript theme={null}
copy(from: string, to: string): Promise<void>
```

<Accordion title="Example">
  ```typescript theme={null}
  await fs.copy("/app/config.json", "/app/config.bak.json");
  ```
</Accordion>

Copy a file within the sandbox.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>from</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Source path.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>to</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Destination path.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">rename()</span>

```typescript theme={null}
rename(from: string, to: string): Promise<void>
```

<Accordion title="Example">
  ```typescript theme={null}
  await fs.rename("/tmp/draft.txt", "/tmp/final.txt");
  ```
</Accordion>

Rename or move a file or directory within the sandbox.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>from</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Current path.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>to</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">New path.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">copyFromHost()</span>

```typescript theme={null}
copyFromHost(hostPath: string, guestPath: string): Promise<void>
```

<Accordion title="Example">
  ```typescript theme={null}
  await fs.copyFromHost("./seed.db", "/app/data/seed.db");
  ```
</Accordion>

Copy a file from the host machine into the sandbox. For transferring many files, consider a [bind-mounted volume](/sandboxes/volumes) instead.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>hostPath</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Path on the host filesystem.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>guestPath</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Destination path inside the sandbox.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">copyToHost()</span>

```typescript theme={null}
copyToHost(guestPath: string, hostPath: string): Promise<void>
```

<Accordion title="Example">
  ```typescript theme={null}
  await fs.copyToHost("/app/out/report.pdf", "./report.pdf");
  ```
</Accordion>

Copy a file from the sandbox to the host machine.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>guestPath</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Path inside the sandbox.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>hostPath</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Destination path on the host.</div>
  </div>
</div>

## Types

### FsEntry

<p className="msb-backref">Returned by <a href="#fs-list">list()</a></p>

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

<p className="msb-backref">Returned by <a href="#fs-stat">stat()</a></p>

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

<p className="msb-backref">Used by <a href="#fsentry">FsEntry.kind</a> · <a href="#fsmetadata">FsMetadata.kind</a></p>

```typescript theme={null}
type FsEntryKind = "file" | "directory" | "symlink" | "other";
```

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

### FsReadStream

<p className="msb-backref">Returned by <a href="#fs-readstream">readStream()</a></p>

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

<p className="msb-backref">Returned by <a href="#fs-writestream">writeStream()</a></p>

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   |