botdb docs

What botdb is, how it works, and the concepts used throughout these docs.

botdb is a command-line tool for end-to-end encrypted, local-first SQL databases that sync across machines. It is built for AI agents: anything an agent needs to remember with structure (a watchlist, a reading log, a task queue, preferences) goes into a real SQL table instead of a JSON file or a paid memory API.

botdb is a single static Rust binary, botdb, with SQLite bundled.

How it works

• Every device keeps a full copy. Each device or agent has a local SQLite copy of each database. Reads and writes never wait on the network, and everything works offline.
• Changes are logical and mergeable. Each write is captured as row and column changes. Changes from different devices merge with CRDT rules: per-column last-writer-wins ordered by hybrid logical clocks, and causal length for row deletes. See Conflict resolution.
• Sync goes through a dumb remote. Changes are encrypted on the device and exchanged through a remote: botdb cloud (the hosted relay, the default), a relay server you host yourself (botdb relay), or any shared folder (iCloud Drive, Dropbox, Syncthing, a USB drive). Remotes store padded ciphertext. They can’t read or forge data.
• One phrase restores everything. A vault holds your master secret. It derives an encrypted catalog that lists your databases and their keys, so a new machine gets everything back from a 24-word recovery phrase.

 machine A               remote                 machine B
 SQLite copy  ─push─▶  relay or folder  ─pull─▶  SQLite copy
 and keys     ◀─pull─  ciphertext only  ◀─push─  and keys

Concepts

Example

An agent tracking the movies you’ve watched. A SQL table fits this better than paying for a memory system or juggling JSON files with no backups:

botdb create movies
botdb sql -d movies "CREATE TABLE watched (
  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
  title TEXT NOT NULL DEFAULT '',
  rating INTEGER,
  watched_at TEXT DEFAULT (datetime('now'))
)"
botdb sql -d movies "INSERT INTO watched (title, rating) VALUES (?, ?)" -p "Dune: Part Two" -p 5
botdb sql -d movies "SELECT title, rating FROM watched WHERE rating >= 4 ORDER BY watched_at DESC"

The same table is available on your other machines, to other agents you invite, and in every backup.

Architecture

botdb is a set of Rust crates: botdb-core (ids, clocks, the change model, crypto, the relay protocol), botdb-sqlite (the storage engine), botdb-sync (the sync loop and transports), botdb-relay (the relay server), botdb (vault, catalog, sharing, backups) and botdb-cli (the botdb binary, including relay and mcp).

The pieces meet at a few traits:

The change log references tables and columns by stable ids and rows by primary key, never by engine internals. SQLite could be swapped for another engine that implements Replica (for example PGlite or Turso) without changing the change-log format.

There is no daemon. botdb pulls before reads when its copy may be stale and pushes after writes from a short-lived background process. See Automatic sync.

Intended scale: databases up to about 100 MB, and dozens of devices per database.

Next steps

• Install botdb
• Quickstart: create a database and run your first queries
• Multiple machines: restore your vault and share databases
• Using with agents: skill, MCP server and headless setups

start

• InstallationInstall the botdb CLI, verify it, and set up shell completions.
• QuickstartCreate a vault and a database, define a table, write and query rows, and undo changes.
• Multiple machinesRestore your vault on a second machine, share one database with someone else, and set up agents.

guides

• botdb cloudThe hosted relay botdb syncs through by default, what it stores, accounts, plan limits and how to leave.
• Using with agentsGive agents persistent SQL tables through the botdb skill, the MCP server, or the CLI in headless environments.
• Sharing and invitesShare a single database with another person or agent, make it read-only, and remove members with key rotation.
• Backups and recoveryThe layers that protect your data, the recovery phrase, local snapshots, encrypted archives, plain exports, and how to recover from common mistakes.
• Self-hosting a relayRun botdb relay with the binary, Docker or systemd behind a TLS reverse proxy, and point clients at it.
• Syncing through a folderUse iCloud Drive, Dropbox, Google Drive, OneDrive, Syncthing or a USB drive as a botdb remote instead of a relay.
• For agentsThe agent skill (SKILL.md), rendered.

reference

• CLI referenceEvery botdb command, argument and option.
• SQL support and table rulesThe SQL dialect botdb accepts, which statements and schema features are allowed, and why.
• Conflict resolutionHow botdb merges concurrent changes from devices that edited offline, for rows, columns, deletes and schema.
• Configuration and environmentbotdb's home directory, keystores, environment variables, automatic sync, output formats and defaults.
• Relay protocolThe HTTP API between botdb clients and relays, request signing, and how batches, cursors and snapshots work.

security

• Threat model and cryptographyWhat botdb protects, what relays and folder hosts can see and do, and the cryptographic design behind it.