# Files

> Upload, download, list, and delete files inside a sandbox filesystem over the API.

Read and write files inside a sandbox's filesystem. Paths are container-local (e.g.
`/workspace/main.py`). File content is base64-encoded in transit. Total `/workspace` size is
capped by your [plan](./plans-and-limits.md).

## Upload / write a file

```http
POST /v1/sandboxes/{sandbox_id}/files
```

```json
{ "path": "/workspace/main.py", "content_base64": "cHJpbnQoIkhlbGxvIik=" }
```

Returns `201` with `{ "path": "...", "status": "written" }`.

## Download a file

```http
GET /v1/sandboxes/{sandbox_id}/files?path=/workspace/main.py
```

Returns `{ "path": "...", "content_base64": "..." }`. Missing files return `404`
(`file_not_found`).

## List a directory

```http
GET /v1/sandboxes/{sandbox_id}/files/list?path=/workspace
```

Returns entries with `name`, `type` (`file` or `dir`), and `size_bytes`.

## Delete a file or directory

```http
DELETE /v1/sandboxes/{sandbox_id}/files?path=/workspace/main.py
```

## Notes

- File operations on a **stopped** sandbox auto-resume it first (restoring persisted files).
- base64-over-JSON is convenient but not ideal for very large files; keep uploads modest.
- The dashboard's **Files** panel is an expandable tree: click a folder to drill in, click a
  file to view its contents inline (text) or download it, with per-file download/delete.
- The SDKs add higher-level helpers (`upload`, `download`, `read_text`, `list_files`, `mkdir`,
  `move`, `exists`, `find`). See [Python](./sdk.md#files) and [JavaScript](./sdk-js.md).