Manage Machines

Last updated 2 November 2026

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), and every refusal is a problem document whose code is a row of Troubleshooting. Machines are managed with the CLI or the API; the console has no Machines pages.

Create a Machine

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

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}'

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.

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

tonbo machine list
tonbo machine show app

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

tonbo machine activations app

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

tonbo machine update app --shape m-4 --sleep-after 1800

curl -sS -X PATCH https://api.tonbo.dev/v1/machines/app \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H 'If-Match: "<the ETag the GET answered>"' \
  -H "Content-Type: application/json" \
  -d '{"shape":"m-4","sleep_after_seconds":1800}'

When each change applies is on Deploy a change.

Put it to sleep

tonbo machine sleep app

curl -sS -X POST https://api.tonbo.dev/v1/machines/app/sleep -H "Authorization: Bearer $TONBO_API_KEY"

Delete a Machine

tonbo machine delete app --yes

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

Shapes

tonbo machine shapes

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

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). Volumes are not offered yet, and no command creates one; until they are, a create or update that names one answers 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.