Quickstart: a computer for your agent
Last updated 16 November 2026
Give an agent a Machine of its own to work on. It runs the agent’s commands, keeps the work on a Volume, sleeps when the agent stops and wakes at its next command, and you can open a terminal in it at any time to see what the agent did or take over.
The agent can be a coding agent on your laptop, such as Claude Code or Codex, or the agent in your own product: each command is one call. You need Node.js 22 or later for the CLI, or curl and jq for the API. The run uses a few cents of your account’s monthly free usage.
Sign in
Sign in at tonbo.dev with GitHub or Google. A new account asks you to choose a username: it names your personal account, which holds your databases, streams and keys, and appears in the console’s addresses. You can change it once every 90 days.
Install the CLI or create a key
npm i -g @tonbo/cli@^0.36
tonbo logintonbo login opens a browser to sign in. Over SSH it prints a code to enter at tonbo.dev/cli/device; in CI, set TONBO_API_KEY instead (see The CLI login). When a newer release is out, the CLI says so on stderr once a day, and tonbo update installs it; the API names it in the Tonbo-CLI-Latest header of every answer, and TONBO_NO_UPDATE_NOTICE=1 silences the line (see Updates).
Create a key under API keys in the console, without narrowing it, and keep it in your shell:
export TONBO_API_KEY=tbo_...Create a Volume for the work
tonbo volume create workspace --size 10 --region ap-southeast-1VOLUME=$(curl -sS https://api.tonbo.dev/v1/volumes \
-H "Authorization: Bearer $TONBO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"workspace","region":"ap-southeast-1","size_gib":10}' | jq -r .data.id)The Volume is the agent’s working disk. What it holds lasts across every sleep (see Volumes), and you pay for the bytes it stores, not its size (see Pricing).
Create the Machine
tonbo machine create agent --image node:22 --shape s-1 --volume workspace:/workspace --region ap-southeast-1 --wait -- sleep infinityThe CLI warns that the Machine has no port. That is expected here: the agent’s commands and your terminal wake it, not requests.
jq -n --arg volume "$VOLUME" \
'{"name":"agent","image":"node:22","shape":"s-1","region":"ap-southeast-1","command":["sleep","infinity"]} + {volumes: [{volume: $volume, path: "/workspace"}]}' \
| 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 @-
until curl -sS https://api.tonbo.dev/v1/machines/agent -H "Authorization: Bearer $TONBO_API_KEY" \
| jq -e '.data.state == "active" or .data.state == "failed"' >/dev/null; do sleep 2; doneThe body names the Volume by the id the last step kept, and the loop reads the Machine until it is active, or failed with why.
node:22has Node.js, npm, git and a shell. Any public image with your agent’s tools works the same way: Machines run on 64-bit Arm, like AWS Graviton, so multi-arch images such as the official Docker Hub ones just work, and a tool you download as a single binary takes its linux-arm64 (aarch64) build.- The Volume is mounted at
/workspace. sleep infinityis the Machine’s program: with nothing to serve, it only has to keep running while the agent works.--shape s-1is the smallest shape, 1 vCPU and 2 GiB of memory, at up to $0.085 an awake hour.
Let the agent work
Each command runs in the Machine and answers its output and exit status:
tonbo machine exec agent --cwd /workspace -- git init demo
echo 'console.log("hello from the agent")' | tonbo machine file write agent /workspace/demo/hello.js
tonbo machine exec agent --cwd /workspace/demo -- node hello.jscurl -sS https://api.ap-southeast-1.tonbo.sh/v1/machines/agent/exec \
-H "Authorization: Bearer $TONBO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"command":["git","init","demo"],"cwd":"/workspace"}' | jq '.data | {exit_code, stdout: .stdout.head}'
echo 'console.log("hello from the agent")' | curl -sS -X PUT "https://api.ap-southeast-1.tonbo.sh/v1/machines/agent/files/content?path=/workspace/demo/hello.js" \
-H "Authorization: Bearer $TONBO_API_KEY" \
--data-binary @-
curl -sS https://api.ap-southeast-1.tonbo.sh/v1/machines/agent/exec \
-H "Authorization: Bearer $TONBO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"command":["node","hello.js"],"cwd":"/workspace/demo"}' | jq '.data | {exit_code, stdout: .stdout.head}'The last command prints hello from the agent. These are the calls an agent makes. A coding agent on your laptop uses the CLI: tell it to run its commands with tonbo machine exec agent --cwd /workspace/demo -- <command> and to write files with tonbo machine file write. Your own agent calls the API as one tool (see Run commands). Commit the change, so the next step has something to find:
tonbo machine exec agent --cwd /workspace/demo -- sh -c 'git add . && git -c user.name=agent -c user.email=agent@example.com commit -m "first change"'Work that takes longer than one call, such as a build or a test suite, runs in the background with --detach, not with nohup or &, which end with the call: it starts at once, keeps the Machine awake until it ends, and you read its output when you like (see Background processes).
tonbo machine exec agent --detach --cwd /workspace/demo -- git log --oneline
tonbo machine output agent <process> --followcurl -sS https://api.ap-southeast-1.tonbo.sh/v1/machines/agent/processes \
-H "Authorization: Bearer $TONBO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"command": ["git", "log", "--oneline"], "cwd": "/workspace/demo"}' | jq -r .data.process
curl -sS "https://api.ap-southeast-1.tonbo.sh/v1/machines/agent/processes/<process>/output" \
-H "Authorization: Bearer $TONBO_API_KEY"Step away and come back
Left alone, the Machine goes to sleep by itself, at most 10 minutes after its last command, or sooner when it looks idle; asleep, it pays no compute. Put it to sleep now instead of waiting:
tonbo machine sleep agent --waitcurl -sS -X POST https://api.tonbo.dev/v1/machines/agent/sleep -H "Authorization: Bearer $TONBO_API_KEY"
until curl -sS https://api.tonbo.dev/v1/machines/agent -H "Authorization: Bearer $TONBO_API_KEY" \
| jq -e '.data.status.power == "asleep"' >/dev/null; do sleep 5; doneThe agent’s next command wakes it, and the work is where it left it:
tonbo machine exec agent --cwd /workspace/demo -- git log --onelinecurl -sS https://api.ap-southeast-1.tonbo.sh/v1/machines/agent/exec \
-H "Authorization: Bearer $TONBO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"command":["git","log","--oneline"],"cwd":"/workspace/demo"}' | jq '.data | {exit_code, stdout: .stdout.head}'The commit is there because it is on the Volume. A wake starts the Machine fresh: running programs and files outside /workspace are gone, so keep the work on the Volume or in a database (see What comes back). A hold keeps it awake while the agent thinks between two commands.
Look inside
Open a terminal in the Machine, where the agent works:
tonbo ssh agentcd /workspace/demo and you see what the agent made, and can carry on from there. A login wakes an asleep Machine too, and VS Code or Cursor connect over Remote-SSH (see Connect with SSH).
Delete it
tonbo machine delete agent
tonbo volume delete workspaceType each name to confirm.
curl -sS -X DELETE https://api.tonbo.dev/v1/machines/agent -H "Authorization: Bearer $TONBO_API_KEY"
curl -sS -X DELETE https://api.tonbo.dev/v1/volumes/workspace -H "Authorization: Bearer $TONBO_API_KEY"Deleting the Machine keeps the Volume, so a new Machine can mount the same work. Once the Machine is gone, delete the Volume when you no longer need it; while a Machine still has it, the delete is refused. Every other operation is on Manage Machines.
Next steps
- Run commandsEvery field of a command, streaming output, and a lost answer.
- Read and write filesRead, write, list and move files, and which of them last.
- Connect with SSHssh, scp, sftp and your editor, with nothing to install.
- Keep it awake with holdsKeep the Machine awake while your agent thinks between two commands.
- HTTPS service (Machine)Serve HTTPS from a Machine that wakes on each request.
- Run GitHub Actions jobsRun your CI on the same kind of Machine.