PricingConsole

Budgets

Last updated 12 November 2026In Platform

View .md

A budget is a monthly limit on what your account, or the Machines one agent or person starts, may spend. Close to the limit, fewer Machines wake and database writes slow down. At the limit, Machines sleep within 10 minutes, nothing new is created, and database writes continue slowly. A budget never deletes anything.

Account budgets and agent budgets

  • The account budget: at most one per account. It counts everything the account is charged for: Machines, their outbound data, Volumes, databases, streams and suspend images.
  • Agent budgets: up to 50 per account, each with a name, covering one or more Agents or people of the account (see People and Agents). It counts the compute and outbound data of the Machines they created, whoever wakes them later.

A budget covers an Agent or a person, not one key. An Agent is covered with every key it has now and later; a person with every personal key and every CLI login in this account. Rotating a key or logging in on a second computer stays covered, and revoking a key changes nothing. An Agent that a covered person creates joins that person’s budget as it is created, so a new Agent never starts outside it; an Agent itself creates no Agents (see What an Agent is). Each Agent or person is covered by at most one agent budget.

A limit is from $1 to $100,000. The month is the calendar month in UTC: every budget resets at 00:00 UTC on the 1st. No card is needed to set a budget, a budget unlocks nothing, and a budget above the balance is allowed: the balance still stops spending when it runs out (see When the balance runs out).

What counts

What a budget has used is what was charged this month plus what is committed and not yet charged:

  • Charged: this month’s charges at list price, whatever pays them. The monthly allowance counts, so a budget of $5 means “stay inside the allowance”.
  • Committed: the ten minutes each awake Machine has reserved, the outbound data sent and not yet charged, and, for the account budget, the database and stream writes and storage measured since the last charge. A reserved ten minutes counts at the shape’s full price and is charged at what it used, so committed can run ahead by up to one reservation per awake Machine.

The console and the API show both. Usage counts in the month its period starts: ten minutes reserved at 23:55 UTC on the last day count toward that month.

An agent budget counts Machines only. Volumes, databases, streams and suspend images are not created for one wake and are often shared, so they count toward the account budget alone. A Machine created in the console has no Agent or person behind it and counts only toward the account budget.

Stages

A Machine is held to the worse of the account budget and the budget of whoever created it.

  • ok: below 50%.
  • notice: 50% or more. Alerts only.
  • slow: 90% or more, or earlier when what is left would last less than 25 hours at the current rate (awake Machines, last hour’s outbound data and, for the account budget, last hour’s database and stream writes).
  • exhausted: 100%. It stays until the reset or a higher limit, even if what is used falls back below the limit once Machines stop.
StageMachinesOutbound dataVolumesDatabases and streams
ok, noticeAs without a budgetAs without a budgetAs without a budgetAs without a budget, under the burst guard (see below)
slowNew wakes within the slow-down rate; awake Machines keep runningCut once inside the marginAs without a budgetWrites slow down, more as what is left runs down
exhaustedNo creates and no wakes; awake Machines sleep at the end of the ten minutes paid forCutNo createsNo creates; writes continue at the floor, reads as usual

When a budget is close to its limit

The slow stage limits how much new Machine time starts. It never stops or shortens a Machine that is already awake: its sleep after idle is unchanged, and it sleeps on its own.

The slow-down rate is m-8’s hourly price ($0.68) or a 250th of the limit an hour, whichever is more: $0.68 for budgets under $170. A wake is let through when the budget has no other Machine awake, whatever its shape, or while the hourly prices of its awake Machines and the new one stay within the rate. Otherwise the wake is refused with budget_slowdown, which names the largest shape that fits now. Sleep another Machine of the budget, or set this one’s shape smaller, and wake it again. Tonbo never runs a Machine on a smaller shape than its spec says.

Outbound data is cut early enough that the next few minutes of it fit: once what is left is less than what the budget’s awake Machines can send at full speed in 150 seconds, more when the meters run late. A wake that would bring the budget inside that margin starts with its outbound data already cut.

When a budget is used up

  • Creates and wakes are refused with budget_exhausted. An awake Machine sleeps at the end of the ten minutes already paid for, with its usual drain (see Sleep and wake).
  • Sleeping, deleting, reading and changing a spec, a smaller shape included, always work.
  • Nothing is deleted. A Machine stopped by its budget keeps its spec and Volume, and its delete_after does not run until it has woken again after the reset or a raise.
  • An inbox event sent to such a Machine is kept, and the Machine wakes for it after the reset, at a time up to 10 minutes past 00:00 UTC so that a fleet does not wake in one second. A raise is picked up within 10 minutes.

An agent with a budget works on its own Machines

An Agent or person covered by an agent budget may wake, update, set secrets on, run commands in, use the files, processes and holds of, reach the private ports of and log in over SSH to only the Machines it created. It can still list, read, sleep and delete others as its role allows. Anything else is refused with 403 budget_scope. Otherwise an agent with a $50 budget could do its work on a Machine a person made, whose spend lands on no agent budget.

Who sets and changes a budget

Owners and admins set budgets (see Roles). In the console, they can do anything: set or change the account budget, raise a limit, remove a budget, and add or move any Agent or person. With the API or the CLI, with any key or login, they can only:

  • create an agent budget over themselves, their own Agents and Agents they created;
  • lower the budget that covers them, and add to it Agents they own or created.

Everything else answers 403 budget_raise_in_console with a link to the budget in the console. An agent holding an admin key or a person’s login can therefore tighten its own budget but never loosen it. A changed limit takes effect at the next wake, ten minutes or create.

Database and stream writes slow down

