PricingConsole

Keep a Machine’s whole disk

Last updated 16 November 2026

View .md

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). 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 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.

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

dev runs node:22 with no port, kept running so you can run commands in it (see Run commands). 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).

2. Install something and keep it

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.

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

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).

3. Know 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

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:

tonbo machine rebuild dev --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, is refused on a whole disk with 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:

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

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

5. Turn a mounted Volume into the whole disk

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:

tonbo machine update app --volume data

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

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:

tonbo machine delete dev
tonbo machine delete dev --delete-volume
tonbo machine delete dev --keep-volume

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).

Answers you may get

AnswerWhyWhat to do
422 root_mode_not_offeredThe 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_requiredThe 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_diskRebuild 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_changeThe 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_mismatchThe 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_pendingThe 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

A whole disk is offered in ap-southeast-1 and us-east-1 (see Regions); elsewhere a binding with no path answers 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). A Machine has at most 1 Volume.
  • The Volume is billed for the bytes it holds, as any Volume (see Pricing). 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).
  • 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).

Next steps