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

# Agents

Last updated 12 November 2026

An Agent is a member of an account that is not a person: an identity for a program, a CI job or a coding agent, which acts only through its own API keys, with the role and the budget you give it.

## Add an Agent {#add-agent}

In the console, open **Members**, choose **New Agent**, give it a name and a role, and choose **Create Agent**. The console opens the Agent’s page: choose **New API key** there to make its first key. With the CLI or the API, create the Agent, then a key that acts as it. Without a role, an Agent is a `member`.

**CLI**

```shell
tonbo agent create release-bot
tonbo api-key create release-bot-ci --member release-bot
```

**API**

```shell
export AGENT=$(curl -sS https://api.tonbo.dev/v1/agents \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"release-bot"}' | jq -r .data.subject)

curl -sS https://api.tonbo.dev/v1/api-keys \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"release-bot-ci","member":"'"$AGENT"'"}'
```

The key’s secret is shown once. To rename an Agent, use the name field in its **Settings**, `tonbo member update release-bot --name deploy-bot`, or `PATCH /v1/members/{subject}` with a `name`. It keeps its id, keys and home region. The account’s operations are in the [Management API reference](https://tonbo.dev/docs/reference/management/account.md).

## How an Agent is authorized {#agent-access}

An Agent is authorized like a person of its account, through its keys, with less: it holds no login, it never acts outside its one account, and it cannot give itself or anyone more access.

### What an Agent is {#agent-identity}

- An identity of one account, a personal account or an organization, and a member of that account only. Its subject is `agent.<agent id>`; its name and its home region are its own.
- Its role is `member` unless an owner or admin gives it another; only an owner gives `owner`. A change applies to the next request of every key it holds.
- Whatever its role, it creates no Agents and no keys, and changes no member’s role or name. It may be an owner, but an account always keeps a person as owner as well.

### How an Agent authenticates {#agent-auth}

A key that acts as an Agent is never accepted directly: the Management API, Streams and the database origins answer `401 exchange_required`, naming the token endpoint. The Agent’s program exchanges the key there for a token of the API it calls: the audience `https://api.tonbo.dev` for the Management API, and `https://streams.tonbo.dev` for databases and streams.

```shell
curl -sS -X POST https://tonbo.dev/api/iam/token \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audience":"https://api.tonbo.dev"}' | jq -r .access_token
```

- The token acts as the Agent: its `sub` is the Agent’s subject and its `client_id` the key’s id, and it reaches the key’s account only.
- The Node.js SDK exchanges the key itself, for databases and for the Management API. The Python package takes a token for an Agent’s key, exchanged first (see [The token exchange](https://tonbo.dev/docs/platform/api-keys.md#exchange)).
- The `tonbo` CLI exchanges an Agent’s key in `TONBO_API_KEY` the same way, so its commands act as the Agent.

### What its token reaches {#agent-reach}

Only the key’s account: a database or stream of another account answers as if it did not exist. Inside the account, a key that is not narrowed reaches everything the Agent’s role reaches: every database, stream and Machine of the account, whoever created them. Databases and streams belong to the account, not to a member, so an Agent has none of its own.

- **Narrowed by name.** A key narrowed when it is created, to databases and database name prefixes (`--database`, `--database-prefix`), to streams and stream prefixes (`--stream`, `--stream-prefix`), or to read-only (`--read-only`), reaches only those, for its whole life. It creates nothing, not even a database it names, and through the Management API it only reads.
- **Machines.** A narrowed key neither manages nor calls Machines, and no key is narrowed to one Machine. An agent budget is what confines an Agent to its own Machines (see [What its budget limits](#agent-budget)).
- **Down-scoped for one client.** The Agent’s server can mint, from its key, a Streams token for a few named databases or streams, read-only unless it asks otherwise and never wider than the key, to hand to a web page (see [Tokens for a web page](https://tonbo.dev/docs/platform/api-keys.md#down-scope)).

### How long a token lives {#agent-lifetime}

- A token lives 10 minutes, or less when the key expires sooner. The Node.js SDK exchanges again before it expires; another program exchanges again itself.
- A key never expires unless you choose an expiry when you create it: 15 days, a month, six months or a year (**Expires** in the console, `--expires-in`, `expires_in`).
- Revoking a key stops new exchanges at once, and the Management API refuses its tokens from the next request. Streams refuses its tokens in every region shortly after; in any case they stop at their expiry, plus the 60 seconds Streams allows for clock skew. Deleting the Agent revokes all of its keys.

### Who manages its keys and its role {#agent-keys}

- **Create a key**: owners and admins, for an Agent whose role is no higher than their own, on the Agent’s page under **Members** or with **New API key** on **API keys**, choosing it under **Acts as**. The Agent never creates one, since a token never creates a key.
- **Rotate**: create the next key, give it to the program, then revoke the old one. A key is never changed in place, so a new narrowing or expiry also takes a new key.
- **Revoke**: owners and admins revoke any key of the account, on **API keys** or the Agent’s page, and the Agent revokes its own keys through the API.
- **Change its role or name**: owners and admins, on the Agent’s page; only an owner changes an owner’s. **Delete it**: owners and admins, in the console only.

**CLI**

```shell
tonbo api-key create release-bot-ci-2 --member release-bot
tonbo api-key list
tonbo api-key revoke <old key id>
```

**API**

```shell
curl -sS https://api.tonbo.dev/v1/api-keys \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"release-bot-ci-2","member":"'"$AGENT"'"}'

curl -sS https://api.tonbo.dev/v1/api-keys \
  -H "Authorization: Bearer $TONBO_API_KEY"

curl -sS -X DELETE https://api.tonbo.dev/v1/api-keys/<old key id> \
  -H "Authorization: Bearer $TONBO_API_KEY"
```

### What its budget limits {#agent-budget}

An agent budget that covers an Agent counts the compute and outbound data of the Machines it creates. Close to the limit fewer of them wake; at the limit they sleep and none is created or woken until the month resets or a person raises the limit in the console. It confines the Agent to its own Machines: it wakes, changes, sets secrets on, runs commands in and logs in to only the Machines it created, and can still list, read, sleep and delete the others as its role allows. It never stops the Agent’s database or stream writes, which count toward the account budget. An Agent with the `admin` or `owner` role may lower the budget that covers it; no Agent raises one (see [Budgets](https://tonbo.dev/docs/platform/budgets.md)).

### A least-privilege Agent {#least-privilege}

A nightly job writes its results to one database, `reports`, and should reach nothing else. A person creates the database, an Agent with the `member` role, and a key that acts as the Agent, narrowed to that database and expiring in six months:

**CLI**

```shell
tonbo database create reports
tonbo agent create report-job
tonbo api-key create report-job --member report-job --database reports --expires-in 6_months
```

**API**

```shell
curl -sS https://api.tonbo.dev/v1/databases \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"reports"}'

export AGENT=$(curl -sS https://api.tonbo.dev/v1/agents \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"report-job"}' | jq -r .data.subject)

curl -sS https://api.tonbo.dev/v1/api-keys \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"report-job","member":"'"$AGENT"'","databases":["reports"],"expires_in":"6_months"}'
```

The job keeps the key in `TONBO_API_KEY` and opens the database by name with the Node.js SDK, which exchanges the key (see [Opening by name](https://tonbo.dev/docs/platform/api-keys.md#open-by-name)). Its tokens read and write `reports` and nothing else: no other database, no stream, no Machine, no account change and no new key. Add `--read-only` to a key for a job that only reads. Before the six months end, rotate the key as above.

## Budgets for the account, an Agent or a person {#budgets}

A budget is a monthly spend limit, and it attaches either to the account or to members:

- **The account budget**, at most one, counts everything the account is charged for. It is set in the console only.
- **An agent budget** covers one or more Agents or people, up to 50 per account. It counts the Machines they create, and confines each of them to working on its own Machines. It covers the member, not one key: every key it holds now and later, and a person’s logins too. An Agent that a covered member creates joins the same budget.

Owners and admins set budgets. In the console, open **Usage & billing** and choose **Set budget**. With the CLI or the API they can only create a budget over themselves and Agents they created, and lower the budget that covers them: raising a limit or covering another member is the console’s. How a budget stops spending is in [Budgets](https://tonbo.dev/docs/platform/budgets.md), and the steps are in [Give an Agent a budget](https://tonbo.dev/docs/platform/agent-budget.md).

## Limits {#limits}

- An Agent’s name is 1 to 40 lowercase letters, digits or single hyphens, starting with a letter, and unique among the account’s active Agents.
- An account has one account budget and up to 50 agent budgets; each member is covered by at most one.
