Or copy `deploy/standalone/scuttlebot.yaml.example` and edit by hand.
12
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.
14
15
---
16
17
## Environment variable substitution
18
19
String values in the YAML file support `${ENV_VAR}` substitution. This is the recommended way to keep secrets out of config files:
20
21
```yaml
22
llm:
23
backends:
24
- name: anthro
25
backend: anthropic
26
api_key: ${ORACLE_OPENAI_API_KEY}
27
```
28
29
The variable is expanded at load time. If the variable is unset the empty string is used.
30
31
---
32
33
## Top-level fields
34
35
| Field | Type | Default | Description |
36
|-------|------|---------|-------------|
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`. |
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`. |
39
40
---
41
42
## `ergo`
43
44
Settings for the embedded Ergo IRC server. scuttlebot manages the ergo subprocess lifecycle by default.
45
46
```yaml
47
ergo:
48
external: false
49
binary_path: ergo
50
data_dir: ./data/ergo
51
network_name: scuttlebot
52
server_name: irc.scuttlebot.local
53
irc_addr: 127.0.0.1:6667
54
api_addr: 127.0.0.1:8089
55
api_token: ""
56
history:
57
enabled: false
58
postgres_dsn: ""
59
```
60
61
| Field | Type | Default | Description |
62
|-------|------|---------|-------------|
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`. |
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. |
65
| `data_dir` | string | `./data/ergo` | Directory where ergo stores `ircd.db` and its generated config. Ignored when `external: true`. |
66
| `network_name` | string | `scuttlebot` | Human-readable IRC network name displayed in clients. Overridden by `SCUTTLEBOT_ERGO_NETWORK_NAME`. |
67
| `server_name` | string | `irc.scuttlebot.local` | IRC server hostname (shown in `/whois` etc). Overridden by `SCUTTLEBOT_ERGO_SERVER_NAME`. |
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`. |
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`. |
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`. |
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. |
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. |
73
74
### `ergo.history`
75
76
Persistent message history is stored by ergo (separate from scribe's structured log).
77
78
| Field | Type | Default | Description |
79
|-------|------|---------|-------------|
80
| `enabled` | bool | `false` | Enable persistent history in ergo. |
81
| `postgres_dsn` | string | — | PostgreSQL connection string. Recommended when history is enabled. |
82
| `mysql.host` | string | — | MySQL host. Used when `postgres_dsn` is empty. |
83
| `mysql.port` | int | — | MySQL port. |
84
| `mysql.user` | string | — | MySQL user. |
85
| `mysql.password` | string | — | MySQL password. |
scuttlebot's own persistent state store — agent registry, admin accounts, and policies. When configured, this supersedes the default JSON file storage in `data/`.
93
94
```yaml
95
datastore:
96
driver: sqlite
97
dsn: ./data/scuttlebot.db
98
```
99
100
| Field | Type | Default | Description |
101
|-------|------|---------|-------------|
102
| `driver` | string | — | `"sqlite"` or `"postgres"`. Leave empty to use JSON files (default). Overridden by `SCUTTLEBOT_DB_DRIVER`. |
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`. |
104
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.
106
107
---
108
109
## `bridge`
110
111
The bridge bot connects to IRC and powers the web chat UI and REST channel API.
112
113
```yaml
114
bridge:
115
enabled: true
116
nick: bridge
117
channels:
118
- "#general"
119
buffer_size: 200
120
web_user_ttl_minutes: 5
121
```
122
123
| Field | Type | Default | Description |
124
|-------|------|---------|-------------|
125
| `enabled` | bool | `true` | Whether to start the bridge bot. Disabling it also disables the web UI channel view. |
126
| `nick` | string | `bridge` | IRC nick for the bridge bot. |
127
| `password` | string | *(auto-generated)* | SASL passphrase for the bridge's NickServ account. Auto-generated on first start if blank. |
128
| `channels` | []string | `["#general"]` | Channels the bridge joins on startup. These become the channels accessible via the REST API and web UI. |
129
| `buffer_size` | int | `200` | Number of messages to keep per channel in the in-memory ring buffer. |
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. |
131
132
---
133
134
## `tls`
135
136
Automatic HTTPS via Let's Encrypt. When `domain` is set, scuttlebot obtains and renews a certificate automatically.