#File (FS)

The File plane reads, writes, edits, searches, transfers, and watches files. It shares one filesystem with commands, terminals, code execution, and browser downloads: a file written through this API is immediately visible to a shell command, and vice versa.

The working directory is not a confinement boundary — file calls reach anywhere the daemon's own account can. Confinement is the sandbox's job, not this API's.

On the file API, user means something different from its meaning on commands and terminals:

On the file API, user only decides who owns new files and directories; on commands and terminals, it decides which account runs the process.

The file API still reads and writes with the daemon's own privileges. GET /v1/capabilities reports the file capabilities under files, one flag per operation. The v1 and v2 routes side by side are in Migration from 1.x.

#Read and write files

curl "$BASE_URL/v2/fs/read?path=/tmp/demo/src/app.py&start_line=2&end_line=5"

curl -X POST "$BASE_URL/v2/fs/write" \
  -H "Content-Type: application/json" \
  -d '{"path": "/tmp/demo/README.md", "content": "# demo\n"}'

{
  "path": "/tmp/demo/README.md",
  "content": "# demo\n"
}

curl -X POST "$BASE_URL/v1/file/read" \
  -H "Content-Type: application/json" \
  -d '{"file": "/tmp/demo/src/app.py", "start_line": 2, "end_line": 5}'

curl -X POST "$BASE_URL/v1/file/write" \
  -H "Content-Type: application/json" \
  -d '{"file": "/tmp/demo/README.md", "content": "# demo\n"}'

{
  "file": "/tmp/demo/README.md",
  "content": "# demo\n"
}

The write body takes these fields:

• A write creates the missing parent directories on the way, and answers file and bytes_written.
• base64 decodes content to bytes; raw writes each character as one byte. leading_newline and trailing_newline apply to utf-8 only.
• Reading is buffered and text-only: a directory answers EISDIR, a non-UTF-8 file decode_error, and a file over 16 MiB file exceeds the 16 MiB buffered text limit. Download streams instead, at any size.

#Files and directories

The editor tool applies an anchored substitution, so an edit needs neither the whole file nor a line number. It takes command, path, old_str, new_str, insert_line for insert, and replace_mode (ALL, FIRST, LAST):

• old_str is matched verbatim, so whitespace and line endings have to agree. An anchor that is absent answers 400 old_str not found in file; an anchor that matches twice answers 400 old_str has multiple occurrences; replace_mode is required rather than picking one.
• data carries output (the cat -n snippet the tool shows a model), old_content and new_content (the whole file before and after), and prev_exist. undo_edit restores the content the last edit replaced.

Listing and stat return these fields:

• Each files entry from list carries name, path, is_directory, size, extension, and modified_time.
• The list envelope carries total_count, file_count, directory_count, and truncated. Results are cut off at 10,000 entries, with truncated set to true.
• is_hidden appears only when it is true; show_hidden is on by default. permissions appears only when requested.
• stat answers path, size, permissions, is_directory, is_symlink, and modified_time.

Symlinks are classified by what they point at: a link to a directory counts as a directory, and a recursive listing lists the link without descending through it. follow_symlinks: false makes stat describe the link itself. Windows attributes and permissions are in Windows.

copy and move refuse an existing destination with already_exists unless overwrite is set, so a rename can never silently clobber. recursive is what lets delete remove a non-empty directory.

#Search

Finding a file by name and searching inside files are two different routes.

curl -X POST "$BASE_URL/v2/fs/grep" \
  -H "Content-Type: application/json" \
  -d '{"path": "/tmp/demo", "pattern": "argv", "recursive": true}'

curl -X POST "$BASE_URL/v1/file/grep" \
  -H "Content-Type: application/json" \
  -d '{"path": "/tmp/demo", "pattern": "argv", "recursive": true}'

The grep body is the same in v1 and v2:

{
  "path": "/tmp/demo",
  "pattern": "argv",
  "recursive": true
}

grep narrows what it reads with include and exclude globs, type, and max_file_size, and shapes the answer with case_insensitive, multiline, context_before and context_after, max_results, and offset. A match carries file, line_number counted from 1, line_content, and the context lines when they were asked for.

Every walk is bounded and says so through truncated: grep reads at most 500 matches and skips files over 1 MiB, a metadata glob stops at 5,000 entries, and a name search stops at 10,000. Raise max_results where the route takes it, or narrow the root.

#Transfer

• An upload spools to disk instead of buffering in memory, so file size is bounded by disk, not RAM. It lands in a .aiod-upload-<id>.part file next to the target and is renamed over it.
• A download streams the bytes with Accept-Ranges, ETag, and Last-Modified, honours a Range header with a 206, and answers a missing path with 404.
• A download otherwise returns whatever the kernel reads while it streams; change_policy=abort pins the file's state at open instead, answers 409 when it had already changed, and cuts a transfer that changes under it.

