Tonbo Documentation
Durable state for agents and the programs around them: SQLite databases that outlive their machine, streams any program reads live, and services that sleep when idle.
Add a Tonbo database to this project: SQLite the program opens by name, which outlives the machine. If I asked for an append-only log that programs append to and read, add a Tonbo stream instead. 1. Check that TONBO_API_KEY is set, in the environment the program runs with or in the .env or secret store the project already uses; check only that it is set, and never print it. If it is not set, stop and ask me to create a key in the Tonbo console under API keys and set it. Do not guess, invent or hardcode a key, and never write one into source code. 2. Check that the Tonbo CLI is signed in as me: `env -u TONBO_API_KEY tonbo account show`. If `tonbo` is missing or not signed in, stop and ask me to run `npm i -g @tonbo/cli` and `tonbo login`. Run every `tonbo` command below as `env -u TONBO_API_KEY tonbo`, so it acts as my login rather than the program's key. 3. Detect the stack in the current directory. In a monorepo, work only in the current directory and below. Take the first that matches: - a package.json that depends on `@earendil-works/pi-durable`: https://tonbo.dev/docs/getting-started/quickstarts/pi#setup - a package.json that depends on `drizzle-orm`: https://tonbo.dev/docs/getting-started/quickstarts/drizzle#setup - any other package.json (Node.js): https://tonbo.dev/docs/getting-started/quickstarts/sqlite#setup - a pyproject.toml, requirements.txt or setup.py (Python): https://tonbo.dev/docs/getting-started/quickstarts/sqlite-python#setup - a stream, in any language: https://tonbo.dev/docs/getting-started/quickstarts/stream#setup If none matches, stop and ask me. 4. Read only the section headed "Add it to a project" at that link, and follow it. Use the name I gave, or else the page's example name, and tell me which. Rules: - Add only a database or a stream. Do not create, change or delete any other Tonbo resource, and do not touch Machines or any other product. - Do not run application code. Install the packages at the exact versions the section names, and change no other dependency. - Put the key only where the project already keeps secrets. Success: `env -u TONBO_API_KEY tonbo database show <name>` (or `stream show <name>`) prints `State:` with `active`, and the section's install check, if it names one, prints what it says. Then tell me the one command that runs the program with TONBO_API_KEY set. For anything else, start at https://tonbo.dev/docs.
Start with a quickstart
Start with Pi Durable, or pick another; each runs from your laptop.
- Pi Durable Start herePi Durable, an open-source agent harness, keeping its conversation in a database another machine resumes.
- SQLite/Node.jsFrom sign-in to a first commit with node:sqlite on a replicated database.
- SQLite/PythonFrom sign-in to a first commit with Python’s sqlite3 on a replicated database.
- Durable stream (HTTP)Create a stream, then append to it, read it, tail it and close it with curl.
- HTTPS service (Machine) Not open yetRun a public arm64 image as an HTTPS service, call it, put it to sleep and wake it, from your laptop.
- Drizzle ORMFrom sign-in to a first Drizzle query on a replicated database.
- DatabasesSQLite databases your program opens by name from any machine: local speed, and they outlive the machine.
- StreamsDurable logs at HTTPS URLs: append exactly once, read from any offset, tail them live.
- Machines Not open yetHTTP and WebSocket services from your own arm64 image that sleep when idle, keeping what lasts in their own database and Volume.
What people build
Each links to the page that shows how.
- An agent that outlives its sandboxIts state and its conversation reopen on the next machine.
- A database per agent, task or tenantCreate and delete them by API; an idle one costs only what it stores.
- An email or a payment made onceRecorded before it is made, so a crash or a second instance never repeats it.
- An agent’s transcript or event logAppended exactly once, replayed from any offset.
- Live progress for many readersTailed with a long-poll or Server-Sent Events; reads are free.
Use a client library
Databases from Node.js and Python; streams over plain HTTP.
- JavaScript@tonbo/sqlite-ursula, Tonbo’s Node.js package, for databases.
- Pythonsqlite-ursula, Tonbo’s Python package, for databases, on Python’s own sqlite3.
- HTTPStreams, from any HTTP client, over the HTTP these pages document.
- CLI@tonbo/cli: databases, streams and keys from a terminal. (opens in a new tab)
Manage your account
Keys, usage and billing for your account.
Need some help? Talk to a founder ↗ (opens in a new tab)
Pricing and limits? See pricing