ScuttleBot

docs: fill config schema reference with full field tables and YAML skeleton

lmata 2026-04-01 17:21 trunk
Commit ac4fa8d9702ebd978ed7aa9b3591dc90c0daa27439467c810554e5fbd68c8042
Parent 0273aeeb493eedb…
1 file changed +213 -3
~ docs/reference/config.md
M docs/reference/config.md
+213 -3
--- docs/reference/config.md
+++ docs/reference/config.md
@@ -1,6 +1,216 @@
1
+# Config Schema
2
+
3
+Quick-reference for all `scuttlebot.yaml` fields. For narrative explanation and examples see [Configuration](../getting-started/configuration.md).
4
+
5
+---
6
+
7
+## Top-level
8
+
9
+| Field | Type | Default | Env override |
10
+|-------|------|---------|--------------|
11
+| `api_addr` | string | `:8080` | `SCUTTLEBOT_API_ADDR` |
12
+| `mcp_addr` | string | `:8081` | `SCUTTLEBOT_MCP_ADDR` |
13
+
14
+---
15
+
16
+## `ergo`
17
+
18
+| Field | Type | Default | Env override |
19
+|-------|------|---------|--------------|
20
+| `external` | bool | `false` | `SCUTTLEBOT_ERGO_EXTERNAL` |
21
+| `binary_path` | string | `ergo` | — |
22
+| `data_dir` | string | `./data/ergo` | — |
23
+| `network_name` | string | `scuttlebot` | `SCUTTLEBOT_ERGO_NETWORK_NAME` |
24
+| `server_name` | string | `irc.scuttlebot.local` | `SCUTTLEBOT_ERGO_SERVER_NAME` |
25
+| `irc_addr` | string | `127.0.0.1:6667` | `SCUTTLEBOT_ERGO_IRC_ADDR` |
26
+| `api_addr` | string | `127.0.0.1:8089` | `SCUTTLEBOT_ERGO_API_ADDR` |
27
+| `api_token` | string | *(auto-generated)* | `SCUTTLEBOT_ERGO_API_TOKEN` |
28
+| `tls_domain` | string | — | — |
29
+
30
+### `ergo.history`
31
+
32
+| Field | Type | Default |
33
+|-------|------|---------|
34
+| `enabled` | bool | `false` |
35
+| `postgres_dsn` | string | — |
36
+| `mysql.host` | string | — |
37
+| `mysql.port` | int | — |
38
+| `mysql.user` | string | — |
39
+| `mysql.password` | string | — |
40
+| `mysql.database` | string | — |
41
+
42
+---
43
+
44
+## `bridge`
45
+
46
+| Field | Type | Default |
47
+|-------|------|---------|
48
+| `enabled` | bool | `true` |
49
+| `nick` | string | `bridge` |
50
+| `password` | string | *(auto-generated)* |
51
+| `channels` | []string | `["#general"]` |
52
+| `buffer_size` | int | `200` |
53
+| `web_user_ttl_minutes` | int | `5` |
54
+
55
+---
56
+
57
+## `tls`
58
+
59
+| Field | Type | Default |
60
+|-------|------|---------|
61
+| `domain` | string | *(empty — TLS disabled)* |
62
+| `email` | string | — |
63
+| `cert_dir` | string | `{ergo.data_dir}/certs` |
64
+| `allow_insecure` | bool | `true` |
65
+
66
+---
67
+
68
+## `llm.backends[]`
69
+
70
+| Field | Type | Default |
71
+|-------|------|---------|
72
+| `name` | string | required |
73
+| `backend` | string | required |
74
+| `api_key` | string | — |
75
+| `base_url` | string | *(provider default)* |
76
+| `model` | string | *(first available)* |
77
+| `region` | string | `us-east-1` *(Bedrock only)* |
78
+| `aws_key_id` | string | *(from env/role)* |
79
+| `aws_secret_key` | string | *(from env/role)* |
80
+| `allow` | []string | — |
81
+| `block` | []string | — |
82
+| `default` | bool | `false` |
83
+
84
+**Supported `backend` values:** `anthropic`, `gemini`, `openai`, `bedrock`, `ollama`, `openrouter`, `groq`, `together`, `fireworks`, `mistral`, `deepseek`, `xai`, `cerebras`, `litellm`, `lmstudio`, `vllm`, `localai`
85
+
86
+---
87
+
88
+## `bots`
89
+
90
+### `bots.oracle`
91
+
92
+| Field | Type | Default |
93
+|-------|------|---------|
94
+| `enabled` | bool | `false` |
95
+| `default_backend` | string | *(first default backend)* |
96
+
97
+### `bots.scribe`
98
+
99
+| Field | Type | Default |
100
+|-------|------|---------|
101
+| `enabled` | bool | `true` |
102
+| `log_dir` | string | `data/logs/scribe` |
103
+
104
+### `bots.sentinel`
105
+
106
+| Field | Type | Default |
107
+|-------|------|---------|
108
+| `enabled` | bool | `false` |
109
+| `backend` | string | *(default backend)* |
110
+| `channel` | string | `#general` |
111
+| `mod_channel` | string | `#moderation` |
112
+| `policy` | string | *(built-in policy)* |
113
+| `window_size` | int | `20` |
114
+| `window_age` | duration | `5m` |
115
+| `cooldown_per_nick` | duration | `10m` |
116
+| `min_severity` | string | `medium` |
117
+
118
+### `bots.steward`
119
+
120
+| Field | Type | Default |
121
+|-------|------|---------|
122
+| `enabled` | bool | `false` |
123
+| `backend` | string | *(default backend)* |
124
+| `channel` | string | `#general` |
125
+| `mod_channel` | string | `#moderation` |
126
+
127
+### `bots.warden`
128
+
129
+| Field | Type | Default |
130
+|-------|------|---------|
131
+| `enabled` | bool | `true` |
132
+| `max_joins_per_minute` | int | `10` |
133
+| `max_messages_per_minute` | int | `60` |
134
+
135
+### `bots.herald`
136
+
137
+| Field | Type | Default |
138
+|-------|------|---------|
139
+| `enabled` | bool | `false` |
140
+| `channel` | string | `#alerts` |
141
+
142
+### `bots.scroll`
143
+
144
+| Field | Type | Default |
145
+|-------|------|---------|
146
+| `enabled` | bool | `true` |
147
+| `max_lines` | int | `50` |
148
+| `rate_limit` | int | `3` *(requests/min)* |
149
+
150
+### `bots.snitch`
151
+
152
+| Field | Type | Default |
153
+|-------|------|---------|
154
+| `enabled` | bool | `false` |
155
+| `alert_channel` | string | `#ops` |
156
+
1157
 ---
