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.

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 /workspace/notes.txt --content "hello"
vetta computer fs read box /workspace/notes.txt

# write binary via base64
vetta computer fs write box /workspace/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: "/workspace/notes.txt",
  content: "hello",
});

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

// binary round-trip
await vetta.computers.fs(computer.id, "write", {
  path: "/workspace/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": "/workspace/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