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

# Filesystem

> Read, write, list, and manage files on the sandbox disk through five governed operations.

The agent reaches the [computer](https://vetta.sh/docs/computer/index.md)'s disk through five file operations. They are deliberately small and explicit — there is no separate upload/download channel and no hidden sync. Scratch work lives here; anything the agent should hand back is promoted to [Files](https://vetta.sh/docs/capabilities/files.md) with `publish_file`.

> [!NOTE]
>
> **This page is the canonical sandbox file API.** The `fs/*` routes below (`fs/write`, `fs/read`, `fs/list`, `fs/mkdir`, `fs/remove`) are the single source of truth for reading and writing a computer's disk. Sandbox scratch files are distinct from persistent, org-scoped [Files](https://vetta.sh/docs/capabilities/files.md) — the latter are what an agent publishes to keep beyond a run.

> [!NOTE]
>
> File operations on a **sleeping** computer wake it automatically. On a **parked** computer they are **rejected** — resume it first. See [lifecycle](https://vetta.sh/docs/computer/sandbox.md#lifecycle).

> [!WARNING]
>
> **These five operations are confined to the computer's home directory** — the `home` reported by [inspect](https://vetta.sh/docs/api/computers.md#inspect), which the examples below write as `/home/user`. Read that value rather than assuming a path. Anything outside it (`/`, `/etc`, `/var`) is refused by the machine; use the [shell](https://vetta.sh/docs/computer/shell.md) to reach the rest of the disk.

## Binary files

There is no dedicated upload or download operation. To move binary data in or out of the sandbox, use `write` / `read` with `encoding: "base64"`.

```bash CLI theme={"system"}
# write a text file, then read it back
vetta computer fs write box /home/user/notes.txt --content "hello"
vetta computer fs read box /home/user/notes.txt

# write binary via base64
vetta computer fs write box /home/user/logo.png \
  --encoding base64 --content "$(base64 -i ./logo.png)"
```

```typescript TypeScript theme={"system"}
// One method, one operation per call: `read`, `write`, `list`, `mkdir`, `remove`.
await vetta.computers.fs(computer.id, "write", {
  path: "/home/user/notes.txt",
  content: "hello",
});

const { content } = await vetta.computers.fs(computer.id, "read", {
  path: "/home/user/notes.txt",
});

// binary round-trip
await vetta.computers.fs(computer.id, "write", {
  path: "/home/user/logo.png",
  encoding: "base64",
  content: pngBuffer.toString("base64"),
});
```

```bash cURL theme={"system"}
curl https://api.vetta.sh/v1/computers/$COMPUTER_ID/fs/write \
  -H "Authorization: Bearer $VETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "path": "/home/user/notes.txt", "content": "hello", "encoding": "utf-8" }'
```

## Working directory

The filesystem operations take **absolute paths** — they do not carry a working directory. The current directory is a per-exec concern: pass `cwd` to the [`bash` tool](https://vetta.sh/docs/computer/shell) to control where a command runs. Nothing about `cwd` persists between calls.

## Limits at a glance

| Operation | Limit |
| - | - |
| `write` | 4 MiB per call |
| `read` | 4 MiB per call |
| `list` | Immediate children only (incl. hidden) |
| `remove` | Refuses `/`; recursive otherwise |

## Operations

> [tab] write
>
> Write bytes to a path, creating or overwriting the file.
>
> **path** `string` *required*
>
> Absolute path of the file to write.
>
> **content** `string` *required*
>
> The file contents. Interpreted according to `encoding`.
>
> **encoding** `string` (default: utf-8)
>
> `utf-8` for text, or `base64` for binary payloads.
>
> > [!WARNING]
> >
> > Maximum **4 MiB** per file per write. Split larger payloads across multiple writes or generate them in-sandbox with the [shell](https://vetta.sh/docs/computer/shell.md).

> [tab] read
>
> Read a file back.
>
> **path** `string` *required*
>
> Absolute path of the file to read.
>
> **encoding** `string` (default: utf-8)
>
> `utf-8` or `base64`. Use `base64` to pull binary content back out.
>
> **content** `string`
>
> The file contents in the requested encoding.
>
> > [!WARNING]
> >
> > Reads are capped at **4 MiB** per call; a larger file is refused before any of it is transferred. Chunk it in-sandbox (`split -b`), or have the agent move it with [`publish_file`](https://vetta.sh/docs/capabilities/files), which takes files up to 5 GiB.

> [tab] list
>
> List the **immediate children** of a directory, including hidden entries (dotfiles). Not recursive.
>
> **path** `string` *required*
>
> Absolute path of the directory to list.
>
> **entries** `object[]`
>
> One entry per child with its name and type (file or directory).

> [tab] mkdir
>
> Create a directory, including any missing parents (`mkdir -p`).
>
> **path** `string` *required*
>
> Absolute path of the directory to create.

> [tab] remove
>
> Remove a file or directory recursively (`rm -rf`).
>
> **path** `string` *required*
>
> Absolute path to remove.
>
> > [!WARNING]
> >
> > `remove`**refuses `/`** outright. It is otherwise recursive and irreversible — there is no trash.

> [card] [Next: shell](https://vetta.sh/docs/computer/shell.md)
>
> Run commands with the `bash` tool and read the buffered output.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.