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

# Keep a Machine’s whole disk

Last updated 16 November 2026

Make a Volume the Machine’s whole disk, and everything the Machine changes on it lasts: the packages you install, files in `/etc`, `/usr` or `/opt`, and your work in `/home`, `/workspace` and `/root` are there after every sleep and wake, and when the Machine moves to another host. Your image stays as it was; the Volume keeps what you changed.

A Volume can instead be mounted at one path, where only the files under that path last (see [Files on its Volume](https://tonbo.dev/docs/machines/database.md#volume)). A whole disk is for a Machine you work in, such as an agent’s computer, that you set up once and keep.

## 1. Create a Machine on its own disk {#create}

Create a Volume in the Machine’s region, then create the Machine with the Volume named and no path: `--volume dev-disk`, or in the API a binding with no `path`. The Machine boots from your image with the Volume as its disk.

**CLI**

```shell
tonbo volume create dev-disk --size 10 --region ap-southeast-1
tonbo machine create dev --image node:22 --shape s-1 --volume dev-disk --region ap-southeast-1 --wait -- sleep infinity
```

**API**

```shell
VOLUME=$(curl -sS https://api.tonbo.dev/v1/volumes \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"dev-disk","region":"ap-southeast-1","size_gib":10}' | jq -r .data.id)
jq -n --arg volume "$VOLUME" \
  '{"name":"dev","image":"node:22","shape":"s-1","region":"ap-southeast-1","command":["sleep","infinity"]} + {volumes: [{volume: $volume}]}' \
  | curl -sS -i https://api.tonbo.dev/v1/machines \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @-
```

`dev` runs `node:22` with no port, kept running so you can run commands in it (see [Run commands](https://tonbo.dev/docs/machines/exec.md)). A Volume already mounted at a path on a Machine can become its whole disk too (see [Turn a mounted Volume into the whole disk](#from-a-path)).

## 2. Install something and keep it {#install}

Install a package as you would on any Debian machine, put the Machine to sleep, and run it again: the package is still there at the next wake.

**CLI**

```shell
tonbo machine exec dev -- sh -c 'apt-get update && apt-get install -y ripgrep'
tonbo machine sleep dev --wait
tonbo machine exec dev -- rg --version
```

**API**

```shell
curl -sS https://api.ap-southeast-1.tonbo.sh/v1/machines/dev/exec \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"command":["sh","-c","apt-get update && apt-get install -y ripgrep"]}' | jq '.data | {exit_code, stdout: .stdout.head}'
curl -sS -X POST https://api.tonbo.dev/v1/machines/dev/sleep -H "Authorization: Bearer $TONBO_API_KEY"
until curl -sS https://api.tonbo.dev/v1/machines/dev -H "Authorization: Bearer $TONBO_API_KEY" \
  | jq -e '.data.status.power == "asleep"' >/dev/null; do sleep 5; done
curl -sS https://api.ap-southeast-1.tonbo.sh/v1/machines/dev/exec \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"command":["rg","--version"]}' | jq '.data | {exit_code, stdout: .stdout.head}'
```

Installs on a whole disk are written safely, so a crash in the middle of one leaves no empty files behind (see [Package installs on a whole disk](https://tonbo.dev/docs/machines/manage.md#whole-disk-installs)).

## 3. Know what lasts {#what-lasts}

Every file you change on the disk lasts, except under `/tmp`, `/var/tmp`, `/var/cache`, `~/.cache`, `/var/lib/tonbo` and `/var/lib/sqlite-ursula`. Those stay on the Machine’s scratch disk and are empty at every wake, because they hold caches and temporary files that would only fill the Volume: apt’s downloaded packages, pip’s and the build tools’ caches, and Tonbo’s own working state. `~/.cache` is that of root and of the image’s user. `/run` and `/scratch` are emptied too, and memory and running programs are gone after a sleep, so your program starts again at each wake.

Caches inside your home directories, such as npm’s `~/.npm` or Cargo’s registry, last with the rest of `/home` and `/root`.

## 4. Change the image with a Rebuild {#rebuild}

The disk’s changes are made on top of one image, so a Machine whose Volume is its whole disk keeps its image. To move it to another image, or to a newer build of its tag, rebuild it:

**CLI**

```shell
tonbo machine rebuild dev --image node:24
```

**API**

```shell
curl -sS -i -X POST https://api.tonbo.dev/v1/machines/dev/rebuild \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"node:24"}'
```

A Rebuild keeps `/home`, `/workspace` and `/root` and deletes every other change on the disk. It never happens by itself. Before it acts, the CLI shows this warning and asks you to type the Machine’s name (`--yes` skips the question, and is required without a terminal):

> **Rebuild deletes changes outside /home, /workspace and /root.** Rebuild moves this Machine to the image `node:24`. Files in /home, /workspace and /root are kept. Everything else you changed on this Machine's disk is deleted and cannot be recovered: installed packages, files you edited in /etc, global npm or pip packages, and anything in /usr, /opt or /var. To keep those changes, add them to the image's Dockerfile. The Machine sleeps now and starts on the new image at its next wake.

An asleep Machine answers at once and moves to the new image at its next wake. An awake one is put to sleep first, and the CLI waits for that and sends the Rebuild again; in the API the answer is `202` with Retry-After, and you send the same request again once the Machine is asleep. A Machine whose disk was never used changes its image with no Rebuild.

A plain image change, as in [Deploy a change](https://tonbo.dev/docs/machines/deploy.md#when), is refused on a whole disk with [rebuild_required](https://tonbo.dev/docs/machines/troubleshooting/manage.md#rebuild_required) and changes nothing. At a terminal the CLI then shows the warning and offers the Rebuild; to send the change as a Rebuild at once, add `--rebuild`:

**CLI**

```shell
tonbo machine update dev --image node:24 --rebuild
```

**API**

```shell
ETAG=$(curl -sS -o /dev/null -D - https://api.tonbo.dev/v1/machines/dev -H "Authorization: Bearer $TONBO_API_KEY" \
  | awk 'tolower($1) == "etag:" {sub(/\r$/, "", $2); print $2}')
jq -n '{"image":"node:24","rebuild":true}' \
  | curl -sS -X PATCH https://api.tonbo.dev/v1/machines/dev \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/json" \
  -d @-
```

To keep packages across a Rebuild, add them to the image’s Dockerfile.

## 5. Turn a mounted Volume into the whole disk {#from-a-path}

A Volume mounted at a path becomes the Machine’s whole disk when you bind it again with no path. Here `app` has the Volume `data` at a path:

**CLI**

```shell
tonbo machine update app --volume data
```

**API**

```shell
VOLUME=$(curl -sS https://api.tonbo.dev/v1/volumes/data -H "Authorization: Bearer $TONBO_API_KEY" | jq -r .data.id)
ETAG=$(curl -sS -o /dev/null -D - https://api.tonbo.dev/v1/machines/app -H "Authorization: Bearer $TONBO_API_KEY" \
  | awk 'tolower($1) == "etag:" {sub(/\r$/, "", $2); print $2}')
jq -n --arg volume "$VOLUME" '{volumes: [{volume: $volume}]}' \
  | curl -sS -X PATCH https://api.tonbo.dev/v1/machines/app \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/json" \
  -d @-
```

The change applies at the Machine’s next wake, and the Volume’s files are then under `/workspace`. This works on the Machine that has the Volume, or with a Volume no Machine has. It goes one way: a whole disk is never mounted at a path again.

## 6. Delete the Machine, with or without its disk {#delete}

Deleting the Machine deletes its Volume too when the Volume was made for it, as the console makes the disk of a new Machine, and keeps it otherwise, as for a Volume you created with `tonbo volume create`. Say which you want to be sure:

**CLI**

```shell
tonbo machine delete dev
tonbo machine delete dev --delete-volume
tonbo machine delete dev --keep-volume
```

**API**

```shell
curl -sS -X DELETE https://api.tonbo.dev/v1/machines/dev -H "Authorization: Bearer $TONBO_API_KEY"
curl -sS -X DELETE "https://api.tonbo.dev/v1/machines/dev?delete_volume=true" -H "Authorization: Bearer $TONBO_API_KEY"
curl -sS -X DELETE "https://api.tonbo.dev/v1/machines/dev?delete_volume=false" -H "Authorization: Bearer $TONBO_API_KEY"
```

The CLI then says whether the Volume was deleted. A kept Volume is billed until you delete it, and can be the whole disk of another Machine on the same image (see [Move a Volume](https://tonbo.dev/docs/machines/manage.md#move-a-volume)).

## Answers you may get {#answers}

| Answer | Why | What to do |
| --- | --- | --- |
| `422 root_mode_not_offered` | The request bound a Volume with no path, which makes it the Machine’s whole disk, and the Machine’s region does not offer that. | Give the Volume a path to mount it there, such as data:/data, or leave the Volume out. |
| `409 rebuild_required` | The Machine’s Volume is its whole disk, so its image changes only by Rebuild, which keeps /home, /workspace and /root and deletes every other change on the disk. | `tonbo machine rebuild <name> --image <ref>` (`POST /v1/machines/<name>/rebuild`, or the update again with `rebuild: true`), or keep the image. |
| `409 volume_not_whole_disk` | Rebuild is for a Machine whose Volume is its whole disk; this Machine’s Volume is mounted at a path, or it has none. | `tonbo machine update <name> --image <ref>` (`PATCH /v1/machines/<name>` with `image`). |
| `409 volume_mode_change` | The request gave the Machine’s whole disk a path, or moved a Volume between being a whole disk and being mounted at a path. A whole disk is never mounted at a path; a Volume mounted at a path becomes a whole disk only on its own Machine, or unbound, with its files under /workspace. | Send the binding as it is now, or bind a new Volume in the mode you want. |
| `409 volume_image_mismatch` | The Volume is a Machine’s whole disk, made against one image digest (volume_digest), and the Machine it was moving to runs another (machine_digest). | Move it to a Machine on the same image, or create one with that image. |
| `409 volume_rebuild_pending` | The Volume is a whole disk with a Rebuild that its Machine applies at its next wake. | `tonbo machine wake <machine>` (`POST /v1/machines/<machine>/wake`) once, then move it. |

## Limits {#limits}

A whole disk is offered in `ap-southeast-1` and `us-east-1` (see [Regions](https://tonbo.dev/docs/platform/regions.md)); elsewhere a binding with no path answers [root_mode_not_offered](https://tonbo.dev/docs/machines/troubleshooting/manage.md#root_mode_not_offered), and a Volume mounted at a path works as before.

- What you change counts against the Volume’s size, 1 to 100 GiB, fixed when you create it; your image does not (see [Things to know](https://tonbo.dev/docs/machines/volumes/things-to-know.md#size)). A Machine has at most 1 Volume.
- The Volume is billed for the bytes it holds, as any Volume (see [Pricing](https://tonbo.dev/docs/machines/pricing.md#volume)). A command that rewrites the whole image, such as `chown -R` over `/usr`, copies it onto the Volume.
- A whole disk moves only to a Machine on the same image, and only once a Rebuild it waits for has been applied.
- It is kept as any Volume is (see [How Volumes work](https://tonbo.dev/docs/machines/volumes/how-it-works.md)).
- In the first measurement, on 15 November 2026 with shape m-4, a Machine whose Volume is its whole disk woke in about the same time as the same Machine with its Volume at a path for a web server and a Node.js dev server, and up to about 1.3 s later for a large Python notebook server.
- In our test on 15 November 2026 (m-4, one run each), after the Machine's host was replaced, the first response came back in about 5.5 s for a small web server and 17–19 s for a large Python notebook server, with the Volume as the whole disk or at a path alike.

Packages every Machine needs, installed the same way each time, belong in your image (see [Run your own image](https://tonbo.dev/docs/machines/images.md)).

## Next steps {#next}

- [Things to know](https://tonbo.dev/docs/machines/volumes/things-to-know.md): what a Volume costs, moving and deleting one, and what it does not do.
- [Manage Volumes](https://tonbo.dev/docs/machines/manage.md#volumes): list, move and watch them.
- [Troubleshooting: managing Machines](https://tonbo.dev/docs/machines/troubleshooting/manage.md): every refusal a create, change or delete can get.
- [Troubleshooting: Volumes](https://tonbo.dev/docs/machines/volumes/troubleshooting.md): what you may see while a Volume is in use.