2
-# config
158
+
159
+## Full skeleton
160
+
161
+```yaml
162
+api_addr: :8080
163
+mcp_addr: :8081
164
+
165
+ergo:
166
+ external: false
167
+ binary_path: ergo
168
+ data_dir: ./data/ergo
169
+ network_name: scuttlebot
170
+ server_name: irc.scuttlebot.local
171
+ irc_addr: 127.0.0.1:6667
172
+ api_addr: 127.0.0.1:8089
173
+ tls_domain: "" # set to enable Let's Encrypt on the IRC port
174
+ history:
175
+ enabled: false
176
+ postgres_dsn: ""
177
+
178
+bridge:
179
+ enabled: true
180
+ nick: bridge
181
+ channels:
182
+ - "#general"
183
+ buffer_size: 200
184
+ web_user_ttl_minutes: 5
185
+
186
+tls:
187
+ domain: "" # set to enable Let's Encrypt on the HTTP API
188
+ email: ""
189
+ allow_insecure: true
3190
4
-!!! note
5
- This page is a work in progress.
191
+llm:
192
+ backends:
193
+ - name: anthro
194
+ backend: anthropic
195
+ api_key: ${ANTHROPIC_API_KEY}
196
+ model: claude-haiku-4-5-20251001
197
+ default: true
6198
199
+bots:
200
+ oracle:
201
+ enabled: false
202
+ scribe:
203
+ enabled: true
204
+ sentinel:
205
+ enabled: false
206
+ steward:
207
+ enabled: false
208
+ warden:
209
+ enabled: true
210
+ herald:
211
+ enabled: false
212
+ scroll:
213
+ enabled: true
214
+ snitch:
215
+ enabled: false
216
+```
7217
--- docs/reference/config.md
+++ docs/reference/config.md
@@ -1,6 +1,216 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1 ---
2 # config
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3
4 !!! note
5 This page is a work in progress.
 
 
 
 
 
