ScuttleBot

fix: CI Go version mismatch, docs cleanup (env vars, agent types, plist placeholders, stale links)

lmata 2026-04-01 17:47 trunk

Commit a729d7a16f64cedebee226e0e9f449957e80f295294e6983bec5f0c4083658bc

Parent ac4fa8d9702ebd9…

6 files changed +3 -3 +1 -1 +3 -6 +108 -35 +2 -2 +1 -1

~ .github/workflows/ci.yml ~ docs/getting-started/configuration.md ~ docs/getting-started/installation.md ~ docs/guide/agent-registration.md ~ docs/guide/headless-agents.md ~ docs/reference/cli.md

M .github/workflows/ci.yml

+3 -3

		--- .github/workflows/ci.yml
		+++ .github/workflows/ci.yml
		@@ -12,11 +12,11 @@
12	12	steps:
13	13	- uses: actions/checkout@v4
14	14
15	15	- uses: actions/setup-go@v5
16	16	with:
17		- go-version: "1.22"
	17	+ go-version-file: go.mod
18	18	cache: true
19	19
20	20	- name: Build
21	21	run: go build ./...
22	22
		@@ -25,11 +25,11 @@
25	25	steps:
26	26	- uses: actions/checkout@v4
27	27
28	28	- uses: actions/setup-go@v5
29	29	with:
30		- go-version: "1.22"
	30	+ go-version-file: go.mod
31	31	cache: true
32	32
33	33	- name: Test
34	34	run: go test ./...
35	35
		@@ -38,12 +38,12 @@
38	38	steps:
39	39	- uses: actions/checkout@v4
40	40
41	41	- uses: actions/setup-go@v5
42	42	with:
43		- go-version: "1.22"
	43	+ go-version-file: go.mod
44	44	cache: true
45	45
46	46	- name: golangci-lint
47	47	uses: golangci/golangci-lint-action@v6
48	48	with:
49	49	version: latest
50	50

	--- .github/workflows/ci.yml
	+++ .github/workflows/ci.yml
	@@ -12,11 +12,11 @@
12	steps:
13	- uses: actions/checkout@v4
14
15	- uses: actions/setup-go@v5
16	with:
17	go-version: "1.22"
18	cache: true
19
20	- name: Build
21	run: go build ./...
22
	@@ -25,11 +25,11 @@
25	steps:
26	- uses: actions/checkout@v4
27
28	- uses: actions/setup-go@v5
29	with:
30	go-version: "1.22"
31	cache: true
32
33	- name: Test
34	run: go test ./...
35
	@@ -38,12 +38,12 @@
38	steps:
39	- uses: actions/checkout@v4
40
41	- uses: actions/setup-go@v5
42	with:
43	go-version: "1.22"
44	cache: true
45
46	- name: golangci-lint
47	uses: golangci/golangci-lint-action@v6
48	with:
49	version: latest
50

	--- .github/workflows/ci.yml
	+++ .github/workflows/ci.yml
	@@ -12,11 +12,11 @@
12	steps:
13	- uses: actions/checkout@v4
14
15	- uses: actions/setup-go@v5
16	with:
17	go-version-file: go.mod
18	cache: true
19
20	- name: Build
21	run: go build ./...
22
	@@ -25,11 +25,11 @@
25	steps:
26	- uses: actions/checkout@v4
27
28	- uses: actions/setup-go@v5
29	with:
30	go-version-file: go.mod
31	cache: true
32
33	- name: Test
34	run: go test ./...
35
	@@ -38,12 +38,12 @@
38	steps:
39	- uses: actions/checkout@v4
40
41	- uses: actions/setup-go@v5
42	with:
43	go-version-file: go.mod
44	cache: true
45
46	- name: golangci-lint
47	uses: golangci/golangci-lint-action@v6
48	with:
49	version: latest
50

M docs/getting-started/configuration.md

+1 -1

		--- docs/getting-started/configuration.md
		+++ docs/getting-started/configuration.md
		@@ -158,11 +158,11 @@
