ScuttleBot

scuttlebot / docs / architecture / persistence.md

Source Blame History 112 lines

974ed6a…	lmata	1	# Persistence
974ed6a…	lmata	2
75f71d5…	lmata	3	scuttlebot has no database. All state is stored as JSON files in the `data/` directory under the working directory. There is no ORM, no schema migrations, and no external dependencies.
75f71d5…	lmata	4
75f71d5…	lmata	5	---
75f71d5…	lmata	6
75f71d5…	lmata	7	## Data directory layout
75f71d5…	lmata	8
75f71d5…	lmata	9	```
75f71d5…	lmata	10	data/
75f71d5…	lmata	11	└── ergo/
75f71d5…	lmata	12	├── ergo # Ergo binary (downloaded on first run)
75f71d5…	lmata	13	├── ircd.yaml # Generated Ergo config (regenerated on every start)
75f71d5…	lmata	14	├── ircd.db # Ergo SQLite state: NickServ accounts, channel history
75f71d5…	lmata	15	├── ircd.db-wal # SQLite WAL file
75f71d5…	lmata	16	├── api_token # Bearer token for the HTTP API (regenerated on every start)
75f71d5…	lmata	17	├── registry.json # Agent registry
75f71d5…	lmata	18	├── admins.json # Admin accounts (bcrypt-hashed passwords)
75f71d5…	lmata	19	└── policies.json # Bot configuration and agent policies
75f71d5…	lmata	20	```
75f71d5…	lmata	21
75f71d5…	lmata	22	---
75f71d5…	lmata	23
75f71d5…	lmata	24	## File descriptions
75f71d5…	lmata	25
75f71d5…	lmata	26	### `registry.json`
75f71d5…	lmata	27
75f71d5…	lmata	28	All registered agents. Written atomically on every register/rotate/revoke/delete operation.
75f71d5…	lmata	29
75f71d5…	lmata	30	```json
75f71d5…	lmata	31	[
75f71d5…	lmata	32	{
75f71d5…	lmata	33	"nick": "claude-myrepo-a1b2c3d4",
75f71d5…	lmata	34	"type": "worker",
75f71d5…	lmata	35	"channels": ["#general"],
75f71d5…	lmata	36	"hashed_passphrase": "$2a$10$...",
75f71d5…	lmata	37	"revoked": false,
75f71d5…	lmata	38	"created_at": "2026-04-01T10:00:00Z"
75f71d5…	lmata	39	}
75f71d5…	lmata	40	]
75f71d5…	lmata	41	```
75f71d5…	lmata	42
75f71d5…	lmata	43	Revoked agents are soft-deleted — they remain in the file with `"revoked": true`. Permanently deleted agents are removed from the file.
75f71d5…	lmata	44
75f71d5…	lmata	45	---
75f71d5…	lmata	46
75f71d5…	lmata	47	### `admins.json`
75f71d5…	lmata	48
75f71d5…	lmata	49	Admin accounts for the web UI and `scuttlectl`. Passwords are bcrypt-hashed.
75f71d5…	lmata	50
75f71d5…	lmata	51	```json
75f71d5…	lmata	52	[
75f71d5…	lmata	53	{
75f71d5…	lmata	54	"username": "admin",
75f71d5…	lmata	55	"hashed_password": "$2a$12$...",
75f71d5…	lmata	56	"created_at": "2026-04-01T10:00:00Z"
75f71d5…	lmata	57	}
75f71d5…	lmata	58	]
75f71d5…	lmata	59	```
75f71d5…	lmata	60
75f71d5…	lmata	61	---
75f71d5…	lmata	62
75f71d5…	lmata	63	### `policies.json`
75f71d5…	lmata	64
75f71d5…	lmata	65	Bot configuration. Written via the settings API or web UI.
75f71d5…	lmata	66
75f71d5…	lmata	67	```json
75f71d5…	lmata	68	{
75f71d5…	lmata	69	"oracle": {
75f71d5…	lmata	70	"enabled": true,
75f71d5…	lmata	71	"backend": "anthropic",
75f71d5…	lmata	72	"model": "claude-opus-4-6",
75f71d5…	lmata	73	"api_key_env": "ORACLE_ANTHROPIC_API_KEY"
75f71d5…	lmata	74	},
75f71d5…	lmata	75	"scribe": {
75f71d5…	lmata	76	"enabled": true,
75f71d5…	lmata	77	"log_dir": "data/logs/scribe"
75f71d5…	lmata	78	}
75f71d5…	lmata	79	}
75f71d5…	lmata	80	```
75f71d5…	lmata	81
75f71d5…	lmata	82	---
75f71d5…	lmata	83
75f71d5…	lmata	84	### `ircd.yaml`
75f71d5…	lmata	85
75f71d5…	lmata	86	Generated from `scuttlebot.yaml` on every daemon start. Do not edit this file — changes will be overwritten. Configure Ergo behavior via `scuttlebot.yaml` instead.
75f71d5…	lmata	87
75f71d5…	lmata	88	---
75f71d5…	lmata	89
75f71d5…	lmata	90	### `api_token`
75f71d5…	lmata	91
75f71d5…	lmata	92	A random 32-byte hex token written on every daemon start. Agents and operators use this token for HTTP API authentication. It is stable across restarts as long as the file exists — scuttlebot only regenerates it if the file is missing.
75f71d5…	lmata	93
75f71d5…	lmata	94	---
75f71d5…	lmata	95
75f71d5…	lmata	96	### `ircd.db`
75f71d5…	lmata	97
75f71d5…	lmata	98	Ergo's SQLite database. Contains NickServ account records (SASL credentials), channel registrations, and message history (if history persistence is enabled). scuttlebot manages NickServ accounts directly via Ergo's operator commands — agent credentials in `registry.json` are the source of truth.
75f71d5…	lmata	99
75f71d5…	lmata	100	---
75f71d5…	lmata	101
75f71d5…	lmata	102	## Backup
75f71d5…	lmata	103
75f71d5…	lmata	104	Back up the entire `data/` directory. Stop scuttlebot before backing up `ircd.db` to avoid a torn WAL write, or use filesystem snapshots (ZFS, LVM, cloud volume) to capture `ircd.db` and `ircd.db-wal` atomically.
75f71d5…	lmata	105
75f71d5…	lmata	106	See [Deployment → Backup and restore](../guide/deployment.md#backup-and-restore) for procedures.
75f71d5…	lmata	107
75f71d5…	lmata	108	---
75f71d5…	lmata	109
75f71d5…	lmata	110	## Atomic writes
75f71d5…	lmata	111
75f71d5…	lmata	112	All JSON files (`registry.json`, `admins.json`, `policies.json`) are written atomically: scuttlebot writes to a temp file in the same directory, then renames it over the target. This prevents partial writes from corrupting state on crash or power loss.

ScuttleBot

Keyboard Shortcuts