When a whole directory has to move as one tar stream, switch to v2: GET /v2/fs/tree

#Watch a directory

Use watch to learn that a file changed. Do not poll for it. Treat events as invalidation signals, not content: reload a clean copy, or flag a conflict when unsaved edits exist. Anything that touches the tree is reported — a command, another API call, a build:

from agent_sandbox import Sandbox

client = Sandbox(base_url="http://127.0.0.1:18091")
watcher = client.file.watch_create(
    path="/tmp/demo", recursive=True, debounce=200
)["data"]["watcher_id"]

client.bash.exec(command="echo 'X = 1' > /tmp/demo/util.py")
polled = client.file.watch_poll(watcher, cursor=0, timeout=10)["data"]
for event in polled["events"]:
    print(event["seq"], event["type"], event["relative_path"])
# 1 create util.py
# 2 write util.py
print(polled["cursor"], polled["overflow"])
# 2 False
client.file.watch_stop(watcher)

import { SandboxClient } from "@agent-infra/sandbox";

const client = new SandboxClient({ environment: "http://127.0.0.1:18091" });
const created = (await client.file.watchCreate({
  path: "/tmp/demo",
  recursive: true,
  debounce: 200,
} as any)) as any;
const watcher = created.body.data.watcher_id;

await client.bash.exec({ command: "echo 'X = 1' > /tmp/demo/util.py" });
const polled = (await client.file.watchPoll(watcher, {
  cursor: 0,
  timeout: 10,
} as any)) as any;
for (const event of polled.body.data.events) {
  console.log(event.seq, event.type, event.relative_path);
}
// 1 create util.py
// 2 write util.py
console.log(polled.body.data.cursor, polled.body.data.overflow);
// 2 false
await client.file.watchStop(watcher);

The knobs and their bounds:

Every event carries these fields:

• Basic information: seq and type (create, write, remove, rename, or chmod).
• Paths: path and relative_path.
• File attributes: is_dir, timestamp, mtime, size, and inode.
• A rename event also carries the old path as old_path.

cursor is the position the client has consumed. Pass the response's cursor straight into the next poll. If the buffer drops events before you read them, the response includes overflow: true. cursor: 0 replays buffered history; the initial_cursor returned when the watcher is created means "from now on."

Filtering and writes work as follows:

• exclude defaults to .git, node_modules, __pycache__, .venv, .DS_Store, and the usual byte-code and editor leftovers. Passing exclude replaces that list; it does not extend it.
• Do not exclude *.part: an upload reports three events on its temporary name before the rename on the target.
• A write that names an owner stages through .aiod-write-<id>.part before reaching the target. A plain write keeps the destination's inode and creates no temporary file.

Creating a watcher twice with the same configuration reuses the existing watcher. The second create answers reused: true with the current initial_cursor, and each DELETE releases one subscriber. Up to 128 watchers can run at once, each holding the last 10,000 events; past that, a create answers 429. A browser UI that would rather receive pushed events than poll can request the event stream with Accept: text/event-stream.

#Ownership identity

user only decides who owns the files and directories created by the call. The file API always reads and writes with the daemon account's privileges.

{
  "path": "/tmp/report.txt",
  "content": "report\n"
}

Other rules:

• Omit user to use the default owner. With AIO_DEFAULT_USER unset, that is the daemon's own account.
• A missing account answers 400 no such user: alice. A non-root daemon cannot switch owners and answers 400 cannot run as alice: aiod is running as uid 501 and only root can change identity; it never writes silently under the wrong owner.
• Linux only. Here user is an ownership identity; commands and terminals use user as an execution identity instead. See Commands (Bash).

#Patterns for an agent

Most file work is a short sequence: locate, read the part that matters, edit in place, and let another plane run the result. Writing a file and then running a command over it is two calls, because both planes see the same disk.

File Operations runs the whole story: scaffold a project, find the TODO, edit it, watch the directory while a command changes it, then transfer the result.

#Error handling

An expected filesystem failure returns the same structured data on both sides. What differs is the status the call is wrapped in.

data describes the failure:

• errno, errno_name — the OS error number and its symbolic name, such as ENOENT
• error_type — the kind of failure: not_found, permission_denied, already_exists, …
• exception_type — the matching exception class name, such as FileNotFoundError
• message, operation, path — the OS message, the operation that failed, and the path involved
• retryable — whether a retry can succeed

download is the exception on both sides: it streams bytes on success and answers 404 for a missing path. Watch routes keep the envelope but use the status for lifecycle failures: 404 for an unknown watcher, 400 for a debounce or limit outside its bounds, 429 at the watcher limit, 503 for a wait that timed out.

#Related

• Error Handling — the envelope, the status conventions, and the other planes
• Commands (Bash) — the plane that sees the files this one writes
• File Operations — the whole surface in one runnable example