An account budget never refuses a database or stream write. It slows them instead: a write is answered later, and the bill grows more slowly, because writes are charged per 10 KiB written and storage grows only by writes (see Databases pricing). Reads are never slowed. Agent budgets do not slow writes, since they do not count databases.

Only appends to your databases and streams by people and Agents are slowed. Never slowed: a Machine’s own writes (its logs, the database it binds, its Volume), reads, deletes, retention changes, snapshots, and Tonbo’s own creates and deletes.

How fast writes go

The pace is in write units of 10 KiB, across all of the account’s regions:

  • ok, notice: the burst guard, which lets at most a quarter of what is left be written in about three minutes. It never slows an ordinary app: a $50 budget at 0% allows about 45,045 units a second.
  • slow: what is left spread over the next 25 hours (or the time to the reset, if shorter), and never below the floor. It starts just under the account’s whole spend rate and tightens as what is left runs down: a $50 budget at 90% writes about 37 units a second.
  • exhausted: the floor, 1 to 4 units a second: 1 for budgets under $8.04, 4 from $32.15, and in between whatever makes a whole month at the floor cost half the budget. One commit of a small transaction is one unit.

One writer gets a share of the pace. Writers of the same account take turns, and each writer’s databases and streams take turns within its share, so one busy agent or one large append does not hold up another writer. A large append delays only that writer’s later writes.

The most writes can cost past the limit

If a budget is used up at 00:00 UTC on the 1st of a 31-day month and the account writes full units at the floor until the reset:

FloorBudgetsWrites past the limitStorage they add, that month
1 unit a secondunder $8.04$4.0225.5 GiB, $0.66
Half the budget over the month$8.04 to $32.15half the budgetat most $2.64
4 units a second$32.15 and up$16.07102 GiB, $2.64

A budget used up later in the month passes its limit by less. The storage stays, and is charged in later months as all storage is; a budget deletes none of it.

What a writer sees

Every append that waited, and every append while the stage is slow or exhausted, carries a header with the pace in units a second and how long this write waited in milliseconds. It names no spend figure, so every writer may read it:

Tonbo-Write-Pace: stage=slow, rate=12.5, floor=4.0, wait=850, resets="2026-12-01T00:00:00Z", raise="https://tonbo.dev/<account>/billing/budgets/bdg_…"

A write still waiting after 60 seconds, or one more than 8 waiting from one writer or 32 from the account, is answered 504 PACED_WRITE_TIMEOUT with Retry-After. Nothing was written; send it again. Tonbo’s database package gives up and resends sooner, and a resent commit is written and charged once.

A slowed database keeps committing

Commits are local and reach Tonbo in the background, so a slowed database commits as fast as before and synced() takes longer (see Status). An app that keeps writing faster than its pace for long enough fills its own backlog, and its commits fail with backlog_full: 64 MiB of compressed commits at the 4-unit floor take about half an hour.

  • On a Machine, write through the database the Machine binds, which is never slowed (see Keep data on a Volume or in a database). A database a Machine’s program opens with a person’s or an Agent’s key is slowed like any other, so when the Machine sleeps, commits that synced() had not confirmed may be cut.
  • Do not judge whether another host is alive by timestamps you read back from a replicated database: under a slowed pace they arrive late. Nothing Tonbo runs depends on them.

How far past the limit spending can go

  • Machine compute: not at all. Every ten minutes are reserved before they run.
  • Outbound data: not at all while Tonbo’s billing answers, beyond rounding to the micro-dollar. If the cut cannot reach a Machine, at most ten minutes at its full speed.
  • Database and stream writes by people and Agents, under an account budget: at most the floor, above.
  • A Machine’s own writes, until it has slept: about a quarter of an hour at its own limits.
  • Storage already held: Volumes, stored database and stream bytes and suspend images keep their storage charge while held. The console shows it as after the limit, and an email goes at 125%.

What an agent sees

  • 402 budget_exhausted: the budget is used up until retry_at, also in Retry-After. Stop, rather than retry before then; a person can raise it at raise_url.
  • 402 budget_slowdown: the same request fails again. Sleep another Machine of this budget, or set the shape to largest_shape_that_fits, and wake again.
  • 403 budget_scope: this caller’s budget confines it to its own Machines.
  • 403 budget_raise_in_console: only the console makes this change, at raise_url.

Each 402 carries the budget:

"budget": {
  "id": "bdg_…",
  "scope": "principals",
  "name": "pi-agent",
  "stage": "exhausted",
  "limit_micros": 50000000,
  "settled_micros": 48210000,
  "committed_micros": 1910000,
  "resets_at": "2026-12-01T00:00:00Z",
  "retry_at": "2026-12-01T00:07:12Z",
  "raise_url": "https://tonbo.dev/<account>/billing/budgets/bdg_…",
  "raise_roles": ["owner", "admin"],
  "raise_channel": "console"
}

GET /v1/account answers budgets.account and budgets.caller, the budget covering the caller, and GET /v1/budgets lists them. From notice on, every Management API answer carries a header:

Tonbo-Budget: stage=slow, scope=principals, used=0.91, resets="2026-12-01T00:00:00Z"

A caller who may read usage sees every figure. A caller covered by an agent budget sees all of its own budget’s. Anyone else sees only the scope, the stage, resets_at, retry_at and raise_url, and the header without used.

Alerts

Tonbo emails at 50%, at 80%, when the budget slows, when it is used up, and, for the account budget, at 125%. Each is sent once a month per budget, and again only after the reset or a changed limit. They go to the account’s verified owners and, for an agent budget, to each covered person and the person who created each covered Agent, when their email is verified. Each links to the budget in the console.