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

# Keep it awake with holds

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

A hold keeps an awake Machine awake for as long as you say, even while nothing calls it: an agent thinking between two commands, or a program inside the Machine downloading or uploading. A hold never wakes a Machine.

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

## Why it matters

Every wake starts fresh, so a Machine that sleeps between an agent’s calls loses what its commands left outside the Volume and the database. A Machine stays awake while a command, a background process, a file call or a request runs, and for `sleep_after_seconds` after; it may sleep sooner when it looks idle (see [Sleep, wake and stop](https://tonbo.dev/docs/machines/sleep.md)). The Machine’s own outbound connections never keep it awake. A hold does.

## Set one from outside

```shell
curl -sS -X PUT https://api.us-east-1.tonbo.sh/v1/machines/hello/holds/agent-turn \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seconds": 900}'
```

- The hold lasts until at least now plus `seconds`, at most 1 hour. A repeat only moves its end later, so sending it on a timer is safe. To shorten one, delete it and set it again.
- `DELETE …/holds/agent-turn` ends it, whether or not it existed, and `GET …/holds` lists the live ones.
- With the Machine asleep, setting one answers 409 `machine_asleep` and wakes nothing. Wake it with a command first (see [Run commands](https://tonbo.dev/docs/machines/exec.md)).
- A Machine takes at most 32 live holds; past that the answer is 429 `hold_limit`.

## Set one from inside the Machine

A program in the Machine sets its own holds over a local socket, with no key and no network:

```shell
# From a program inside the Machine: no key and no network needed
curl -sS --unix-socket "$TONBO_GUEST_SOCKET" -X PUT http://guest/v1/holds/sync \
  -H "Content-Type: application/json" -d '{"seconds": 600}'
```

Holds set from inside and from outside are separate: neither side can end the other’s. Both count toward the 32.

## When holds end

A hold ends at its time, when it is deleted, or with the Machine’s sleep or stop, and never carries over to the next wake. An explicit sleep, a delete, a stop for want of funds, the program’s exit and the Machine’s own `max_awake_seconds` all override it. When the last hold ends, the Machine sleeps after `sleep_after_seconds` with nothing else to do. A running [background process](https://tonbo.dev/docs/machines/processes.md) keeps the Machine awake by itself, with no hold.

## What a hold costs

A held Machine is billed as any awake one. Held and idle, it costs about the memory it has touched, which only grows while it is awake, so at most its shape’s whole memory: $0.32 an hour for m-8, the default shape, and $0.08 for s-2. A Machine an agent drives as a sandbox names `s-2` at create. See [Pricing](https://tonbo.dev/docs/machines/pricing.md).