> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# Read and write files

Last updated 3 November 2026

> Machines are not open yet. These pages describe Machines as they will open; until then, a create answers [`region_not_offered`](https://tonbo.dev/docs/machines/troubleshooting/manage.md#region_not_offered) (422), “Machines are not offered in any region yet.”

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.

> Planned Not served yet. This page describes how it will work, as decided; until it is served, every request below answers 404 at `https://api.us-east-1.tonbo.sh/v1`. The [Machines API reference](https://tonbo.dev/docs/reference/management/machines.md) lists each operation, marked Planned.

## 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](https://tonbo.dev/docs/machines/guarantees/data.md)). What must last belongs in the [database or on the Volume](https://tonbo.dev/docs/machines/database.md).

## Read, write, list and delete

```shell
# 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](https://tonbo.dev/docs/machines/exec.md)).