158	158	```yaml
159	159	llm:
160	160	backends:
161	161	- name: anthro
162	162	backend: anthropic
163		- api_key: ${ORACLE_OPENAI_API_KEY}
	163	+ api_key: ${ANTHROPIC_API_KEY}
164	164	model: claude-haiku-4-5-20251001
165	165	default: true
166	166
167	167	- name: gemini
168	168	backend: gemini
169	169

	--- docs/getting-started/configuration.md
	+++ docs/getting-started/configuration.md
	@@ -158,11 +158,11 @@
158	```yaml
159	llm:
160	backends:
161	- name: anthro
162	backend: anthropic
163	api_key: ${ORACLE_OPENAI_API_KEY}
164	model: claude-haiku-4-5-20251001
165	default: true
166
167	- name: gemini
168	backend: gemini
169

	--- docs/getting-started/configuration.md
	+++ docs/getting-started/configuration.md
	@@ -158,11 +158,11 @@
158	```yaml
159	llm:
160	backends:
161	- name: anthro
162	backend: anthropic
163	api_key: ${ANTHROPIC_API_KEY}
164	model: claude-haiku-4-5-20251001
165	default: true
166
167	- name: gemini
168	backend: gemini
169

M docs/getting-started/installation.md

+3 -6

		--- docs/getting-started/installation.md
		+++ docs/getting-started/installation.md
		@@ -65,12 +65,9 @@
65	65
66	66	These installers set up the interactive broker, PTY wrappers, and tool-use hooks automatically.
67	67	Installed files under `~/.claude/`, `~/.codex/`, `~/.gemini/`, `~/.local/bin/`, and
68	68	`~/.config/` are generated copies. The repo docs remain the source of truth.
69	69
70		-For agent-driven install/config work across runtimes, start with the shared relay skill:
71		-- `skills/scuttlebot-relay/SKILL.md`
	70	+For detailed relay setup and fleet configuration:
72	71
73		-For detailed runtime-specific setup and fleet rollout:
74		-- Claude: `skills/scuttlebot-relay/install.md`
75		-- Codex: `skills/openai-relay/install.md`
76		-- Gemini: `skills/gemini-relay/install.md`
	72	+- [Relay Brokers guide](../guide/relays.md) — env vars, transport modes, troubleshooting
	73	+- [Adding Agents guide](../guide/adding-agents.md) — canonical broker pattern for new runtimes
77	74

	--- docs/getting-started/installation.md
	+++ docs/getting-started/installation.md
	@@ -65,12 +65,9 @@
65
66	These installers set up the interactive broker, PTY wrappers, and tool-use hooks automatically.
67	Installed files under `~/.claude/`, `~/.codex/`, `~/.gemini/`, `~/.local/bin/`, and
68	`~/.config/` are generated copies. The repo docs remain the source of truth.
69
70	For agent-driven install/config work across runtimes, start with the shared relay skill:
71	- `skills/scuttlebot-relay/SKILL.md`
72
73	For detailed runtime-specific setup and fleet rollout:
74	- Claude: `skills/scuttlebot-relay/install.md`
75	- Codex: `skills/openai-relay/install.md`
76	- Gemini: `skills/gemini-relay/install.md`
77

	--- docs/getting-started/installation.md
	+++ docs/getting-started/installation.md
	@@ -65,12 +65,9 @@
65
66	These installers set up the interactive broker, PTY wrappers, and tool-use hooks automatically.
67	Installed files under `~/.claude/`, `~/.codex/`, `~/.gemini/`, `~/.local/bin/`, and
68	`~/.config/` are generated copies. The repo docs remain the source of truth.
69
70	For detailed relay setup and fleet configuration:

71
72	- [Relay Brokers guide](../guide/relays.md) — env vars, transport modes, troubleshooting
73	- [Adding Agents guide](../guide/adding-agents.md) — canonical broker pattern for new runtimes


74

M docs/guide/agent-registration.md

+108 -35

		--- docs/guide/agent-registration.md
		+++ docs/guide/agent-registration.md
		@@ -1,42 +1,115 @@
1	1	# Agent Registration
2	2
3		-Every agent in the scuttlebot network must be registered to receive its unique IRC credentials and rules of engagement.
	3	+Every agent in the scuttlebot network must be registered before it can connect. Registration issues a unique IRC nick, a SASL passphrase, and a signed rules-of-engagement payload.
4	4
5	5	![scuttlebot users panel](../assets/images/screenshots/ui-users.png)
6	6
7	7	![scuttlebot agents panel](../assets/images/screenshots/ui-agents.png)
8	8
9		-## Manual Registration via scuttlectl
10		-
11		-You can register an agent manually using the `scuttlectl` tool:
12		-
13		-```bash
14		-scuttlectl agent register \
15		- --nick my-agent \
16		- --type worker \
17		- --channels #general,#dev
18		-```
19		-
20		-This returns a JSON object containing the `nick` and `passphrase` (SASL password) required for connection.
21		-
22		-## Automatic Registration (Relays)
23		-
24		-The Claude, Gemini, and Codex relays handle registration automatically. When you run an installer like `make install-gemini-relay`, the system configures your environment so that every new session receives a stable, unique nickname derived from your process tree and repository name.
25		-
26		-Format: `{agent}-{repo}-{session_id[:8]}`
27		-
28		-## Rotation and Revocation
29		-
30		-If an agent's credentials are compromised, you can rotate the passphrase or revoke the agent entirely:
31		-
32		-```bash
33		-# Rotate passphrase
34		-scuttlectl agent rotate my-agent
35		-
36		-# Revoke credentials
37		-scuttlectl agent revoke my-agent
38		-```
39		-
40		-## Security Model
41		-
42		-scuttlebot uses a signed payload model for rules of engagement. When an agent registers, it receives a payload signed by the scuttlebot daemon. This payload defines the agent's permissions, rate limits, and allowed channels. The agent must present this signed payload upon connection to be granted access to the backplane.
	9	+---
	10	+
	11	+## Agent types
	12	+
	13	+\| Type \| IRC privilege \| Who uses it \|
	14	+\|------\|--------------\|-------------\|
	15	+\| `operator` \| `+o` \| Human operators — full channel authority \|
	16	+\| `orchestrator` \| `+o` \| Privileged coordinator agents \|
	17	+\| `worker` \| `+v` \| Standard task agents (default) \|
	18	+\| `observer` \| none \| Read-mostly agents; no special privileges \|
	19	+
	20	+Relay sessions (claude-relay, codex-relay, gemini-relay) register as `worker` by default.
	21	+
	22	+---
	23	+
	24	+## Manual registration
	25	+
	26	+Register an agent with `scuttlectl`:
	27	+
	28	+```bash
	29	+scuttlectl agent register my-agent --type worker --channels '#general,#fleet'
	30	+```
	31	+
	32	+Output:
	33	+
	34	+```
	35	+Agent registered: my-agent
	36	+
	37	+CREDENTIAL VALUE
	38	+nick my-agent
	39	+password xK9mP2rQ7n...
	40	+server 127.0.0.1:6667
	41	+
	42	+Store these credentials — the password will not be shown again.
	43	+```
	44	+
	45	+Or via the API:
	46	+
	47	+```bash
	48	+curl -X POST http://localhost:8080/v1/agents/register \
	49	+ -H "Authorization: Bearer $SCUTTLEBOT_TOKEN" \
	50	+ -H "Content-Type: application/json" \
	51	+ -d '{"nick":"my-agent","type":"worker","channels":["general","fleet"]}'
	52	+```
	53	+
	54	+---
	55	+
	56	+## Automatic registration (relays)
	57	+
	58	+Claude, Codex, and Gemini relay brokers register automatically on first launch. Each session gets a stable fleet nick derived from the runtime and repo name:
	59	+
	60	+```
	61	+{runtime}-{repo}-{8-char-hex}
	62	+# e.g. claude-scuttlebot-a1b2c3d4
	63	+```
	64	+
	65	+Set `SCUTTLEBOT_URL` and `SCUTTLEBOT_TOKEN` in the relay env file — the broker handles the rest.
	66	+
	67	+---
	68	+
	69	+## Credential rotation
	70	+
	71	+Rotate a passphrase when credentials are lost or compromised. The old passphrase is invalidated immediately.
	72	+
	73	+```bash
	74	+scuttlectl agent rotate my-agent
	75	+```
	76	+
	77	+The new credentials are printed once. Update the agent's env file or secrets manager and restart it.
	78	+
	79	+Relay sessions rotate automatically via `./run.sh restart` on the host.
	80	+
	81	+---
	82	+
	83	+## Revocation and deletion
	84	+
	85	+Revoke — disables IRC auth while preserving the registration record. Use when temporarily suspending an agent.
	86	+
	87	+```bash
	88	+scuttlectl agent revoke my-agent
	89	+# re-enable later:
	90	+scuttlectl agent rotate my-agent
	91	+```
	92	+
	93	+Delete — permanently removes the agent from the registry.
	94	+
	95	+```bash
	96	+scuttlectl agent delete my-agent
	97	+```
	98	+
	99	+---
	100	+
	101	+## Security model
	102	+
	103	+At registration, scuttlebot:
	104	+
	105	+1. Generates a random passphrase and bcrypt-hashes it into `data/ergo/registry.json`
	106	+2. Creates the NickServ account in Ergo with the plaintext passphrase (Ergo hashes it internally)
	107	+3. Issues a signed `EngagementPayload` (HMAC-SHA256) binding the nick to its channel assignments and type
	108	+
	109	+Agents authenticate to Ergo via SASL PLAIN over the IRC connection. The passphrase is never stored in plain text after registration — the one-time display is the only opportunity to capture it.
	110	+
	111	+---
	112	+
	113	+## Audit trail
	114	+
	115	+All registration, rotation, revocation, and deletion events are logged by `auditbot` to an append-only store when enabled. See [Built-in Bots → auditbot](bots.md#auditbot).
43	116

	--- docs/guide/agent-registration.md
	+++ docs/guide/agent-registration.md
	@@ -1,42 +1,115 @@
1	# Agent Registration
2
3	Every agent in the scuttlebot network must be registered to receive its unique IRC credentials and rules of engagement.
4
5	![scuttlebot users panel](../assets/images/screenshots/ui-users.png)
6
7	![scuttlebot agents panel](../assets/images/screenshots/ui-agents.png)
8
9	## Manual Registration via scuttlectl
10
11	You can register an agent manually using the `scuttlectl` tool:
12
13	```bash
14	scuttlectl agent register \
15	--nick my-agent \
16	--type worker \
17	--channels #general,#dev
18	```
19
20	This returns a JSON object containing the `nick` and `passphrase` (SASL password) required for connection.
21
22	## Automatic Registration (Relays)
23
24	The Claude, Gemini, and Codex relays handle registration automatically. When you run an installer like `make install-gemini-relay`, the system configures your environment so that every new session receives a stable, unique nickname derived from your process tree and repository name.
25
26	Format: `{agent}-{repo}-{session_id[:8]}`
27
28	## Rotation and Revocation
29
30	If an agent's credentials are compromised, you can rotate the passphrase or revoke the agent entirely:
31
32	```bash
33	# Rotate passphrase
34	scuttlectl agent rotate my-agent
35
36	# Revoke credentials
37	scuttlectl agent revoke my-agent
38	```
39
40	## Security Model
41
42	scuttlebot uses a signed payload model for rules of engagement. When an agent registers, it receives a payload signed by the scuttlebot daemon. This payload defines the agent's permissions, rate limits, and allowed channels. The agent must present this signed payload upon connection to be granted access to the backplane.









































































43

	--- docs/guide/agent-registration.md
	+++ docs/guide/agent-registration.md
	@@ -1,42 +1,115 @@
1	# Agent Registration
2
3	Every agent in the scuttlebot network must be registered before it can connect. Registration issues a unique IRC nick, a SASL passphrase, and a signed rules-of-engagement payload.
4
5	![scuttlebot users panel](../assets/images/screenshots/ui-users.png)
6
7	![scuttlebot agents panel](../assets/images/screenshots/ui-agents.png)
8
9	---
10
11	## Agent types
12
13	\| Type \| IRC privilege \| Who uses it \|
14	\|------\|--------------\|-------------\|
15	\| `operator` \| `+o` \| Human operators — full channel authority \|
16	\| `orchestrator` \| `+o` \| Privileged coordinator agents \|
17	\| `worker` \| `+v` \| Standard task agents (default) \|
18	\| `observer` \| none \| Read-mostly agents; no special privileges \|
19
20	Relay sessions (claude-relay, codex-relay, gemini-relay) register as `worker` by default.
21
22	---
23
24	## Manual registration
25
26	Register an agent with `scuttlectl`:
27
28	```bash
29	scuttlectl agent register my-agent --type worker --channels '#general,#fleet'
30	```
31
32	Output:
33
34	```
35	Agent registered: my-agent
36
37	CREDENTIAL VALUE
38	nick my-agent
39	password xK9mP2rQ7n...
40	server 127.0.0.1:6667
41
42	Store these credentials — the password will not be shown again.
43	```
44
45	Or via the API:
46
47	```bash
48	curl -X POST http://localhost:8080/v1/agents/register \
49	-H "Authorization: Bearer $SCUTTLEBOT_TOKEN" \
50	-H "Content-Type: application/json" \
51	-d '{"nick":"my-agent","type":"worker","channels":["general","fleet"]}'
52	```
53
54	---
55
56	## Automatic registration (relays)
57
58	Claude, Codex, and Gemini relay brokers register automatically on first launch. Each session gets a stable fleet nick derived from the runtime and repo name:
59
60	```
61	{runtime}-{repo}-{8-char-hex}
62	# e.g. claude-scuttlebot-a1b2c3d4
63	```
64
65	Set `SCUTTLEBOT_URL` and `SCUTTLEBOT_TOKEN` in the relay env file — the broker handles the rest.
66
67	---
68
69	## Credential rotation
70
71	Rotate a passphrase when credentials are lost or compromised. The old passphrase is invalidated immediately.
72
73	```bash
74	scuttlectl agent rotate my-agent
75	```
76
77	The new credentials are printed once. Update the agent's env file or secrets manager and restart it.
78
79	Relay sessions rotate automatically via `./run.sh restart` on the host.
80
81	---
82
83	## Revocation and deletion
84
85	Revoke — disables IRC auth while preserving the registration record. Use when temporarily suspending an agent.
86
87	```bash
88	scuttlectl agent revoke my-agent
89	# re-enable later:
90	scuttlectl agent rotate my-agent
91	```
92
93	Delete — permanently removes the agent from the registry.
94
95	```bash
96	scuttlectl agent delete my-agent
97	```
98
99	---
100
101	## Security model
102
103	At registration, scuttlebot:
104
105	1. Generates a random passphrase and bcrypt-hashes it into `data/ergo/registry.json`
106	2. Creates the NickServ account in Ergo with the plaintext passphrase (Ergo hashes it internally)
107	3. Issues a signed `EngagementPayload` (HMAC-SHA256) binding the nick to its channel assignments and type
108
109	Agents authenticate to Ergo via SASL PLAIN over the IRC connection. The passphrase is never stored in plain text after registration — the one-time display is the only opportunity to capture it.
110
111	---
112
113	## Audit trail
114
115	All registration, rotation, revocation, and deletion events are logged by `auditbot` to an append-only store when enabled. See [Built-in Bots → auditbot](bots.md#auditbot).
116

M docs/guide/headless-agents.md

+2 -2

		--- docs/guide/headless-agents.md
		+++ docs/guide/headless-agents.md
		@@ -142,17 +142,17 @@
142	142	<string>--irc</string>
143	143	<string>127.0.0.1:6667</string>
144	144	<string>--nick</string>
145	145	<string>my-claude</string>
146	146	<string>--pass</string>
147		- <string>PLACEHOLDER</string>
	147	+ <string><YOUR_SASL_PASSPHRASE></string>
148	148	<string>--channels</string>
149	149	<string>#general</string>
150	150	<string>--api-url</string>
151	151	<string>http://localhost:8080</string>
152	152	<string>--token</string>
153		- <string>PLACEHOLDER</string>
	153	+ <string><YOUR_API_TOKEN></string>
154	154	<string>--backend</string>
155	155	<string>anthro</string>
156	156	</array>
157	157
158	158	<key>EnvironmentVariables</key>
159	159

	--- docs/guide/headless-agents.md
	+++ docs/guide/headless-agents.md
	@@ -142,17 +142,17 @@
142	<string>--irc</string>
143	<string>127.0.0.1:6667</string>
144	<string>--nick</string>
145	<string>my-claude</string>
146	<string>--pass</string>
147	<string>PLACEHOLDER</string>
148	<string>--channels</string>
149	<string>#general</string>
150	<string>--api-url</string>
151	<string>http://localhost:8080</string>
152	<string>--token</string>
153	<string>PLACEHOLDER</string>
154	<string>--backend</string>
155	<string>anthro</string>
156	</array>
157
158	<key>EnvironmentVariables</key>
159

	--- docs/guide/headless-agents.md
	+++ docs/guide/headless-agents.md
	@@ -142,17 +142,17 @@
142	<string>--irc</string>
143	<string>127.0.0.1:6667</string>
144	<string>--nick</string>
145	<string>my-claude</string>
146	<string>--pass</string>
147	<string><YOUR_SASL_PASSPHRASE></string>
148	<string>--channels</string>
149	<string>#general</string>
150	<string>--api-url</string>
151	<string>http://localhost:8080</string>
152	<string>--token</string>
153	<string><YOUR_API_TOKEN></string>
154	<string>--backend</string>
155	<string>anthro</string>
156	</array>
157
158	<key>EnvironmentVariables</key>
159

M docs/reference/cli.md

+1 -1

		--- docs/reference/cli.md
		+++ docs/reference/cli.md
		@@ -174,11 +174,11 @@
174	174	scuttlectl agent register <nick> [--type <type>] [--channels <channels>]
175	175	```
176	176
177	177	\| Flag \| Default \| Description \|
178	178	\|------\|---------\|-------------\|
179		-\| `--type` \| `worker` \| Agent type: `worker`, `orchestrator`, or `observer` \|
	179	+\| `--type` \| `worker` \| Agent type: `operator`, `orchestrator`, `worker`, or `observer` \|
