Filesystem

The agent reaches the computer’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 with publish_file.

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 — the latter are what an agent publishes to keep beyond a run.

File operations on a sleeping computer wake it automatically. On a parked computer they are rejected — resume it first. See lifecycle.

These five operations are confined to the computer’s home directory — the home reported by 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 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".

# 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)"

// 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"),
});

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 to control where a command runs. Nothing about cwd persists between calls.

Limits at a glance

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

Operations

write
read
list
mkdir
remove

Write bytes to a path, creating or overwriting the file.

string

required

Absolute path of the file to write.

string

required

The file contents. Interpreted according to encoding.

string

default:"utf-8"

utf-8 for text, or base64 for binary payloads.

Maximum 4 MiB per file per write. Split larger payloads across multiple writes or generate them in-sandbox with the shell.

Read a file back.

string

required

Absolute path of the file to read.

string

default:"utf-8"

utf-8 or base64. Use base64 to pull binary content back out.

string

The file contents in the requested encoding.

Reads are capped at 4 MiB. Larger files must be chunked or processed in-sandbox.

Create a directory, including any missing parents (mkdir -p).

string

required

Absolute path of the directory to create.

Remove a file or directory recursively (rm -rf).

string

required

Absolute path to remove.

remove refuses / outright. It is otherwise recursive and irreversible — there is no trash.

Next: shell

Run commands with the bash tool and read the buffered output.

Agent

Running an agent

Agent capabilities

Computer

Identity

Team

Binary files

Working directory

Limits at a glance

Operations

Next: shell

​Binary files

​Working directory

​Limits at a glance

​Operations

Next: shell

Binary files

Working directory

Limits at a glance

Operations