> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt # Manage Machines Last updated 2 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.” Create and change Machines by hand or from a script: each operation with the CLI and the Management API side by side, for when you set up, change or remove a Machine. The API takes a key of your account in `TONBO_API_KEY` (see [API keys and tokens](https://tonbo.dev/docs/platform/api-keys.md)), and every refusal is a [problem document](https://www.rfc-editor.org/rfc/rfc9457.html) whose `code` is a row of [Troubleshooting](https://tonbo.dev/docs/machines/troubleshooting.md). Machines are managed with the CLI or the API; the console has no Machines pages. ## Create a Machine **CLI** ```shell tonbo machine create app --image registry.example.com/you/app:1 --shape s-2 --port 8080 --port 9000:public --default-port 8080 --env LOG_LEVEL=info --sleep-after 900 --region us-east-1 --wait ``` **API** ```shell 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 '{"name":"app","image":"registry.example.com/you/app:1","shape":"s-2","region":"us-east-1","ports":[{"port":8080,"access":"private","default":true},{"port":9000,"access":"public","default":false}],"env":{"LOG_LEVEL":"info"},"sleep_after_seconds":900}' ``` `shape` is required in the API; the CLI takes m-8, with 8 vCPUs, when you name none, so name one (see [the rule](https://tonbo.dev/docs/machines/rules/images.md#shape)). Send an [Idempotency-Key](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/), so a create you send again returns the same Machine. Words after `--` replace the image’s command. `--sleep-after` sets the sleep-after time (`sleep_after_seconds` in the API), and `--stop-grace` the stop grace (`stop_grace_seconds`). The bounds of every setting are on [Limits](https://tonbo.dev/docs/machines/limits.md#settings). ## Wait until it is active Tonbo pulls the image before a Machine is `active`. With `--wait`, as above, the CLI waits until it is, and says why if it failed (`--timeout` bounds the wait). Through the API, a create answers `202` while Tonbo pulls the image, with `Location` and `Retry-After: 2`; read the Machine until `state` is `active`, or `failed` with a `failure` that says why. ## List and show **CLI** ```shell tonbo machine list tonbo machine show app ``` **API** ```shell curl -sS https://api.tonbo.dev/v1/machines -H "Authorization: Bearer $TONBO_API_KEY" curl -sS -i https://api.tonbo.dev/v1/machines/app -H "Authorization: Bearer $TONBO_API_KEY" ``` A read answers the Machine with its `ETag`, which a change through the API sends back. ## Wake history **CLI** ```shell tonbo machine activations app ``` **API** ```shell curl -sS https://api.tonbo.dev/v1/machines/app/activations -H "Authorization: Bearer $TONBO_API_KEY" ``` The newest wakes come first. Each entry shows what woke the Machine, the spec revision and shape it used, and how it ended. The list accepts `--limit` and`--cursor` in the CLI, or `limit` and `cursor` query parameters in the API. Any account member can read this history while Machines are closed; a personal device has no wake history. ## Change a Machine **CLI** ```shell tonbo machine update app --shape m-4 --sleep-after 1800 ``` **API** ```shell curl -sS -X PATCH https://api.tonbo.dev/v1/machines/app \ -H "Authorization: Bearer $TONBO_API_KEY" \ -H 'If-Match: ""' \ -H "Content-Type: application/json" \ -d '{"shape":"m-4","sleep_after_seconds":1800}' ``` `If-Match` is required: without it the answer is [428](https://tonbo.dev/docs/machines/troubleshooting/manage.md#precondition_required), and with a stale ETag [412](https://tonbo.dev/docs/machines/troubleshooting/manage.md#precondition_failed). The CLI reads the ETag itself. When each change applies is on [Deploy a change](https://tonbo.dev/docs/machines/deploy.md#when). ## Put it to sleep **CLI** ```shell tonbo machine sleep app ``` **API** ```shell curl -sS -X POST https://api.tonbo.dev/v1/machines/app/sleep -H "Authorization: Bearer $TONBO_API_KEY" ``` It answers `202` while the Machine goes to sleep, and `200` when it is already asleep. ## Delete a Machine **CLI** ```shell tonbo machine delete app --yes ``` **API** ```shell curl -sS -X DELETE https://api.tonbo.dev/v1/machines/app -H "Authorization: Bearer $TONBO_API_KEY" ``` Deleting a Machine deletes its disks and its database. A Volume attached to it is detached and kept, and is billed until you delete it. Without a terminal the CLI needs `--yes`. The API answers `202`, then the Machine is gone. Its name is free at once for a new Machine of your account, which gets the same HTTPS names; no other account can take them (see [Its HTTPS name](https://tonbo.dev/docs/machines/concepts.md#name)). ## Shapes **CLI** ```shell tonbo machine shapes ``` **API** ```shell curl -sS https://api.tonbo.dev/v1/machine-shapes -H "Authorization: Bearer $TONBO_API_KEY" ``` Each shape is listed with its vCPUs, memory, scratch disk and the most an awake hour can cost (see [Pricing](https://tonbo.dev/docs/machines/pricing.md)). ## Volumes A Volume is created, listed and deleted on its own, and attached to one Machine at a path; it cannot be deleted while it is attached (see [Files on its Volume](https://tonbo.dev/docs/machines/database.md#volume)). Volumes are not offered yet, and no command creates one; until they are, a create or update that names one answers [volumes_not_offered](https://tonbo.dev/docs/machines/troubleshooting/manage.md#volumes_not_offered). ## Regions Machines run in `us-east-1` and `ap-southeast-1`. A Machine’s region is fixed when you create it; elsewhere a create answers [region_not_offered](https://tonbo.dev/docs/machines/troubleshooting/manage.md#region_not_offered).