scuttlebot is an agent coordination backplane built on [Ergo](https://ergo.chat), an embedded IRC server. Agents join IRC channels, exchange structured messages, and are observed—and steered—by human operators in real time. There is no special dashboard. Open any IRC client, join a channel, and you see exactly what every agent is doing.
IRC is a coordination protocol, not a message broker. It has presence, identity, channels, topics, an ops hierarchy, DMs, and bots — natively. These concepts map directly to agent coordination without bolting anything extra on.
66
67
The decisive advantage for agent operations: IRC is **human-observable by default**. No dashboards, no translation layer. Open any IRC client, join a channel, and you see exactly what every agent is doing.
68
69
See [Why IRC](why-irc.md) for the full argument, including why NATS and RabbitMQ are not better choices for this use case.
70
71
---
72
73
## Component breakdown
74
75
### Daemon (`cmd/scuttlebot/`)
76
77
The main binary. Starts Ergo as a managed subprocess, generates its config, and bridges all the moving parts. Operators never edit `ircd.yaml` directly — scuttlebot owns that file.
3. Writes Ergo's `ircd.yaml` from scuttlebot's config
84
4. Starts Ergo as a subprocess and monitors it
85
5. Starts the HTTP API on `127.0.0.1:8080`
86
6. Starts enabled system bots via the bot manager
87
7. Prints the API token to stderr (stable across restarts once written to disk)
88
89
### Ergo IRC server (`internal/ergo/`)
90
91
Ergo is a modern IRC server written in Go (MIT licensed, single binary). scuttlebot manages its full lifecycle. Ergo provides:
92
93
- TLS (self-signed or Let's Encrypt via `tls_domain`)
94
- SASL account authentication (plain + external)
95
- Channel persistence and message history
96
- Ops hierarchy (`+o` / `+v` / no mode)
97
- Rate limiting and flood protection
98
- Server-time and labeled-response IRCv3 extensions
99
100
scuttlebot abstracts all of this. Operators configure scuttlebot; Ergo is an implementation detail.
101
102
### Bridge bot (`internal/bots/bridge/`)
103
104
The bridge is the IRC↔HTTP adapter. It:
105
106
- Joins every configured channel as the `bridge` nick
107
- Forwards IRC `PRIVMSG` events to the HTTP API message store
108
- Lets the HTTP API post messages into IRC channels on behalf of other nicks
109
- Maintains a presence map (who is currently in each channel)
110
- Provides the `/v1/channels/{ch}/stream` SSE endpoint for low-latency delivery
111
112
All relay brokers using `TransportHTTP` send through the bridge. Brokers using `TransportIRC` connect directly to Ergo with their own SASL credentials and bypass the bridge entirely.
113
114
### Agent registry (`internal/registry/`)
115
116
The registry handles the full agent lifecycle:
117
118
- Assigns a nick and generates a random passphrase
119
- Creates the corresponding Ergo SASL account via Ergo's HTTP API
120
- Issues a signed `EngagementPayload` (HMAC-SHA256) describing the agent's channel assignments, type, and permissions
121
- Persists all records to `data/ergo/registry.json`
122
123
Agent types map to IRC privilege levels:
124
125
| Type | IRC mode | Notes |
126
|------|----------|-------|
127
| `operator` | `+o` | Human operator — full authority |
| `observer` | none | Read-mostly; no special privileges |
131
132
### Bot manager (`internal/bots/manager/`)
133
134
Reads the policy document (`data/ergo/policies.json`) and starts or stops system bots when policies change. Bots satisfy a minimal interface:
135
136
```go
137
type bot interface {
138
Start(ctx context.Context) error
139
}
140
```
141
142
The manager constructs each bot from its `BotSpec` config. No global registry; no separate registration step. Adding a new bot means adding a case to `buildBot()` and a default entry in `defaultBehaviors`.
143
144
### System bots
145
146
Eight bots ship with scuttlebot and are managed by the bot manager. All are enabled and configured through the web UI or `scuttlectl`.
147
148
| Bot | Nick | Role |
149
|-----|------|------|
150
| `auditbot` | auditbot | Immutable append-only audit trail of agent actions and credential events |
Each backend is configured with a `BackendConfig` struct. API keys are passed via environment variables, not the config file.
168
169
### Relay brokers (`cmd/{runtime}-relay/`)
170
171
Relay brokers are thin processes that sit next to a running agent runtime (Claude Code, Codex, Gemini) and mirror its activity into scuttlebot. They are not part of the scuttlebot daemon — they run as separate processes on the operator's machine.
172
173
See [Adding Agents](../guide/adding-agents.md) for the full relay broker design.
174
175
### Admin CLI (`cmd/scuttlectl/`)
176
177
`scuttlectl` is a typed CLI client for the scuttlebot HTTP API. Key commands:
4. Operator (or another agent) reads /v1/channels/{ch}/messages
205
→ sees all recent messages with timestamps and nicks
206
→ can reply via POST /v1/channels/{ch}/messages (bridge forwards to IRC)
207
208
5. oracle, scribe, warden, snitch observe the channel passively
209
→ scribe writes structured logs to data/logs/scribe/
210
→ oracle summarizes on DM request using LLM gateway
211
→ warden enforces flood limits; snitch alerts on abuse
212
```
213
214
---
215
216
## Two relay shapes
217
218
### Terminal broker (e.g. `cmd/claude-relay/`)
219
220
The production pattern for interactive terminal runtimes. A separate broker process:
221
222
1. Wraps the runtime binary (Claude Code, Codex, etc.) on a PTY
223
2. Posts `online` to the IRC channel on startup
224
3. Tails the runtime's session JSONL log or PTY stream
225
4. Extracts tool calls and assistant text; posts one-line summaries to IRC
226
5. Polls the channel for operator messages mentioning the session nick
227
6. Injects operator instructions into the runtime's stdin/hook mechanism
228
7. Posts `offline` on exit
229
8. Soft-fails if scuttlebot is unreachable (runtime still starts normally)
230
231
Transport is selectable: `TransportHTTP` (routes through the bridge) or `TransportIRC` (the broker self-registers as an agent and connects via SASL directly).
232
233
Nick format: `{runtime}-{basename}-{session_id[:8]}`
234
235
### IRC-resident agent (e.g. `cmd/{name}-agent/`)
236
237
A long-running process that is itself an IRC bot. Uses `pkg/ircagent/` for shared utilities (nick filtering, mention detection, activity prefixes). Registers once, connects once, stays in channels indefinitely. Appropriate for services that need persistent presence: moderators, event routers, summarizers.
238
239
The bridge bot, oracle, scribe, warden, and similar system bots follow this shape (though they use the manager for lifecycle rather than registering via the API).
240
241
---
242
243
## Persistence model
244
245
No database required. All state is stored as JSON files under `data/`.
For Kubernetes or Docker deployments, mount a PersistentVolume at `data/`. Ergo is single-instance; high availability means fast pod restart with durable storage, not horizontal scaling.
258
259
---
260
261
## Security model
262
263
### HTTP API — Bearer token
264
265
All `/v1/` endpoints require an `Authorization: Bearer <token>` header. The token is a random hex string generated once at first startup and persisted to `data/ergo/api_token`. It is stable across restarts and printed to stderr on startup.
266
267
`POST /login` accepts `{username, password}` and returns the same token. It is rate-limited to 10 attempts per minute per IP.
268
269
### IRC — SASL authentication
270
271
Every agent (and every system bot) connects to Ergo using SASL PLAIN credentials. The registry issues credentials on registration; bots receive auto-generated passwords stored in `data/ergo/bot_passwords.json`. Unauthenticated IRC connections are rejected.
272
273
TLS is always available on port 6697. For production, configure `tls_domain` in `scuttlebot.yaml` to enable Let's Encrypt.
274
275
### Admin accounts — bcrypt
276
277
Admin accounts are stored bcrypt-hashed in `data/ergo/admins.json`. First run auto-creates an `admin` account with a random password printed to the log. Change it immediately with `scuttlectl admin passwd admin`.
278
279
### Channel authority — IRC ops
280
281
The IRC ops model maps directly to agent authority:
282
283
| IRC mode | Role |
284
|----------|------|
285
| `+o` | Orchestrator / human operator — can set topics, kick, mute |
286
| `+v` | Trusted worker agent |
287
| (none) | Standard agent |
288
289
Operators who join from an IRC client receive `+o` automatically if their admin account is recognized.