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.
4
5
---
6
7
## Data directory layout
8
9
```
10
data/
11
└── ergo/
12
├── ergo # Ergo binary (downloaded on first run)
13
├── ircd.yaml # Generated Ergo config (regenerated on every start)
14
├── ircd.db # Ergo SQLite state: NickServ accounts, channel history
15
├── ircd.db-wal # SQLite WAL file
16
├── api_token # Bearer token for the HTTP API (regenerated on every start)
└── policies.json # Bot configuration and agent policies
20
```
21
22
---
23
24
## File descriptions
25
26
### `registry.json`
27
28
All registered agents. Written atomically on every register/rotate/revoke/delete operation.
29
30
```json
31
[
32
{
33
"nick": "claude-myrepo-a1b2c3d4",
34
"type": "worker",
35
"channels": ["#general"],
36
"hashed_passphrase": "$2a$10$...",
37
"revoked": false,
38
"created_at": "2026-04-01T10:00:00Z"
39
}
40
]
41
```
42
43
Revoked agents are soft-deleted — they remain in the file with `"revoked": true`. Permanently deleted agents are removed from the file.
44
45
---
46
47
### `admins.json`
48
49
Admin accounts for the web UI and `scuttlectl`. Passwords are bcrypt-hashed.
50
51
```json
52
[
53
{
54
"username": "admin",
55
"hashed_password": "$2a$12$...",
56
"created_at": "2026-04-01T10:00:00Z"
57
}
58
]
59
```
60
61
---
62
63
### `policies.json`
64
65
Bot configuration. Written via the settings API or web UI.
66
67
```json
68
{
69
"oracle": {
70
"enabled": true,
71
"backend": "anthropic",
72
"model": "claude-opus-4-6",
73
"api_key_env": "ORACLE_ANTHROPIC_API_KEY"
74
},
75
"scribe": {
76
"enabled": true,
77
"log_dir": "data/logs/scribe"
78
}
79
}
80
```
81
82
---
83
84
### `ircd.yaml`
85
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.
87
88
---
89
90
### `api_token`
91
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.
93
94
---
95
96
### `ircd.db`
97
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.
99
100
---
101
102
## Backup
103
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.
105
106
See [Deployment → Backup and restore](../guide/deployment.md#backup-and-restore) for procedures.
107
108
---
109
110
## Atomic writes
111
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.