6
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7
--- docs/reference/config.md
+++ docs/reference/config.md
@@ -1,6 +1,216 @@
1 # Config Schema
2
3 Quick-reference for all `scuttlebot.yaml` fields. For narrative explanation and examples see [Configuration](../getting-started/configuration.md).
4
5 ---
6
7 ## Top-level
8
9 | Field | Type | Default | Env override |
10 |-------|------|---------|--------------|
11 | `api_addr` | string | `:8080` | `SCUTTLEBOT_API_ADDR` |
12 | `mcp_addr` | string | `:8081` | `SCUTTLEBOT_MCP_ADDR` |
13
14 ---
15
16 ## `ergo`
17
18 | Field | Type | Default | Env override |
19 |-------|------|---------|--------------|
20 | `external` | bool | `false` | `SCUTTLEBOT_ERGO_EXTERNAL` |
21 | `binary_path` | string | `ergo` | — |
22 | `data_dir` | string | `./data/ergo` | — |
23 | `network_name` | string | `scuttlebot` | `SCUTTLEBOT_ERGO_NETWORK_NAME` |
24 | `server_name` | string | `irc.scuttlebot.local` | `SCUTTLEBOT_ERGO_SERVER_NAME` |
25 | `irc_addr` | string | `127.0.0.1:6667` | `SCUTTLEBOT_ERGO_IRC_ADDR` |
26 | `api_addr` | string | `127.0.0.1:8089` | `SCUTTLEBOT_ERGO_API_ADDR` |
27 | `api_token` | string | *(auto-generated)* | `SCUTTLEBOT_ERGO_API_TOKEN` |
28 | `tls_domain` | string | — | — |
29
30 ### `ergo.history`
31
32 | Field | Type | Default |
33 |-------|------|---------|
34 | `enabled` | bool | `false` |
35 | `postgres_dsn` | string | — |
36 | `mysql.host` | string | — |
37 | `mysql.port` | int | — |
38 | `mysql.user` | string | — |
39 | `mysql.password` | string | — |
40 | `mysql.database` | string | — |
41
42 ---
43
44 ## `bridge`
45
46 | Field | Type | Default |
47 |-------|------|---------|
48 | `enabled` | bool | `true` |
49 | `nick` | string | `bridge` |
50 | `password` | string | *(auto-generated)* |
51 | `channels` | []string | `["#general"]` |
52 | `buffer_size` | int | `200` |
53 | `web_user_ttl_minutes` | int | `5` |
54
55 ---
56
57 ## `tls`
58
59 | Field | Type | Default |
60 |-------|------|---------|
61 | `domain` | string | *(empty — TLS disabled)* |
62 | `email` | string | — |
63 | `cert_dir` | string | `{ergo.data_dir}/certs` |
64 | `allow_insecure` | bool | `true` |
65
66 ---
67
68 ## `llm.backends[]`
69
70 | Field | Type | Default |
71 |-------|------|---------|
72 | `name` | string | required |
73 | `backend` | string | required |
74 | `api_key` | string | — |
75 | `base_url` | string | *(provider default)* |
76 | `model` | string | *(first available)* |
77 | `region` | string | `us-east-1` *(Bedrock only)* |
78 | `aws_key_id` | string | *(from env/role)* |
79 | `aws_secret_key` | string | *(from env/role)* |
80 | `allow` | []string | — |
81 | `block` | []string | — |
82 | `default` | bool | `false` |
83
84 **Supported `backend` values:** `anthropic`, `gemini`, `openai`, `bedrock`, `ollama`, `openrouter`, `groq`, `together`, `fireworks`, `mistral`, `deepseek`, `xai`, `cerebras`, `litellm`, `lmstudio`, `vllm`, `localai`
85
86 ---
87
88 ## `bots`
89
90 ### `bots.oracle`
91
92 | Field | Type | Default |
93 |-------|------|---------|
94 | `enabled` | bool | `false` |
95 | `default_backend` | string | *(first default backend)* |
96
97 ### `bots.scribe`
98
99 | Field | Type | Default |
100 |-------|------|---------|
101 | `enabled` | bool | `true` |
102 | `log_dir` | string | `data/logs/scribe` |
103
104 ### `bots.sentinel`
105
106 | Field | Type | Default |
107 |-------|------|---------|
108 | `enabled` | bool | `false` |
109 | `backend` | string | *(default backend)* |
110 | `channel` | string | `#general` |
111 | `mod_channel` | string | `#moderation` |
112 | `policy` | string | *(built-in policy)* |
113 | `window_size` | int | `20` |
114 | `window_age` | duration | `5m` |
115 | `cooldown_per_nick` | duration | `10m` |
116 | `min_severity` | string | `medium` |
117
118 ### `bots.steward`
119
120 | Field | Type | Default |
121 |-------|------|---------|
122 | `enabled` | bool | `false` |
123 | `backend` | string | *(default backend)* |
124 | `channel` | string | `#general` |
125 | `mod_channel` | string | `#moderation` |
126
127 ### `bots.warden`
128
129 | Field | Type | Default |
130 |-------|------|---------|
131 | `enabled` | bool | `true` |
132 | `max_joins_per_minute` | int | `10` |
133 | `max_messages_per_minute` | int | `60` |
134
135 ### `bots.herald`
136
137 | Field | Type | Default |
138 |-------|------|---------|
139 | `enabled` | bool | `false` |
140 | `channel` | string | `#alerts` |
141
142 ### `bots.scroll`
143
144 | Field | Type | Default |
145 |-------|------|---------|
146 | `enabled` | bool | `true` |
147 | `max_lines` | int | `50` |
148 | `rate_limit` | int | `3` *(requests/min)* |
149
150 ### `bots.snitch`
151
152 | Field | Type | Default |
153 |-------|------|---------|
154 | `enabled` | bool | `false` |
155 | `alert_channel` | string | `#ops` |
156
157 ---
158
159 ## Full skeleton
160
161 ```yaml
162 api_addr: :8080
163 mcp_addr: :8081
164
165 ergo:
166 external: false
167 binary_path: ergo
168 data_dir: ./data/ergo
169 network_name: scuttlebot
170 server_name: irc.scuttlebot.local
171 irc_addr: 127.0.0.1:6667
172 api_addr: 127.0.0.1:8089
173 tls_domain: "" # set to enable Let's Encrypt on the IRC port
174 history:
175 enabled: false
176 postgres_dsn: ""
177
178 bridge:
179 enabled: true
180 nick: bridge
181 channels:
182 - "#general"
183 buffer_size: 200
184 web_user_ttl_minutes: 5
185
186 tls:
187 domain: "" # set to enable Let's Encrypt on the HTTP API
188 email: ""
189 allow_insecure: true
190
191 llm:
192 backends:
193 - name: anthro
194 backend: anthropic
195 api_key: ${ANTHROPIC_API_KEY}
196 model: claude-haiku-4-5-20251001
197 default: true
198
199 bots:
200 oracle:
201 enabled: false
202 scribe:
203 enabled: true
204 sentinel:
205 enabled: false
206 steward:
207 enabled: false
208 warden:
209 enabled: true
210 herald:
211 enabled: false
212 scroll:
213 enabled: true
214 snitch:
215 enabled: false
216 ```
217

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button