---
url: >-
  https://adk.nht.io/api/@nhtio/adk/batteries/sandbox/interfaces/SandboxFileSystem.md
description: >-
  Filesystem capability with no copy primitive; traversal is complete and
  terminal-framed.
---

# Interface: SandboxFileSystem

Defined in: [src/batteries/sandbox/contracts/file\_system.ts:6](https://github.com/NHTIO/ADK/blob/v1.20260824.1/src/src/batteries/sandbox/contracts/file_system.ts#L6)

Filesystem capability with no copy primitive; traversal is complete and terminal-framed.

## Methods

### list()

```ts
list(path: string, o: {
  maxDepth: number;
  signal?: AbortSignal;
}): AsyncIterable<ListFrame>;
```

Defined in: [src/batteries/sandbox/contracts/file\_system.ts:17](https://github.com/NHTIO/ADK/blob/v1.20260824.1/src/src/batteries/sandbox/contracts/file_system.ts#L17)

Lazily yield every item, followed by exactly one mandatory done frame.

#### Parameters

| Parameter    | Type                                                  |
| ------------ | ----------------------------------------------------- |
| `path`       | `string`                                              |
| `o`          | { `maxDepth`: `number`; `signal?`: `AbortSignal`; } |
| `o.maxDepth` | `number`                                              |
| `o.signal?`  | `AbortSignal`                                         |

#### Returns

`AsyncIterable`<[`ListFrame`](../type-aliases/ListFrame.md)>

***

### read()

```ts
read(path: string, o?: {
  signal?: AbortSignal;
}): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
```

Defined in: [src/batteries/sandbox/contracts/file\_system.ts:19](https://github.com/NHTIO/ADK/blob/v1.20260824.1/src/src/batteries/sandbox/contracts/file_system.ts#L19)

Open a fresh, replayable byte stream; non-regular kinds are refused by adapters.

#### Parameters

| Parameter   | Type                            |
| ----------- | ------------------------------- |
| `path`      | `string`                        |
| `o?`        | { `signal?`: `AbortSignal`; } |
| `o.signal?` | `AbortSignal`                   |

#### Returns

`Promise`<`ReadableStream`<`Uint8Array`<`ArrayBufferLike`>>>

***

### stat()

```ts
stat(path: string): Promise<{
  dev?: number;
  ino?: number;
  kind: "other" | "file" | "dir" | "symlink";
  mtimeMs?: number;
  size: number;
  version: string;
}>;
```

Defined in: [src/batteries/sandbox/contracts/file\_system.ts:8](https://github.com/NHTIO/ADK/blob/v1.20260824.1/src/src/batteries/sandbox/contracts/file_system.ts#L8)

Return metadata. A changed version token is evidence of change; equality is not a no-change guarantee.

#### Parameters

| Parameter | Type     |
| --------- | -------- |
| `path`    | `string` |

#### Returns

`Promise`<{
`dev?`: `number`;
`ino?`: `number`;
`kind`: `"other"` | `"file"` | `"dir"` | `"symlink"`;
`mtimeMs?`: `number`;
`size`: `number`;
`version`: `string`;
}>

***

### write()

```ts
write(
   path: string,
   bytes:
  | Uint8Array<ArrayBufferLike>
  | ReadableStream<Uint8Array<ArrayBufferLike>>,
   o?: {
  signal?: AbortSignal;
}): Promise<void>;
```

Defined in: [src/batteries/sandbox/contracts/file\_system.ts:21](https://github.com/NHTIO/ADK/blob/v1.20260824.1/src/src/batteries/sandbox/contracts/file_system.ts#L21)

Write bytes without imposing a battery-level size cap.

#### Parameters

| Parameter   | Type                                                                                          |
| ----------- | --------------------------------------------------------------------------------------------- |
| `path`      | `string`                                                                                      |
| `bytes`     | | `Uint8Array`<`ArrayBufferLike`> | `ReadableStream`<`Uint8Array`<`ArrayBufferLike`>> |
| `o?`        | { `signal?`: `AbortSignal`; }                                                               |
| `o.signal?` | `AbortSignal`                                                                                 |

#### Returns

`Promise`<`void`>