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

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

Sign in at [tonbo.dev](https://tonbo.dev/login) 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 {#install}

**CLI**

```shell
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](https://tonbo.dev/docs/platform/api-keys.md#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](https://tonbo.dev/docs/reference/cli.md#updates)).

**API**

Create a key under **API keys** in the console, without narrowing it, and keep it in your shell:

```shell
export TONBO_API_KEY=tbo_...
```

## Create a Volume for the work {#volume}

**CLI**

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

**API**

```shell
VOLUME=$(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](https://tonbo.dev/docs/machines/volumes.md)), and you pay for the bytes it stores, not its size (see [Pricing](https://tonbo.dev/docs/machines/pricing.md)).

## Create the Machine {#create}

**CLI**

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

**API**

```shell
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; done
```

The 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: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 {#work}

Each command runs in the Machine and answers its output and exit status:

**CLI**

```shell
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
```

**API**

```shell
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":["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](https://tonbo.dev/docs/machines/exec.md)). Commit the change, so the next step has something to find:

```shell
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](https://tonbo.dev/docs/machines/processes.md)).

**CLI**

```shell
tonbo machine exec agent --detach --cwd /workspace/demo -- git log --oneline
tonbo machine output agent <process> --follow
```

**API**

```shell
curl -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 {#away}

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:

**CLI**

```shell
tonbo machine sleep agent --wait
```

**API**

```shell
curl -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; done
```

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

**CLI**

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

**API**

```shell
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":["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](https://tonbo.dev/docs/machines/database.md) (see [What comes back](https://tonbo.dev/docs/machines/guarantees/sleep.md#continue)). A [hold](https://tonbo.dev/docs/machines/holds.md) keeps it awake while the agent thinks between two commands.

## Look inside {#look}

Open a terminal in the Machine, where the agent works:

```shell
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](https://tonbo.dev/docs/machines/ssh.md)).

## Delete it {#delete}

**CLI**

```shell
tonbo machine delete agent
tonbo volume delete workspace
```

Type each name to confirm.

**API**

```shell
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](https://tonbo.dev/docs/machines/manage.md).

## Next steps {#next-steps}

- [Run commands](https://tonbo.dev/docs/machines/exec.md): Every field of a command, streaming output, and a lost answer.
- [Read and write files](https://tonbo.dev/docs/machines/files.md): Read, write, list and move files, and which of them last.
- [Connect with SSH](https://tonbo.dev/docs/machines/ssh.md): ssh, scp, sftp and your editor, with nothing to install.
- [Keep it awake with holds](https://tonbo.dev/docs/machines/holds.md): Keep the Machine awake while your agent thinks between two commands.
- [HTTPS service (Machine)](https://tonbo.dev/docs/getting-started/quickstarts/machine.md): Serve HTTPS from a Machine that wakes on each request.
- [Run GitHub Actions jobs](https://tonbo.dev/docs/machines/github-actions.md): Run your CI on the same kind of Machine.