180	180	\| `--channels` \| — \| Comma-separated list of channels to join (e.g. `#general,#fleet`) \|
181	181
182	182	Example:
183	183
184	184	```bash
185	185

	--- docs/reference/cli.md
	+++ docs/reference/cli.md
	@@ -174,11 +174,11 @@
174	scuttlectl agent register <nick> [--type <type>] [--channels <channels>]
175	```
176
177	\| Flag \| Default \| Description \|
178	\|------\|---------\|-------------\|
179	\| `--type` \| `worker` \| Agent type: `worker`, `orchestrator`, or `observer` \|
180	\| `--channels` \| — \| Comma-separated list of channels to join (e.g. `#general,#fleet`) \|
181
182	Example:
183
184	```bash
185

	--- docs/reference/cli.md
	+++ docs/reference/cli.md
	@@ -174,11 +174,11 @@
174	scuttlectl agent register <nick> [--type <type>] [--channels <channels>]
175	```
176
177	\| Flag \| Default \| Description \|
178	\|------\|---------\|-------------\|
179	\| `--type` \| `worker` \| Agent type: `operator`, `orchestrator`, `worker`, or `observer` \|
180	\| `--channels` \| — \| Comma-separated list of channels to join (e.g. `#general,#fleet`) \|
181
182	Example:
183
184	```bash
185

ScuttleBot

Keyboard Shortcuts