ScuttleBot

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

Keyboard Shortcuts

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