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

# How Volumes work

Last updated 17 November 2026

A Volume keeps its data on the disk of the server your Machine runs on, and Tonbo copies it to storage in the Machine’s region. This page explains why it is built that way and what that means for your program. What Tonbo promises is the Volume text on [Data guarantees](https://tonbo.dev/docs/machines/guarantees/data/volume.md); where this page and that one seem to differ, that one holds.

## Why the data is on the server’s disk {#working-copy}

Every read and write goes to a working copy on the local disk of the server the Machine runs on. That is why a Volume is as fast as a local disk (see [Performance](https://tonbo.dev/docs/machines/volumes/performance.md)), and why `fsync` waits only for that disk, not for the network. The price is that, until the next copy, the newest writes are on that one server alone.

```text
  your program
     |  reads and writes, and fsync
     v
  THE WORKING COPY, on the disk of the server the Machine runs on
     |  the blocks that changed, about once a minute while the Machine
     |  is awake, and once more every time it goes to sleep
     v
  THE LAST FINISHED COPY, in storage in the Machine's region
```

## Why it is copied, and when {#copies}

To keep a Volume beyond one server, Tonbo copies the blocks that changed to the region’s storage about once a minute while the Machine is awake, sooner after a burst of writes, and once more every time the Machine goes to sleep; the sleep finishes only once that copy has. Copying in the background, rather than on every `fsync`, is what keeps `fsync` fast. So that the copies never fall far behind, `fsync` itself waits once copying is five minutes behind, until it catches up.

Each copy holds the whole Volume as it was at one moment. A Volume restored from a copy is therefore that moment exactly, never a mix of two.

## When a server is lost or stops responding {#server-loss}

If the server is lost, the Volume is restored on another server from its last finished copy. If it stops responding instead, its disk may still hold writes that no copy has, so Tonbo waits up to 10 minutes for it to come back before it gives them up and restores the Volume elsewhere; the Machine cannot wake during that wait. A Machine that is asleep has finished its copy, so its Volume depends on no one server.

The region’s storage holds the last copy, not a history: a Volume is not a backup, and it does not outlive its region (see [What a Volume does not do](https://tonbo.dev/docs/machines/volumes/things-to-know.md#does-not-do)).

## A wake on the same server, or on another {#wakes}

Tonbo wakes a Machine on the server that holds its Volume’s working copy when that server has room, and the Volume is then ready at once, all of it on local disk. When it cannot, because that server is full, was replaced or was lost, the Machine wakes on another server and the Volume is restored there from its last finished copy. It is ready at once there too: the blocks your program reads are fetched first, and the rest fill in behind them. So the first reads after such a wake are slower, and they reach local-disk speed as the copy fills in.

## What this means for your program {#for-your-program}

- Call `fsync` after a write that matters; a write you only `close` may not be on disk yet.
- While the Machine is awake, the writes since the last finished copy depend on its server until the next copy finishes; once it sleeps, none do.
- When a write must be safe off the server the moment you answer, keep it in a Tonbo database and answer after `synced()` (see [Keep data on a Volume or in a database](https://tonbo.dev/docs/machines/database.md)).
- A program that reads its working set when it starts pays the slower first reads once, after a wake on another server.
- If copying cannot catch up at all, Tonbo stops the Machine rather than let `fsync` wait for ever (see [The Machine stopped because of its Volume](https://tonbo.dev/docs/machines/volumes/troubleshooting.md#volume-stopped)).

The limits, the bills and the rules for moving and deleting a Volume are on [Things to know](https://tonbo.dev/docs/machines/volumes/things-to-know.md).
