Give an Agent a budget
Last updated 12 November 2026
Put an Agent under a monthly spend limit for the Machines it creates, and give the program that runs as it a key. Owners and admins set budgets. The steps below create an Agent named coder with a limit of $50; what a budget counts and how it stops spending are on Budgets.
Create the Agent, its budget and its key
In the console, add the Agent on Members (see Add an Agent), then open Usage & billing, choose Set budget and pick the Agent. With the CLI or the API, you can cover only yourself and Agents you created:
tonbo agent create coder
tonbo budget add coder --limit 50 --member coder
tonbo api-key create coder --member coderexport 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":"coder"}' | jq -r .data.subject)
curl -sS https://api.tonbo.dev/v1/budgets \
-H "Authorization: Bearer $TONBO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"scope":"principals","name":"coder","limit_micros":50000000,"principals":["'"$AGENT"'"]}'
curl -sS https://api.tonbo.dev/v1/api-keys \
-H "Authorization: Bearer $TONBO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"coder","member":"'"$AGENT"'"}'The key’s secret is in its answer only. Leave the key unnarrowed: a key narrowed to databases or streams neither manages nor calls Machines (see What its budget limits).
See what it has used
tonbo budget show codercurl -sS https://api.tonbo.dev/v1/budgets \
-H "Authorization: Bearer $TONBO_API_KEY" | jq '.data[] | select(.name == "coder")'It shows the limit, what was charged and committed this month, whom it covers, its stage and when it resets: at 00:00 UTC on the 1st.
Change the limit
To lower it, or to add Agents you created, use the CLI or the API. The API sends the ETag a read of the budget answered:
tonbo budget set coder --limit 25ETAG=$(curl -sS -o /dev/null -D - https://api.tonbo.dev/v1/budgets/<budget id> -H "Authorization: Bearer $TONBO_API_KEY" \
| awk 'tolower($1) == "etag:" {sub(/\r$/, "", $2); print $2}')
curl -sS -X PATCH https://api.tonbo.dev/v1/budgets/<budget id> \
-H "Authorization: Bearer $TONBO_API_KEY" \
-H "If-Match: $ETAG" \
-H "Content-Type: application/json" \
-d '{"limit_micros":25000000}'Raising a limit, renaming a budget and removing a member from it are done in the console only, on the budget’s page: the CLI prints that page and opens it, and the API refuses with 403 budget_raise_in_console and the page’s link. A lower limit takes effect at the next wake, the next create or the month’s reset (see Who sets and changes a budget).