Read and write files

Last updated 3 November 2026

Read, write, list, move and delete files inside a Machine over HTTPS, and know from each answer whether what you wrote lasts past the next sleep.

What lasts

Every wake starts the Machine fresh from its image, with its database and its Volume as they were. A file under the Volume’s path lasts; any other file is gone at the next sleep, and a call that wakes the Machine finds only the image and the Volume. Every write, stat and move answers durability: volumes for a file that lasts, machines for one that is gone at the next sleep (see Data guarantees). What must last belongs in the database or on the Volume.

Read, write, list and delete

# Write a file, creating its directory
curl -sS -X PUT "https://api.us-east-1.tonbo.sh/v1/machines/hello/files/content?path=/data/report.json&parents=true" \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  --data-binary @report.json

# Read it back
curl -sS "https://api.us-east-1.tonbo.sh/v1/machines/hello/files/content?path=/data/report.json" \
  -H "Authorization: Bearer $TONBO_API_KEY"

# Its size, mode, time and ETag
curl -sS "https://api.us-east-1.tonbo.sh/v1/machines/hello/files/stat?path=/data/report.json" \
  -H "Authorization: Bearer $TONBO_API_KEY"

# One directory, a page at a time
curl -sS "https://api.us-east-1.tonbo.sh/v1/machines/hello/files/list?path=/data" \
  -H "Authorization: Bearer $TONBO_API_KEY"

# Delete it; missing_ok answers 204 when it is already gone
curl -sS -X DELETE "https://api.us-east-1.tonbo.sh/v1/machines/hello/files/content?path=/data/report.json&missing_ok=true" \
  -H "Authorization: Bearer $TONBO_API_KEY"

• Every call names an absolute path, without . or .. parts or a trailing slash, and may name a user to act as; the image’s user otherwise.
• A read streams one regular file; one Range answers 206, and a file of at most 64 MiB carries an ETag, the SHA-256 of its bytes.
• A write replaces the file in one step, up to 1 GiB, with Content-Length: a reader sees the old file or the new one, never a mix. If-Match with an ETag writes only over that version, and If-None-Match: * only where no file is; mode sets a new file’s permissions, 0644 by default.
• A list reads one directory, sorted by name, at most 10,000 entries a page, and answers next_cursor for the next.
• A delete removes a file, a symbolic link (never its target) or an empty directory, and a full one with recursive=true; it never crosses into another file system.

Directories, moves and archives

• PUT …/files/directory?path=/data/out&parents=true creates a directory, and answers 200 when it is already there.
• POST …/files/rename with {"from": …, "to": …} moves a path in one atomic step, and refuses an existing target unless overwrite is true. Write to a temporary name, then move it into place, and a reader never sees half a file. A move from the Machine’s disk onto the Volume answers 409 cross_device and moves nothing; copy it with a command instead.
• GET …/files/archive?path=/data&format=tar.gz downloads a directory as one archive.

Rules every call follows

• Every file call wakes an asleep Machine, and keeps it awake while it runs. Send Tonbo-Wake: never to only act on an awake one.
• Tonbo-Expect-Activation, from an earlier answer’s Tonbo-Activation, keeps a sequence of calls on one boot: a write never lands on the fresh disks of the next.
• A Machine runs at most 16 file calls at once (429 file_limit). Writes, deletes, moves and new directories take an Idempotency-Key.
• Changing Tonbo’s own paths, such as /tonbo where its tools are, answers 403 platform_path; reading them is allowed. A file the user may not change answers 403 permission_denied.
• Within one boot, a change that answered 2xx is visible to every later call. To change many files at once, run a command (see Run commands).