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

# Filesystem methods

> Read run files, captured changes, sandbox logs, and live processes.

A `RunFilesystem` belongs to a trial, analysis, or task check. Each exposes the same methods.

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const fs = trials().filesystem(trialId);
  // Or: analyses().filesystem(analysisId)
  // Or: checks().taskFilesystem(checkId, taskCheckId)
  ```

  ```python Python theme={"dark"}
  fs = trials().filesystem(trial_id)
  # Or: analyses().filesystem(analysis_id)
  # Or: checks().task_filesystem(check_id, task_check_id)
  ```
</CodeGroup>

Read [filesystem states](/sdk-reference/filesystem) before choosing a source. Omit `source` to use the available source; pass `live` or `capture` to request one explicitly.

| Files                                                                                                        | Live observation                                                                            |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| [status](#status), [list](#list), [read](#read), [search](#search), [changes](#changes), [archive](#archive) | [watch](#watch), [events](#events), [logs](#logs), [logEvents](#logevents), [procs](#procs) |

[Task package files](#task-package-files) provide a smaller, read-only interface.

## status

Return `FilesystemStatus`: state, live box, watcher type, root, work directory, and capture record.

<Accordion title="Signature">
  <CodeGroup>
    ```ts TypeScript signature theme={"dark"}
    status(): Promise<FilesystemStatus>;
    ```

    ```python Python signature theme={"dark"}
    async def status() -> FilesystemStatus: ...
    ```
  </CodeGroup>
</Accordion>

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const status = await fs.status();
  ```

  ```python Python theme={"dark"}
  status = await fs.status()
  ```
</CodeGroup>

