docs / guides
Sharing and invites
Share a single database with another person or agent, make it read-only, and remove members with key rotation.
Your own machines get every database through the vault. To give someone else, or an agent, access to one database, use an invite.
Create an invite
botdb invite movies # read and write
botdb invite movies --read-only # read only
The output is a single string starting with bdb1_. It contains:
- the database name and id,
- the database key, keys from earlier key epochs (so history stays readable), and the write key unless
--read-only, - the database’s remotes, so the other side knows where to sync.
On a terminal, the invite is printed alone on stdout with a note on stderr. As JSON: {"invite": "bdb1_...", "database": "movies", "read_only": true}. botdb warns if the database has no remote, since the invitee would have nothing to sync with. Members with read-only access can only create read-only invites.
Caution: An invite is a secret. Anyone who holds it can read the database. Share it over a channel you trust, and don’t paste it into logs, issues or prompts.
Join
botdb join bdb1_...
botdb join bdb1_... --as films # choose a local name
botdb join bdb1_... --remote https://relay.example.com
| Option | Description |
|---|---|
--as <name> |
Local name. Defaults to the invite’s name, with a short id suffix if it’s taken. |
--remote <url|path> |
Use these remotes instead of the invite’s. Repeatable. Useful when the invite’s remote isn’t reachable from this machine, such as a folder path on another computer. |
join downloads the database right away. If you have a vault, the database is added to it and follows you to your other machines. Without a vault, it’s kept in config.json (listed as not in vault) and added to the vault the next time you run botdb login.
Joining a database you already have upgrades its key if the invite is from a newer key epoch or grants write access, and adds the invite’s remotes.
For containers and CI, set BOTDB_INVITE=bdb1_... and botdb joins on first use. See Using with agents.
Read-only access
A read-only invite omits the write key. A read-only member can pull and decrypt everything, but:
- botdb refuses writes locally with
read_only(alsorevertandrotate-key); - relays only accept pushes signed with the write key, which the member doesn’t have.
Note: Read-only access is enforced end to end. Every change is signed with the write key, which read-only invites don’t contain, and every replica verifies the signature, whether it syncs through a relay or a shared folder.
Removing a member
There is no way to take a key back once shared. To remove someone:
botdb rotate-key movies
This starts a new key epoch:
- botdb generates a new database key and write key.
- Each remote switches to the new keys and drops data from older epochs. Relays then reject requests made with the old keys, so removed members get “rejected the request” errors.
- botdb re-uploads everything under the new key, with a fresh snapshot.
- Your own devices pick up the new key through the vault catalog automatically.
- Members you want to keep need a new invite:
botdb invite movies.
The removed member keeps whatever they had already synced. Rotation protects future changes, not past ones. Keys from older epochs are kept, so history from before the rotation stays readable on your devices.
With a shared folder, rotation stops removed members from reading new changes, but they can still write to the folder if they have access to it. Remove their access to the folder too.
Agents sharing a database
Several agents can share one database, each with its own invite. Every agent is a separate replica with its own local copy, and their writes merge with the usual conflict rules. Give agents read-only invites when they only need to look things up.