docs / start
Multiple machines
Restore your vault on a second machine, share one database with someone else, and set up agents.
There are two ways to get a database onto another machine:
- Your own machines restore the whole vault with the recovery phrase. Every database comes back, and new ones appear automatically.
- Someone else, or an agent you don’t want to give everything to, joins a single database with an invite.
Walkthrough
# Machine A
botdb login # asks for a default remote, shows the phrase
botdb vault verify
botdb create movies && botdb use movies
botdb sql "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 "INSERT INTO watched (title, rating) VALUES ('Dune: Part Two', 5)"
# Machine B (same person)
botdb login --restore
botdb sql -d movies "SELECT title, rating FROM watched"
# Share one db with someone/another agent
botdb invite movies --read-only # on A
botdb join bdb1_... # on B
# agents
botdb skill install && botdb mcp install
Restoring your vault
botdb login --restore asks for your recovery phrase, then where your vault syncs: pick the same remote you chose on the first machine (botdb cloud, the same relay URL, or the same synced folder). Your botdb cloud account comes along with the vault, so nothing else to set up. It pulls the vault catalog and then every database in it, and prints what it restored.
The phrase derives the catalog’s id and keys, so botdb can find and decrypt the catalog on the remote. The catalog lists every database with its keys and remotes, and your default remotes. Databases you create later on either machine are added to the catalog and show up on the other after the next sync.
Pass everything up front to skip the prompts:
botdb login --restore --phrase-stdin --remote https://relay.example.com < phrase.txt
This stores the vault key in the keystore like a normal login. On servers where you’d rather not store it, set BOTDB_PHRASE and BOTDB_REMOTE instead and run botdb sync; see Using with agents.
Sharing a single database
botdb invite movies # read and write
botdb invite movies --read-only # read only
The invite (bdb1_...) contains the database’s keys and remotes. It’s a secret: anyone holding it can read the database. Send it over a channel you trust.
On the other side:
botdb join bdb1_... # optionally: --as films, --remote <url|path>
join works with or without a vault. Without one, the database is kept on that device only and added to the vault when they later run botdb login.
Read-only members can read and sync but can’t write. To remove a member later, run botdb rotate-key movies and re-invite the members you keep. See Sharing and invites.
Agents on each machine
botdb skill install # teaches your agents when and how to use botdb
botdb mcp install # registers the botdb MCP server with your agent clients
For containers and CI, set BOTDB_INVITE and botdb joins the database on first use. See Using with agents.