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

# Files

> sandbox.files - read and write files inside a sandbox's filesystem.

Read and write files in a sandbox's filesystem with `sandbox.files`.

## `write`

Write a file at an absolute path. Parent directories are created automatically.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  // String content
  await sandbox.files.write("/app/config.json", '{"key": "value"}')

  // Binary content
  await sandbox.files.write("/app/image.png", buffer)

  // From Uint8Array
  await sandbox.files.write("/app/data.bin", new Uint8Array([1, 2, 3]))
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  # String content (UTF-8 encoded)
  sandbox.files.write("/app/config.json", '{"key": "value"}')

  # Binary content
  with open("local-image.png", "rb") as f:
      sandbox.files.write("/app/image.png", f.read())
  ```
</CodeGroup>

**Parameters:**

| Option                  | Type                         | Description                              |
| ----------------------- | ---------------------------- | ---------------------------------------- |
| `path`                  | `string` / `str`             | Absolute destination path.               |
| `content`               | `FileInput` / `str \| bytes` | File contents. See accepted types below. |
| `timeoutMs` / `timeout` | `number` / `float`           | Optional request timeout.                |
| `signal`                | `AbortSignal`                | TypeScript only - abort the request.     |

**Accepted content types:**

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  type FileInput = string | Uint8Array | ArrayBuffer | Blob
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  # str  - encoded as UTF-8
  # bytes - written as-is
  ```
</CodeGroup>

**Cancellation (TypeScript):**

```typescript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
const controller = new AbortController()
setTimeout(() => controller.abort(), 5000)

await sandbox.files.write("/app/large.bin", buffer, {
  signal: controller.signal,
})
```

## `read`

Read a file as raw bytes.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  const bytes: Uint8Array = await sandbox.files.read("/app/image.png")
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  data: bytes = sandbox.files.read("/app/image.png")
  ```
</CodeGroup>

## `readText` / `read_text`

Read a file and decode as UTF-8.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  const text: string = await sandbox.files.readText("/app/config.json")
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  text: str = sandbox.files.read_text("/app/config.json")
  ```
</CodeGroup>

## `downloadDir` / `download_dir`

Download a directory as a ZIP archive. Returns the raw zip bytes — entries are
prefixed with the directory's base name (e.g. `output/log.txt`), and symlinks
are skipped.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  import { writeFileSync } from "node:fs"

  const zip: Uint8Array = await sandbox.files.downloadDir("/app/output")
  writeFileSync("output.zip", zip)
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  zip_bytes: bytes = sandbox.files.download_dir("/app/output")
  with open("output.zip", "wb") as f:
      f.write(zip_bytes)
  ```
</CodeGroup>

**Parameters:**

| Option                  | Type               | Description                                                             |
| ----------------------- | ------------------ | ----------------------------------------------------------------------- |
| `path`                  | `string` / `str`   | Absolute directory path to archive.                                     |
| `timeoutMs` / `timeout` | `number` / `float` | Optional request timeout. Large directories can exceed the 30s default. |
| `signal`                | `AbortSignal`      | TypeScript only - abort the request.                                    |

The server decides file-vs-directory: if `path` points at a regular file, its
bytes are streamed back as-is (not zipped) — use `read` for files.

## Round-trip example

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  const original = "hello, world!\n"

  await sandbox.files.write("/tmp/greeting.txt", original)
  const roundTripped = await sandbox.files.readText("/tmp/greeting.txt")

  console.log(roundTripped === original)  // true
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  original = "hello, world!\n"

  sandbox.files.write("/tmp/greeting.txt", original)
  round_tripped = sandbox.files.read_text("/tmp/greeting.txt")

  print(round_tripped == original)  # True
  ```
</CodeGroup>

## Path rules

* Paths **must** start with `/`
* Paths **must not** contain `..` segments
* Parent directories are created automatically on `write`

## Errors

Commonly raised:

* `NotFoundError` - file or directory does not exist (on read / downloadDir)
* `ValidationError` - invalid path (relative, contains `..`, or malformed)
* `AuthenticationError` - access token invalid or sandbox was deleted
* `TimeoutError` / `SandboxTimeoutError` - the optional timeout elapsed

See [Errors](/errors) for the full hierarchy.