|
0adbd1e…
|
lmata
|
1 |
# Configuration |
|
0adbd1e…
|
lmata
|
2 |
|
|
0adbd1e…
|
lmata
|
3 |
scuttlebot is configured with a single YAML file, `scuttlebot.yaml`, in the working directory. Generate a starting file with: |
|
0adbd1e…
|
lmata
|
4 |
|
|
75f71d5…
|
lmata
|
5 |
 |
|
75f71d5…
|
lmata
|
6 |
|
|
0adbd1e…
|
lmata
|
7 |
```bash |
|
0adbd1e…
|
lmata
|
8 |
bin/scuttlectl setup |
|
0adbd1e…
|
lmata
|
9 |
``` |
|
0adbd1e…
|
lmata
|
10 |
|
|
0adbd1e…
|
lmata
|
11 |
Or copy `deploy/standalone/scuttlebot.yaml.example` and edit by hand. |
|
0adbd1e…
|
lmata
|
12 |
|
|
0adbd1e…
|
lmata
|
13 |
All fields are optional — the daemon applies defaults for anything that is missing. Call order: **defaults → YAML file → environment variables**. Environment variables always win. |
|
0adbd1e…
|
lmata
|
14 |
|
|
0adbd1e…
|
lmata
|
15 |
--- |
|
0adbd1e…
|
lmata
|
16 |
|
|
0adbd1e…
|
lmata
|
17 |
## Environment variable substitution |
|
0adbd1e…
|
lmata
|
18 |
|
|
0adbd1e…
|
lmata
|
19 |
String values in the YAML file support `${ENV_VAR}` substitution. This is the recommended way to keep secrets out of config files: |
|
0adbd1e…
|
lmata
|
20 |
|
|
0adbd1e…
|
lmata
|
21 |
```yaml |
|
0adbd1e…
|
lmata
|
22 |
llm: |
|
0adbd1e…
|
lmata
|
23 |
backends: |
|
0adbd1e…
|
lmata
|
24 |
- name: anthro |
|
0adbd1e…
|
lmata
|
25 |
backend: anthropic |
|
0adbd1e…
|
lmata
|
26 |
api_key: ${ORACLE_OPENAI_API_KEY} |
|
0adbd1e…
|
lmata
|
27 |
``` |
|
0adbd1e…
|
lmata
|
28 |
|
|
0adbd1e…
|
lmata
|
29 |
The variable is expanded at load time. If the variable is unset the empty string is used. |
|
0adbd1e…
|
lmata
|
30 |
|
|
0adbd1e…
|
lmata
|
31 |
--- |
|
0adbd1e…
|
lmata
|
32 |
|
|
0adbd1e…
|
lmata
|
33 |
## Top-level fields |
|
0adbd1e…
|
lmata
|
34 |
|
|
0adbd1e…
|
lmata
|
35 |
| Field | Type | Default | Description | |
|
0adbd1e…
|
lmata
|
36 |
|-------|------|---------|-------------| |
|
c669cc3…
|
lmata
|
37 |
| `api_addr` | string | `127.0.0.1:8080` | Listen address for scuttlebot's HTTP API and web UI. Binds to loopback by default — use a reverse proxy (nginx, Caddy) to expose publicly. Overridden by `SCUTTLEBOT_API_ADDR`. When `tls.domain` is set this is ignored — HTTPS runs on `:443` and HTTP on `:80`. | |
|
c669cc3…
|
lmata
|
38 |
| `mcp_addr` | string | `127.0.0.1:8081` | Listen address for the MCP server. Binds to loopback by default. Overridden by `SCUTTLEBOT_MCP_ADDR`. | |
|
0adbd1e…
|
lmata
|
39 |
|
|
0adbd1e…
|
lmata
|
40 |
--- |
|
0adbd1e…
|
lmata
|
41 |
|
|
0adbd1e…
|
lmata
|
42 |
## `ergo` |
|
0adbd1e…
|
lmata
|
43 |
|
|
0adbd1e…
|
lmata
|
44 |
Settings for the embedded Ergo IRC server. scuttlebot manages the ergo subprocess lifecycle by default. |
|
0adbd1e…
|
lmata
|
45 |
|
|
0adbd1e…
|
lmata
|
46 |
```yaml |
|
0adbd1e…
|
lmata
|
47 |
ergo: |
|
0adbd1e…
|
lmata
|
48 |
external: false |
|
0adbd1e…
|
lmata
|
49 |
binary_path: ergo |
|
0adbd1e…
|
lmata
|
50 |
data_dir: ./data/ergo |
|
0adbd1e…
|
lmata
|
51 |
network_name: scuttlebot |
|
0adbd1e…
|
lmata
|
52 |
server_name: irc.scuttlebot.local |
|
0adbd1e…
|
lmata
|
53 |
irc_addr: 127.0.0.1:6667 |
|
0adbd1e…
|
lmata
|
54 |
api_addr: 127.0.0.1:8089 |
|
0adbd1e…
|
lmata
|
55 |
api_token: "" |
|
0adbd1e…
|
lmata
|
56 |
history: |
|
0adbd1e…
|
lmata
|
57 |
enabled: false |
|
0adbd1e…
|
lmata
|
58 |
postgres_dsn: "" |
|
0adbd1e…
|
lmata
|
59 |
``` |
|
0adbd1e…
|
lmata
|
60 |
|
|
0adbd1e…
|
lmata
|
61 |
| Field | Type | Default | Description | |
|
0adbd1e…
|
lmata
|
62 |
|-------|------|---------|-------------| |
|
0adbd1e…
|
lmata
|
63 |
| `external` | bool | `false` | When `true`, scuttlebot does not manage ergo as a subprocess. Use in Docker/Kubernetes where ergo runs as a separate container. Overridden by `SCUTTLEBOT_ERGO_EXTERNAL=true`. | |
|
0adbd1e…
|
lmata
|
64 |
| `binary_path` | string | `ergo` | Path to the ergo binary. Resolved on PATH if not absolute. Ignored when `external: true`. scuttlebot auto-downloads ergo if the binary is not found. | |
|
0adbd1e…
|
lmata
|
65 |
| `data_dir` | string | `./data/ergo` | Directory where ergo stores `ircd.db` and its generated config. Ignored when `external: true`. | |
|
0adbd1e…
|
lmata
|
66 |
| `network_name` | string | `scuttlebot` | Human-readable IRC network name displayed in clients. Overridden by `SCUTTLEBOT_ERGO_NETWORK_NAME`. | |
|
0adbd1e…
|
lmata
|
67 |
| `server_name` | string | `irc.scuttlebot.local` | IRC server hostname (shown in `/whois` etc). Overridden by `SCUTTLEBOT_ERGO_SERVER_NAME`. | |
|
0adbd1e…
|
lmata
|
68 |
| `irc_addr` | string | `127.0.0.1:6667` | Address ergo listens for IRC connections. Loopback by default — agents connect here. Overridden by `SCUTTLEBOT_ERGO_IRC_ADDR`. | |
|
0adbd1e…
|
lmata
|
69 |
| `api_addr` | string | `127.0.0.1:8089` | Address of ergo's HTTP management API. loopback only by default. Overridden by `SCUTTLEBOT_ERGO_API_ADDR`. | |
|
0adbd1e…
|
lmata
|
70 |
| `api_token` | string | *(auto-generated)* | Bearer token for ergo's HTTP API. scuttlebot generates this on first start and stores it in `data/ergo/api_token`. Overridden by `SCUTTLEBOT_ERGO_API_TOKEN`. | |
|
c669cc3…
|
lmata
|
71 |
| `require_sasl` | bool | `false` | Require SASL authentication for all IRC connections. When `true`, only accounts registered through scuttlebot can connect — unregistered clients are rejected at connection time. Recommended for public deployments. | |
|
c669cc3…
|
lmata
|
72 |
| `default_channel_modes` | string | `+n` | Channel modes applied when a new channel is created. `+n` prevents external messages. Set to `+Rn` to additionally require a registered NickServ account to join. | |
|
0adbd1e…
|
lmata
|
73 |
|
|
0adbd1e…
|
lmata
|
74 |
### `ergo.history` |
|
0adbd1e…
|
lmata
|
75 |
|
|
0adbd1e…
|
lmata
|
76 |
Persistent message history is stored by ergo (separate from scribe's structured log). |
|
0adbd1e…
|
lmata
|
77 |
|
|
0adbd1e…
|
lmata
|
78 |
| Field | Type | Default | Description | |
|
0adbd1e…
|
lmata
|
79 |
|-------|------|---------|-------------| |
|
0adbd1e…
|
lmata
|
80 |
| `enabled` | bool | `false` | Enable persistent history in ergo. | |
|
0adbd1e…
|
lmata
|
81 |
| `postgres_dsn` | string | — | PostgreSQL connection string. Recommended when history is enabled. | |
|
0adbd1e…
|
lmata
|
82 |
| `mysql.host` | string | — | MySQL host. Used when `postgres_dsn` is empty. | |
|
0adbd1e…
|
lmata
|
83 |
| `mysql.port` | int | — | MySQL port. | |
|
0adbd1e…
|
lmata
|
84 |
| `mysql.user` | string | — | MySQL user. | |
|
0adbd1e…
|
lmata
|
85 |
| `mysql.password` | string | — | MySQL password. | |
|
0adbd1e…
|
lmata
|
86 |
| `mysql.database` | string | — | MySQL database name. | |
|
0adbd1e…
|
lmata
|
87 |
|
|
0adbd1e…
|
lmata
|
88 |
--- |
|
0adbd1e…
|
lmata
|
89 |
|
|
0adbd1e…
|
lmata
|
90 |
## `datastore` |
|
0adbd1e…
|
lmata
|
91 |
|
|
c669cc3…
|
lmata
|
92 |
scuttlebot's own persistent state store — agent registry, admin accounts, and policies. When configured, this supersedes the default JSON file storage in `data/`. |
|
0adbd1e…
|
lmata
|
93 |
|
|
0adbd1e…
|
lmata
|
94 |
```yaml |
|
0adbd1e…
|
lmata
|
95 |
datastore: |
|
0adbd1e…
|
lmata
|
96 |
driver: sqlite |
|
0adbd1e…
|
lmata
|
97 |
dsn: ./data/scuttlebot.db |
|
0adbd1e…
|
lmata
|
98 |
``` |
|
0adbd1e…
|
lmata
|
99 |
|
|
0adbd1e…
|
lmata
|
100 |
| Field | Type | Default | Description | |
|
0adbd1e…
|
lmata
|
101 |
|-------|------|---------|-------------| |
|
c669cc3…
|
lmata
|
102 |
| `driver` | string | — | `"sqlite"` or `"postgres"`. Leave empty to use JSON files (default). Overridden by `SCUTTLEBOT_DB_DRIVER`. | |
|
0adbd1e…
|
lmata
|
103 |
| `dsn` | string | `./data/scuttlebot.db` | Data source name. For SQLite: path to the `.db` file. For PostgreSQL: a standard `postgres://` connection string. Overridden by `SCUTTLEBOT_DB_DSN`. | |
|
c669cc3…
|
lmata
|
104 |
|
|
c669cc3…
|
lmata
|
105 |
When `driver` is unset (the default), state is stored as JSON files (`registry.json`, `admins.json`, `policies.json`) in the Ergo data directory. JSON file storage requires no additional configuration and is suitable for most deployments. Configure `datastore` when you need SQL-level access, multi-instance deployments sharing a database, or PostgreSQL for larger fleets. |
|
0adbd1e…
|
lmata
|
106 |
|
|
0adbd1e…
|
lmata
|
107 |
--- |
|
0adbd1e…
|
lmata
|
108 |
|
|
0adbd1e…
|
lmata
|
109 |
## `bridge` |
|
0adbd1e…
|
lmata
|
110 |
|
|
0adbd1e…
|
lmata
|
111 |
The bridge bot connects to IRC and powers the web chat UI and REST channel API. |
|
0adbd1e…
|
lmata
|
112 |
|
|
0adbd1e…
|
lmata
|
113 |
```yaml |
|
0adbd1e…
|
lmata
|
114 |
bridge: |
|
0adbd1e…
|
lmata
|
115 |
enabled: true |
|
0adbd1e…
|
lmata
|
116 |
nick: bridge |
|
0adbd1e…
|
lmata
|
117 |
channels: |
|
0adbd1e…
|
lmata
|
118 |
- "#general" |
|
0adbd1e…
|
lmata
|
119 |
buffer_size: 200 |
|
0adbd1e…
|
lmata
|
120 |
web_user_ttl_minutes: 5 |
|
0adbd1e…
|
lmata
|
121 |
``` |
|
0adbd1e…
|
lmata
|
122 |
|
|
0adbd1e…
|
lmata
|
123 |
| Field | Type | Default | Description | |
|
0adbd1e…
|
lmata
|
124 |
|-------|------|---------|-------------| |
|
0adbd1e…
|
lmata
|
125 |
| `enabled` | bool | `true` | Whether to start the bridge bot. Disabling it also disables the web UI channel view. | |
|
0adbd1e…
|
lmata
|
126 |
| `nick` | string | `bridge` | IRC nick for the bridge bot. | |
|
0adbd1e…
|
lmata
|
127 |
| `password` | string | *(auto-generated)* | SASL passphrase for the bridge's NickServ account. Auto-generated on first start if blank. | |
|
0adbd1e…
|
lmata
|
128 |
| `channels` | []string | `["#general"]` | Channels the bridge joins on startup. These become the channels accessible via the REST API and web UI. | |
|
0adbd1e…
|
lmata
|
129 |
| `buffer_size` | int | `200` | Number of messages to keep per channel in the in-memory ring buffer. | |
|
0adbd1e…
|
lmata
|
130 |
| `web_user_ttl_minutes` | int | `5` | How many minutes an HTTP-bridge sender nick remains visible in the channel user list after their last post. | |
|
0adbd1e…
|
lmata
|
131 |
|
|
0adbd1e…
|
lmata
|
132 |
--- |
|
0adbd1e…
|
lmata
|
133 |
|
|
0adbd1e…
|
lmata
|
134 |
## `tls` |
|
0adbd1e…
|
lmata
|
135 |
|
|
0adbd1e…
|
lmata
|
136 |
Automatic HTTPS via Let's Encrypt. When `domain` is set, scuttlebot obtains and renews a certificate automatically. |
|
0adbd1e…
|
lmata
|
137 |
|
|
0adbd1e…
|
lmata
|
138 |
```yaml |
|
0adbd1e…
|
lmata
|
139 |
tls: |
|
0adbd1e…
|
lmata
|
140 |
domain: scuttlebot.example.com |
|
0adbd1e…
|
lmata
|
141 |
email: [email protected] |
|
0adbd1e…
|
lmata
|
142 |
cert_dir: "" |
|
0adbd1e…
|
lmata
|
143 |
allow_insecure: true |
|
0adbd1e…
|
lmata
|
144 |
``` |
|
0adbd1e…
|
lmata
|
145 |
|
|
0adbd1e…
|
lmata
|
146 |
| Field | Type | Default | Description | |
|
0adbd1e…
|
lmata
|
147 |
|-------|------|---------|-------------| |
|
0adbd1e…
|
lmata
|
148 |
| `domain` | string | *(empty — TLS disabled)* | Domain name for the Let's Encrypt certificate. Setting this enables HTTPS on `:443`. | |
|
0adbd1e…
|
lmata
|
149 |
| `email` | string | — | Email address for Let's Encrypt expiry notifications. | |
|
0adbd1e…
|
lmata
|
150 |
| `cert_dir` | string | `{ergo.data_dir}/certs` | Directory to cache the certificate. | |
|
0adbd1e…
|
lmata
|
151 |
| `allow_insecure` | bool | `true` | Keep HTTP running on `:80` alongside HTTPS. The ACME HTTP-01 challenge always runs on `:80` regardless of this setting. | |
|
0adbd1e…
|
lmata
|
152 |
|
|
0adbd1e…
|
lmata
|
153 |
!!! note "Local dev" |
|
c669cc3…
|
lmata
|
154 |
Leave `tls.domain` empty for local development. The HTTP API on `127.0.0.1:8080` is used instead. |
|
0adbd1e…
|
lmata
|
155 |
|
|
0adbd1e…
|
lmata
|
156 |
--- |
|
0adbd1e…
|
lmata
|
157 |
|
|
0adbd1e…
|
lmata
|
158 |
## `llm` |
|
0adbd1e…
|
lmata
|
159 |
|
|
0adbd1e…
|
lmata
|
160 |
Configures the LLM gateway used by oracle, sentinel, and steward. Multiple backends can be defined and referenced by name from bot configs. |
|
0adbd1e…
|
lmata
|
161 |
|
|
0adbd1e…
|
lmata
|
162 |
```yaml |
|
0adbd1e…
|
lmata
|
163 |
llm: |
|
0adbd1e…
|
lmata
|
164 |
backends: |
|
0adbd1e…
|
lmata
|
165 |
- name: anthro |
|
0adbd1e…
|
lmata
|
166 |
backend: anthropic |
|
a729d7a…
|
lmata
|
167 |
api_key: ${ANTHROPIC_API_KEY} |
|
0adbd1e…
|
lmata
|
168 |
model: claude-haiku-4-5-20251001 |
|
0adbd1e…
|
lmata
|
169 |
default: true |
|
0adbd1e…
|
lmata
|
170 |
|
|
0adbd1e…
|
lmata
|
171 |
- name: gemini |
|
0adbd1e…
|
lmata
|
172 |
backend: gemini |
|
0adbd1e…
|
lmata
|
173 |
api_key: ${GEMINI_API_KEY} |
|
0adbd1e…
|
lmata
|
174 |
model: gemini-2.5-flash |
|
0adbd1e…
|
lmata
|
175 |
|
|
0adbd1e…
|
lmata
|
176 |
- name: local |
|
0adbd1e…
|
lmata
|
177 |
backend: ollama |
|
0adbd1e…
|
lmata
|
178 |
base_url: http://localhost:11434 |
|
0adbd1e…
|
lmata
|
179 |
model: devstral:latest |
|
0adbd1e…
|
lmata
|
180 |
``` |
|
0adbd1e…
|
lmata
|
181 |
|
|
0adbd1e…
|
lmata
|
182 |
### `llm.backends[]` |
|
0adbd1e…
|
lmata
|
183 |
|
|
0adbd1e…
|
lmata
|
184 |
Each entry in `backends` defines one LLM backend instance. |
|
0adbd1e…
|
lmata
|
185 |
|
|
0adbd1e…
|
lmata
|
186 |
| Field | Type | Default | Description | |
|
0adbd1e…
|
lmata
|
187 |
|-------|------|---------|-------------| |
|
0adbd1e…
|
lmata
|
188 |
| `name` | string | required | Unique identifier. Used to reference this backend from bot configs (e.g. `oracle.default_backend: anthro`). | |
|
0adbd1e…
|
lmata
|
189 |
| `backend` | string | required | Provider type. See table below. | |
|
0adbd1e…
|
lmata
|
190 |
| `api_key` | string | — | API key for cloud providers. Use `${ENV_VAR}` syntax. | |
|
0adbd1e…
|
lmata
|
191 |
| `base_url` | string | *(provider default)* | Override the base URL. Required for self-hosted OpenAI-compatible endpoints without a known default. | |
|
0adbd1e…
|
lmata
|
192 |
| `model` | string | *(first available)* | Default model ID. If empty, the first model passing the allow/block filters is used. | |
|
0adbd1e…
|
lmata
|
193 |
| `region` | string | `us-east-1` | AWS region. Bedrock only. | |
|
0adbd1e…
|
lmata
|
194 |
| `aws_key_id` | string | *(from env/role)* | AWS access key ID. Bedrock only. Leave empty to use instance role or `AWS_*` env vars. | |
|
0adbd1e…
|
lmata
|
195 |
| `aws_secret_key` | string | *(from env/role)* | AWS secret access key. Bedrock only. | |
|
0adbd1e…
|
lmata
|
196 |
| `allow` | []string | — | Regex patterns. Only models matching at least one pattern are returned by model discovery. | |
|
0adbd1e…
|
lmata
|
197 |
| `block` | []string | — | Regex patterns. Models matching any pattern are excluded from model discovery. | |
|
0adbd1e…
|
lmata
|
198 |
| `default` | bool | `false` | Mark as the default backend when no backend is specified in a bot config. Only one backend should be default. | |
|
0adbd1e…
|
lmata
|
199 |
|
|
0adbd1e…
|
lmata
|
200 |
### Supported backend types |
|
0adbd1e…
|
lmata
|
201 |
|
|
0adbd1e…
|
lmata
|
202 |
| `backend` value | Provider | |
|
0adbd1e…
|
lmata
|
203 |
|-----------------|----------| |
|
0adbd1e…
|
lmata
|
204 |
| `anthropic` | Anthropic Claude API | |
|
0adbd1e…
|
lmata
|
205 |
| `gemini` | Google Gemini API | |
|
0adbd1e…
|
lmata
|
206 |
| `openai` | OpenAI API | |
|
0adbd1e…
|
lmata
|
207 |
| `bedrock` | AWS Bedrock | |
|
0adbd1e…
|
lmata
|
208 |
| `ollama` | Ollama (local) | |
|
0adbd1e…
|
lmata
|
209 |
| `openrouter` | OpenRouter proxy | |
|
0adbd1e…
|
lmata
|
210 |
| `groq` | Groq | |
|
0adbd1e…
|
lmata
|
211 |
| `together` | Together AI | |
|
0adbd1e…
|
lmata
|
212 |
| `fireworks` | Fireworks AI | |
|
0adbd1e…
|
lmata
|
213 |
| `mistral` | Mistral AI | |
|
0adbd1e…
|
lmata
|
214 |
| `deepseek` | DeepSeek | |
|
0adbd1e…
|
lmata
|
215 |
| `xai` | xAI Grok | |
|
0adbd1e…
|
lmata
|
216 |
| `cerebras` | Cerebras | |
|
0adbd1e…
|
lmata
|
217 |
| `litellm` | LiteLLM proxy | |
|
0adbd1e…
|
lmata
|
218 |
| `lmstudio` | LM Studio | |
|
0adbd1e…
|
lmata
|
219 |
| `vllm` | vLLM | |
|
0adbd1e…
|
lmata
|
220 |
| `localai` | LocalAI | |
|
0adbd1e…
|
lmata
|
221 |
|
|
0adbd1e…
|
lmata
|
222 |
--- |
|
0adbd1e…
|
lmata
|
223 |
|
|
0adbd1e…
|
lmata
|
224 |
## `bots` |
|
0adbd1e…
|
lmata
|
225 |
|
|
0adbd1e…
|
lmata
|
226 |
Individual bot configurations are nested under `bots`. Bots not listed here still run with defaults. |
|
0adbd1e…
|
lmata
|
227 |
|
|
0adbd1e…
|
lmata
|
228 |
```yaml |
|
0adbd1e…
|
lmata
|
229 |
bots: |
|
0adbd1e…
|
lmata
|
230 |
oracle: |
|
0adbd1e…
|
lmata
|
231 |
enabled: true |
|
0adbd1e…
|
lmata
|
232 |
default_backend: anthro |
|
0adbd1e…
|
lmata
|
233 |
|
|
0adbd1e…
|
lmata
|
234 |
sentinel: |
|
0adbd1e…
|
lmata
|
235 |
enabled: true |
|
0adbd1e…
|
lmata
|
236 |
backend: anthro |
|
0adbd1e…
|
lmata
|
237 |
channel: "#general" |
|
0adbd1e…
|
lmata
|
238 |
mod_channel: "#moderation" |
|
0adbd1e…
|
lmata
|
239 |
policy: "Flag harassment, spam, and coordinated manipulation." |
|
0adbd1e…
|
lmata
|
240 |
min_severity: medium |
|
0adbd1e…
|
lmata
|
241 |
|
|
0adbd1e…
|
lmata
|
242 |
steward: |
|
0adbd1e…
|
lmata
|
243 |
enabled: true |
|
0adbd1e…
|
lmata
|
244 |
backend: anthro |
|
0adbd1e…
|
lmata
|
245 |
channel: "#general" |
|
0adbd1e…
|
lmata
|
246 |
mod_channel: "#moderation" |
|
0adbd1e…
|
lmata
|
247 |
|
|
0adbd1e…
|
lmata
|
248 |
scribe: |
|
0adbd1e…
|
lmata
|
249 |
enabled: true |
|
0adbd1e…
|
lmata
|
250 |
|
|
0adbd1e…
|
lmata
|
251 |
warden: |
|
0adbd1e…
|
lmata
|
252 |
enabled: true |
|
0adbd1e…
|
lmata
|
253 |
|
|
0adbd1e…
|
lmata
|
254 |
scroll: |
|
0adbd1e…
|
lmata
|
255 |
enabled: true |
|
0adbd1e…
|
lmata
|
256 |
|
|
0adbd1e…
|
lmata
|
257 |
herald: |
|
0adbd1e…
|
lmata
|
258 |
enabled: true |
|
0adbd1e…
|
lmata
|
259 |
|
|
0adbd1e…
|
lmata
|
260 |
snitch: |
|
0adbd1e…
|
lmata
|
261 |
enabled: true |
|
0adbd1e…
|
lmata
|
262 |
alert_channel: "#ops" |
|
0adbd1e…
|
lmata
|
263 |
``` |
|
0adbd1e…
|
lmata
|
264 |
|
|
0adbd1e…
|
lmata
|
265 |
See [Built-in Bots](../guide/bots.md) for the full field reference for each bot. |
|
0adbd1e…
|
lmata
|
266 |
|
|
0adbd1e…
|
lmata
|
267 |
--- |
|
0adbd1e…
|
lmata
|
268 |
|
|
0adbd1e…
|
lmata
|
269 |
## Environment variable overrides |
|
0adbd1e…
|
lmata
|
270 |
|
|
0adbd1e…
|
lmata
|
271 |
These environment variables take precedence over the YAML file for the fields they cover: |
|
0adbd1e…
|
lmata
|
272 |
|
|
0adbd1e…
|
lmata
|
273 |
| Variable | Field overridden | |
|
0adbd1e…
|
lmata
|
274 |
|----------|-----------------| |
|
0adbd1e…
|
lmata
|
275 |
| `SCUTTLEBOT_API_ADDR` | `api_addr` | |
|
0adbd1e…
|
lmata
|
276 |
| `SCUTTLEBOT_MCP_ADDR` | `mcp_addr` | |
|
0adbd1e…
|
lmata
|
277 |
| `SCUTTLEBOT_DB_DRIVER` | `datastore.driver` | |
|
0adbd1e…
|
lmata
|
278 |
| `SCUTTLEBOT_DB_DSN` | `datastore.dsn` | |
|
0adbd1e…
|
lmata
|
279 |
| `SCUTTLEBOT_ERGO_EXTERNAL` | `ergo.external` (set to `true` or `1`) | |
|
0adbd1e…
|
lmata
|
280 |
| `SCUTTLEBOT_ERGO_API_ADDR` | `ergo.api_addr` | |
|
0adbd1e…
|
lmata
|
281 |
| `SCUTTLEBOT_ERGO_API_TOKEN` | `ergo.api_token` | |
|
0adbd1e…
|
lmata
|
282 |
| `SCUTTLEBOT_ERGO_IRC_ADDR` | `ergo.irc_addr` | |
|
0adbd1e…
|
lmata
|
283 |
| `SCUTTLEBOT_ERGO_NETWORK_NAME` | `ergo.network_name` | |
|
0adbd1e…
|
lmata
|
284 |
| `SCUTTLEBOT_ERGO_SERVER_NAME` | `ergo.server_name` | |
|
0adbd1e…
|
lmata
|
285 |
|
|
0adbd1e…
|
lmata
|
286 |
In addition, `${ENV_VAR}` placeholders in any YAML string value are expanded at load time. |
|
0adbd1e…
|
lmata
|
287 |
|
|
974ed6a…
|
lmata
|
288 |
--- |
|
0adbd1e…
|
lmata
|
289 |
|
|
0adbd1e…
|
lmata
|
290 |
## Complete annotated example |
|
0adbd1e…
|
lmata
|
291 |
|
|
0adbd1e…
|
lmata
|
292 |
```yaml |
|
0adbd1e…
|
lmata
|
293 |
# scuttlebot.yaml |
|
0adbd1e…
|
lmata
|
294 |
|
|
0adbd1e…
|
lmata
|
295 |
# HTTP API and web UI |
|
c669cc3…
|
lmata
|
296 |
api_addr: 127.0.0.1:8080 |
|
0adbd1e…
|
lmata
|
297 |
|
|
0adbd1e…
|
lmata
|
298 |
# MCP server |
|
c669cc3…
|
lmata
|
299 |
mcp_addr: 127.0.0.1:8081 |
|
0adbd1e…
|
lmata
|
300 |
|
|
0adbd1e…
|
lmata
|
301 |
ergo: |
|
0adbd1e…
|
lmata
|
302 |
# Manage ergo as a subprocess (default). |
|
0adbd1e…
|
lmata
|
303 |
# Set external: true if ergo runs separately (Docker, etc.) |
|
0adbd1e…
|
lmata
|
304 |
external: false |
|
0adbd1e…
|
lmata
|
305 |
network_name: myfleet |
|
0adbd1e…
|
lmata
|
306 |
server_name: irc.myfleet.internal |
|
c669cc3…
|
lmata
|
307 |
irc_addr: 127.0.0.1:6667 # set to :6667 or :6697 to expose IRC publicly |
|
c669cc3…
|
lmata
|
308 |
api_addr: 127.0.0.1:8089 # keep on loopback — no auth layer on this port |
|
0adbd1e…
|
lmata
|
309 |
# api_token is auto-generated on first start |
|
c669cc3…
|
lmata
|
310 |
|
|
c669cc3…
|
lmata
|
311 |
# Security (recommended for public deployments): |
|
c669cc3…
|
lmata
|
312 |
require_sasl: false # set to true to reject unauthenticated IRC connections |
|
c669cc3…
|
lmata
|
313 |
default_channel_modes: "+n" # set to "+Rn" to restrict joins to registered nicks |
|
0adbd1e…
|
lmata
|
314 |
|
|
0adbd1e…
|
lmata
|
315 |
# Optional: persistent IRC history in PostgreSQL |
|
0adbd1e…
|
lmata
|
316 |
history: |
|
0adbd1e…
|
lmata
|
317 |
enabled: true |
|
0adbd1e…
|
lmata
|
318 |
postgres_dsn: postgres://scuttlebot:secret@localhost/scuttlebot?sslmode=disable |
|
0adbd1e…
|
lmata
|
319 |
|
|
0adbd1e…
|
lmata
|
320 |
datastore: |
|
0adbd1e…
|
lmata
|
321 |
driver: sqlite |
|
0adbd1e…
|
lmata
|
322 |
dsn: ./data/scuttlebot.db |
|
0adbd1e…
|
lmata
|
323 |
|
|
0adbd1e…
|
lmata
|
324 |
bridge: |
|
0adbd1e…
|
lmata
|
325 |
enabled: true |
|
0adbd1e…
|
lmata
|
326 |
nick: bridge |
|
0adbd1e…
|
lmata
|
327 |
channels: |
|
0adbd1e…
|
lmata
|
328 |
- "#general" |
|
0adbd1e…
|
lmata
|
329 |
- "#fleet" |
|
0adbd1e…
|
lmata
|
330 |
- "#ops" |
|
0adbd1e…
|
lmata
|
331 |
buffer_size: 500 |
|
0adbd1e…
|
lmata
|
332 |
web_user_ttl_minutes: 10 |
|
0adbd1e…
|
lmata
|
333 |
|
|
0adbd1e…
|
lmata
|
334 |
# TLS — comment out for local dev |
|
0adbd1e…
|
lmata
|
335 |
# tls: |
|
0adbd1e…
|
lmata
|
336 |
# domain: scuttlebot.example.com |
|
0adbd1e…
|
lmata
|
337 |
# email: [email protected] |
|
0adbd1e…
|
lmata
|
338 |
|
|
0adbd1e…
|
lmata
|
339 |
llm: |
|
0adbd1e…
|
lmata
|
340 |
backends: |
|
0adbd1e…
|
lmata
|
341 |
- name: anthro |
|
0adbd1e…
|
lmata
|
342 |
backend: anthropic |
|
0adbd1e…
|
lmata
|
343 |
api_key: ${ANTHROPIC_API_KEY} |
|
0adbd1e…
|
lmata
|
344 |
model: claude-haiku-4-5-20251001 |
|
0adbd1e…
|
lmata
|
345 |
default: true |
|
0adbd1e…
|
lmata
|
346 |
|
|
0adbd1e…
|
lmata
|
347 |
- name: gemini |
|
0adbd1e…
|
lmata
|
348 |
backend: gemini |
|
0adbd1e…
|
lmata
|
349 |
api_key: ${GEMINI_API_KEY} |
|
0adbd1e…
|
lmata
|
350 |
model: gemini-2.5-flash |
|
0adbd1e…
|
lmata
|
351 |
|
|
0adbd1e…
|
lmata
|
352 |
- name: local |
|
0adbd1e…
|
lmata
|
353 |
backend: ollama |
|
0adbd1e…
|
lmata
|
354 |
base_url: http://localhost:11434 |
|
0adbd1e…
|
lmata
|
355 |
model: devstral:latest |
|
0adbd1e…
|
lmata
|
356 |
|
|
0adbd1e…
|
lmata
|
357 |
bots: |
|
0adbd1e…
|
lmata
|
358 |
oracle: |
|
0adbd1e…
|
lmata
|
359 |
enabled: true |
|
0adbd1e…
|
lmata
|
360 |
default_backend: anthro |
|
0adbd1e…
|
lmata
|
361 |
|
|
0adbd1e…
|
lmata
|
362 |
sentinel: |
|
0adbd1e…
|
lmata
|
363 |
enabled: true |
|
0adbd1e…
|
lmata
|
364 |
backend: anthro |
|
0adbd1e…
|
lmata
|
365 |
channel: "#general" |
|
0adbd1e…
|
lmata
|
366 |
mod_channel: "#moderation" |
|
0adbd1e…
|
lmata
|
367 |
policy: | |
|
0adbd1e…
|
lmata
|
368 |
Flag: harassment, hate speech, spam, coordinated manipulation, |
|
0adbd1e…
|
lmata
|
369 |
attempts to exfiltrate credentials or secrets. |
|
0adbd1e…
|
lmata
|
370 |
window_size: 20 |
|
0adbd1e…
|
lmata
|
371 |
window_age: 5m |
|
0adbd1e…
|
lmata
|
372 |
cooldown_per_nick: 10m |
|
0adbd1e…
|
lmata
|
373 |
min_severity: medium |
|
0adbd1e…
|
lmata
|
374 |
|
|
0adbd1e…
|
lmata
|
375 |
steward: |
|
0adbd1e…
|
lmata
|
376 |
enabled: true |
|
0adbd1e…
|
lmata
|
377 |
backend: anthro |
|
0adbd1e…
|
lmata
|
378 |
channel: "#general" |
|
0adbd1e…
|
lmata
|
379 |
mod_channel: "#moderation" |
|
0adbd1e…
|
lmata
|
380 |
|
|
0adbd1e…
|
lmata
|
381 |
scribe: |
|
0adbd1e…
|
lmata
|
382 |
enabled: true |
|
0adbd1e…
|
lmata
|
383 |
|
|
0adbd1e…
|
lmata
|
384 |
warden: |
|
0adbd1e…
|
lmata
|
385 |
enabled: true |
|
0adbd1e…
|
lmata
|
386 |
|
|
0adbd1e…
|
lmata
|
387 |
scroll: |
|
0adbd1e…
|
lmata
|
388 |
enabled: true |
|
974ed6a…
|
lmata
|
389 |
|
|
0adbd1e…
|
lmata
|
390 |
herald: |
|
0adbd1e…
|
lmata
|
391 |
enabled: true |
|
974ed6a…
|
lmata
|
392 |
|
|
0adbd1e…
|
lmata
|
393 |
snitch: |
|
0adbd1e…
|
lmata
|
394 |
enabled: true |
|
0adbd1e…
|
lmata
|
395 |
alert_channel: "#ops" |
|
0adbd1e…
|
lmata
|
396 |
``` |