PricingConsole

Quickstart: a computer for your agent

Last updated 16 November 2026In Getting started

View .md

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 login

tonbo 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 Volume for the work

tonbo volume create workspace --size 10 --region ap-southeast-1

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 infinity

The CLI warns that the Machine has no port. That is expected here: the agent’s commands and your terminal wake it, not requests.

  • node:22 has 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 infinity is the Machine’s program: with nothing to serve, it only has to keep running while the agent works.
  • --shape s-1 is 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.js

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

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

The agent’s next command wakes it, and the work is where it left it:

tonbo machine exec agent --cwd /workspace/demo -- git log --oneline

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 agent

cd /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 workspace

Type each name to confirm.

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