States: `live`, `capturing`, `captured`, `none`. A null `capture` means no settled capture record. A capture can be incomplete: inspect `left_out` before assuming every file was retained. See [filesystem result fields](/sdk-reference/types#filesystem-results).

## list

Read one directory page, sorted by name. Returns `FilesystemListing`.

<Accordion title="Signature">
  <CodeGroup>
    ```ts TypeScript signature theme={"dark"}
    list(
      options?: FilesystemListOptions
    ): Promise<FilesystemListing>;
    ```

    ```python Python signature theme={"dark"}
    async def list(
        *,
        path: str = '/',
        source: Optional[FilesystemSource] = None,
        cursor: Optional[str] = None,
        limit: Optional[int] = None,
    ) -> FilesystemListing: ...
    ```
  </CodeGroup>
</Accordion>

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const page = await fs.list({
    path: "/app",
    limit: 100
  });
  ```

  ```python Python theme={"dark"}
  page = await fs.list(
      path='/app',
      limit=100,
  )
  ```
</CodeGroup>

Optional `path` defaults to `/`; `source` selects `live` or `capture`; `cursor` continues the page; `limit` defaults to 500 (maximum 1,000).

Returns `path`, `source`, `entries`, `next_cursor`, and elapsed `ms`. Both languages use `next_cursor` here. An entry with `captured: false` has no retained bytes. Read `left_out` for an omitted or failed capture; otherwise it may be an untouched image file. A missing directory returns `not_found`.

## read

Read raw bytes from an absolute sandbox path. Returns `Buffer` / `bytes`.

<Accordion title="Signature">
  <CodeGroup>
    ```ts TypeScript signature theme={"dark"}
    read(
      path: string,
      options?: FilesystemReadOptions
    ): Promise<Buffer>;
    ```

    ```python Python signature theme={"dark"}
    async def read(
        path: str,
        *,
        source: Optional[FilesystemSource] = None,
        start: Optional[int] = None,
        end: Optional[int] = None,
        suffix: Optional[int] = None,
    ) -> bytes: ...
    ```
  </CodeGroup>
</Accordion>

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const bytes = await fs.read("/app/result.txt", {
    range: {
      suffix: 4096
    }
  });
  ```

  ```python Python theme={"dark"}
  data = await fs.read(
      '/app/result.txt',
      suffix=4096,
  )
  ```
</CodeGroup>

Optional `source` chooses `live` or `capture`. For ranges, TypeScript uses `{ range: { start, end } }`; Python uses `start=` and `end=`. End is inclusive. Use `start` alone through EOF or `suffix` alone for the last N bytes. An oversized whole-file read returns 413; read slices instead.

## search

Search file contents. Returns `FilesystemSearchResult`, including hits and whether results were truncated.

<Accordion title="Signature">
  <CodeGroup>
    ```ts TypeScript signature theme={"dark"}
    search(
      options: FilesystemSearchOptions
    ): Promise<FilesystemSearchResult>;
    ```

    ```python Python signature theme={"dark"}
    async def search(
        q: str,
        *,
        path: str = '/',
        regex: bool = False,
        limit: Optional[int] = None,
        source: Optional[FilesystemSource] = None,
    ) -> FilesystemSearchResult: ...
    ```
  </CodeGroup>
</Accordion>

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const result = await fs.search({
    q: "TODO",
    path: "/app"
  });
  ```

  ```python Python theme={"dark"}
  result = await fs.search(
      'TODO',
      path='/app',
  )
  ```
</CodeGroup>

Required `q` is text; `regex: true` / `regex=True` interprets it as a regular expression. Optional `path` defaults to `/`; `limit` defaults to 200 (maximum 1,000); `source` selects `live` or `capture`.

Returns `hits[]` with `path`, `line`, `snippet`; plus `truncated`, `scope`, `source`, `ms`, and optional `image_files_excluded`. A whole-box search can take seconds. Captured search cannot inspect untouched image files.

## changes

Read created, modified, and removed paths by phase. Returns one `FilesystemChanges` page.

<Accordion title="Signature">
  <CodeGroup>
    ```ts TypeScript signature theme={"dark"}
    changes(
      options?: FilesystemChangesOptions
    ): Promise<FilesystemChanges>;
    ```

    ```python Python signature theme={"dark"}
    async def changes(
        *,
        source: Optional[FilesystemSource] = None,
        phase: Optional[Literal['setup', 'agent', 'verifier', 'all']] = None,
        cursor: Optional[str] = None,
        limit: Optional[int] = None,
    ) -> FilesystemChanges: ...
    ```
  </CodeGroup>
</Accordion>

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const page = await fs.changes({
    phase: "agent",
    limit: 100
  });
  ```

  ```python Python theme={"dark"}
  page = await fs.changes(
      phase='agent',
      limit=100,
  )
  ```
</CodeGroup>

Optional `phase`: `setup`, `agent`, `verifier`, or `all` (default); `source`: `live` or `capture`; `limit`: default 500, maximum 1,000; `cursor`: next page. Returns `source`, whole-list `total` and `changed_bytes`, page `items`, and `next_cursor`. Live changes require a recorded initial listing; otherwise the server returns `feature_unsupported`. For captured changes, `left_out` explains missing retained bytes.

## archive

Download a subtree as `.tar.gz`. The default path `/` requests the whole tree.

<Accordion title="Signature">
  <CodeGroup>
    ```ts TypeScript signature theme={"dark"}
    archive(
      options?: FilesystemArchiveOptions
    ): Promise<Buffer>;
    archive(
      options: FilesystemArchiveOptions & { to: string }
    ): Promise<string>;
    archive(
      options: FilesystemArchiveOptions & { stream: true },
    ): Promise<ReadableStream<Uint8Array>>;
    ```

    ```python Python signature theme={"dark"}
    async def archive(
        *,
        path: str = '/',
        source: Optional[FilesystemSource] = None,
        to: Optional[str] = None,
    ) -> bytes | str: ...
    ```
  </CodeGroup>
</Accordion>

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const path = await fs.archive({
    path: "/app",
    to: "./results"
  });
  ```

  ```python Python theme={"dark"}
  path = await fs.archive(
      path='/app',
      to='./results',
  )
  ```
</CodeGroup>

Optional `source` selects `live` or `capture`. No `to` returns `Buffer` / `bytes`; `to` saves into a directory and returns the file path. TypeScript also accepts `stream: true`; Python does not expose streaming. A live subtree too large to read within provider limits returns `feature_unsupported`.

## watch

Declare the folders currently open in your viewer. Replaces the watched set, with at most eight paths.

<Accordion title="Signature">
  <CodeGroup>
    ```ts TypeScript signature theme={"dark"}
    watch(paths: string[]): Promise<FilesystemWatchResult>;
    ```

    ```python Python signature theme={"dark"}
    async def watch(
        paths: List[str]
    ) -> FilesystemWatchResult: ...
    ```
  </CodeGroup>
</Accordion>

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const result = await fs.watch(["/app", "/logs"]);
  ```

  ```python Python theme={"dark"}
  result = await fs.watch(
      ['/app', '/logs'],
  )
  ```
</CodeGroup>

Required `paths: string[]`. Returns `watcher: "native" | "poll"` and `paths: string[]`. Poll-based change detection uses this set. This method registers folders; `events()` reads their changes.

## events

Iterate filesystem state and changes until the filesystem settles. Returns async `FilesystemStreamEvent` frames.

<Accordion title="Signature">
  <CodeGroup>
    ```ts TypeScript signature theme={"dark"}
    events(
      options?: FilesystemStreamOptions
    ): AsyncIterableIterator<FilesystemStreamEvent>;
    ```

    ```python Python signature theme={"dark"}
    async def events(
        *,
        last_event_id: Optional[str] = None,
    ) -> 'AsyncIterator[FilesystemStreamEvent]': ...
    ```
  </CodeGroup>
</Accordion>

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  for await (const event of fs.events()) {
    console.log(event.event, event.data);
  }
  ```

  ```python Python theme={"dark"}
  async for event in fs.events():
      print(event.event, event.data)
  ```
</CodeGroup>

Optional `lastEventId` / `last_event_id` resumes after a stored event id. TypeScript also accepts `signal`. A `state` frame after a resume request means relist the folder. Frames are `state`, `fs`, or `ping`; [event fields](/sdk-reference/types#filesystem-results) define the payloads.

## logs

Read one page of one sandbox log stream. Returns `SandboxLogLines`.

<Accordion title="Signature">
  <CodeGroup>
    ```ts TypeScript signature theme={"dark"}
    logs(
      options: SandboxLogOptions
    ): Promise<SandboxLogLines>;
    ```

    ```python Python signature theme={"dark"}
    async def logs(
        stream: SandboxLogStream,
        *,
        cursor: Optional[str] = None,
        limit: Optional[int] = None,
    ) -> SandboxLogLines: ...
    ```
  </CodeGroup>
</Accordion>

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const page = await fs.logs({
    stream: "agent",
    limit: 100
  });
  ```

  ```python Python theme={"dark"}
  page = await fs.logs(
      'agent',
      limit=100,
  )
  ```
</CodeGroup>

Required `stream`: `agent`, `verifier`, `setup`, `system`, or `metrics`. Optional `cursor` continues the stream; `limit` defaults to and is capped at 1,000. Returns `stream`, `lines`, `next_cursor`, and optional `reason` when no lines were retained. Each line has `seq`, nullable `t`, `fd` (`out` or `err`), and `line`.

## logEvents

Python: `log_events`. Iterate all sandbox log streams together. Ends after the box is gone and stored lines are drained.

<Accordion title="Signature">
  <CodeGroup>
    ```ts TypeScript signature theme={"dark"}
    logEvents(
      options?: FilesystemStreamOptions
    ): AsyncIterableIterator<SandboxLogEvent>;
    ```

    ```python Python signature theme={"dark"}
    async def log_events(
        *,
        last_event_id: Optional[str] = None,
    ) -> 'AsyncIterator[SandboxLogEvent]': ...
    ```
  </CodeGroup>
</Accordion>

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  for await (const event of fs.logEvents()) {
    if (event.event === "line")
      console.log(event.data.line);
  }
  ```

  ```python Python theme={"dark"}
  async for event in fs.log_events():
      if event.event == "line":
          print(event.data["line"])
  ```
</CodeGroup>

Optional `lastEventId` / `last_event_id` is `<stream>:<seq>`. TypeScript also accepts `signal`. Returns `SandboxLogEvent`: `line`, `state`, or `ping`. A line payload adds `stream` to `SandboxLogLine`.

## procs

Read the live sandbox’s process list. Returns `SandboxProcs`.

<Accordion title="Signature">
  <CodeGroup>
    ```ts TypeScript signature theme={"dark"}
    procs(): Promise<SandboxProcs>;
    ```

    ```python Python signature theme={"dark"}
    async def procs() -> SandboxProcs: ...
    ```
  </CodeGroup>
</Accordion>

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const processes = await fs.procs();
  console.log(processes.text);
  ```

  ```python Python theme={"dark"}
  processes = await fs.procs()
  print(processes.text)
  ```
</CodeGroup>

No arguments. `text` is the process listing; `ms` is elapsed server time. Once the box is gone, this returns 409 `filesystem_state`; a captured filesystem cannot supply live processes.

## Task package files

`datasets().taskFiles(ref, taskName)` / `task_files(ref, task_name)` returns `TaskPackageFiles`. Pin `ref` as `name@version`. This reads the retained task package, not a sandbox.

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const files = datasets().taskFiles(
    "my-tasks@1.0",
    "hello-world"
  );
  ```

  ```python Python theme={"dark"}
  files = datasets().task_files(
      "my-tasks@1.0",
      "hello-world"
  )
  ```
</CodeGroup>

## package.status

Read `TaskPackageFilesystemStatus`, the normal filesystem status plus `source: "package"` and `package_retained: boolean`. Its `state` is always `none`.

<Accordion title="Signature">
  <CodeGroup>
    ```ts TypeScript signature theme={"dark"}
    status(): Promise<TaskPackageFilesystemStatus>;
    ```

    ```python Python signature theme={"dark"}
    async def status() -> TaskPackageFilesystemStatus: ...
    ```
  </CodeGroup>
</Accordion>

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const status = await files.status();
  ```

  ```python Python theme={"dark"}
  status = await files.status()
  ```
</CodeGroup>

A false `package_retained` means package bytes are unavailable; file reads return `task_package_not_retained`.

## package.list

Read a page from the task directory. Returns `FilesystemListing` with `source: "package"`.

<Accordion title="Signature">
  <CodeGroup>
    ```ts TypeScript signature theme={"dark"}
    list(
      options?: Omit<FilesystemListOptions, "source">
    ): Promise<FilesystemListing>;
    ```

    ```python Python signature theme={"dark"}
    async def list(
        *,
        path: str = '/',
        cursor: Optional[str] = None,
        limit: Optional[int] = None,
    ) -> FilesystemListing: ...
    ```
  </CodeGroup>
</Accordion>

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const page = await files.list({
    path: "/tests"
  });
  ```

  ```python Python theme={"dark"}
  page = await files.list(path="/tests")
  ```
</CodeGroup>

Optional `path` defaults to `/`; `limit` defaults to 500 (maximum 1,000); `cursor` continues the page. There is no `source` selector.

## package.read

Read exact bytes from a retained task file. Returns `Buffer` / `bytes`.

<Accordion title="Signature">
  <CodeGroup>
    ```ts TypeScript signature theme={"dark"}
    read(
      path: string,
      options?: { range?: TrialFileRange }
    ): Promise<Buffer>;
    ```

    ```python Python signature theme={"dark"}
    async def read(
        path: str,
        *,
        start: Optional[int] = None,
        end: Optional[int] = None,
        suffix: Optional[int] = None,
    ) -> bytes: ...
    ```
  </CodeGroup>
</Accordion>

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const bytes = await files.read("/instruction.md", {
    range: {
      start: 0,
      end: 1023
    }
  });
  ```

  ```python Python theme={"dark"}
  data = await files.read(
      '/instruction.md',
      start=0,
      end=1023,
  )
  ```
</CodeGroup>

The same inclusive byte-range forms as `RunFilesystem.read` apply. This interface has no search, archive, watch, event, log, or process methods.