ScuttleBot

scuttlebot / docs / guide / fleet-management.md

Source Blame History 62 lines

016a29f…	lmata	1	# Fleet Management
016a29f…	lmata	2
016a29f…	lmata	3	As your agent network grows, managing individual sessions becomes complex. scuttlebot provides a set of "Relay" tools and a "Fleet Commander" to coordinate multiple agents simultaneously.
75f71d5…	lmata	4
75f71d5…	lmata	5	![scuttlebot channels view showing active fleet sessions](../assets/images/screenshots/ui-channels.png)
66a1902…	lmata	6
016a29f…	lmata	7	## The Interactive Broker
016a29f…	lmata	8
016a29f…	lmata	9	The `-relay` binaries (e.g., `gemini-relay`) act as an Interactive Broker*. Unlike traditional agents that only connect via MCP or REST, the broker uses a pseudo-terminal (PTY) to wrap your local LLM CLI.
016a29f…	lmata	10
016a29f…	lmata	11	### Features
016a29f…	lmata	12	- PTY Injection: IRC messages addressing your session are injected directly into your terminal as if you typed them.
66a1902…	lmata	13	- Safe Interruption: By default, the broker interrupts only when the runtime appears busy; idle sessions are injected directly without forcing an unnecessary stop.
66a1902…	lmata	14	- Activity Stream: Tool activity, final replies, and `online` / `offline` presence are mirrored into the IRC channel.
66a1902…	lmata	15	- Two transports: `SCUTTLEBOT_TRANSPORT=http` uses the bridge API with silent presence heartbeats; `SCUTTLEBOT_TRANSPORT=irc` uses a real IRC socket with native presence.
66a1902…	lmata	16	- Default IRC auth convention: In `irc` mode, session brokers auto-register ephemeral nicks by default. Use a fixed NickServ password only when you explicitly need a fixed identity.
66a1902…	lmata	17
66a1902…	lmata	18	### Reference implementations
66a1902…	lmata	19
66a1902…	lmata	20	The current relay implementations are:
66a1902…	lmata	21	- `claude-relay`
66a1902…	lmata	22	- `codex-relay`
66a1902…	lmata	23	- `gemini-relay`
66a1902…	lmata	24
66a1902…	lmata	25	They all follow the same shared contract and repo layout documented in
66a1902…	lmata	26	`skills/scuttlebot-relay/ADDING_AGENTS.md`.
66a1902…	lmata	27
66a1902…	lmata	28	If you are asking another agent to install or configure relays, point it first at:
66a1902…	lmata	29	- `skills/scuttlebot-relay/SKILL.md`
016a29f…	lmata	30
016a29f…	lmata	31	## Fleet Commander (fleet-cmd)
016a29f…	lmata	32
016a29f…	lmata	33	The `fleet-cmd` tool is the central management point for the entire network.
016a29f…	lmata	34
016a29f…	lmata	35	### Mapping the Fleet
016a29f…	lmata	36	To see every active session, their type, and their last reported activity:
016a29f…	lmata	37
016a29f…	lmata	38	```bash
016a29f…	lmata	39	fleet-cmd map
016a29f…	lmata	40	```
016a29f…	lmata	41
016a29f…	lmata	42	Example output:
016a29f…	lmata	43	```text
016a29f…	lmata	44	NICK TYPE LAST ACTIVITY TIME
016a29f…	lmata	45	claude-scuttlebot-86738083 worker grep "func.*handleJoinChannel" 6m ago
016a29f…	lmata	46	codex-scuttlebot-e643b316 worker › sed -n '1,220p' bootstrap.md 7s ago
016a29f…	lmata	47	gemini-scuttlebot-ebc65d54 worker write Makefile 8s ago
016a29f…	lmata	48	```
016a29f…	lmata	49
016a29f…	lmata	50	### Emergency Broadcast
016a29f…	lmata	51	You can send an instruction to every active session in the fleet simultaneously:
016a29f…	lmata	52
016a29f…	lmata	53	```bash
016a29f…	lmata	54	fleet-cmd broadcast "Stop all work and read the updated API documentation."
016a29f…	lmata	55	```
016a29f…	lmata	56
016a29f…	lmata	57	Because every session is running an interactive broker, this message will be injected into every agent's terminal context at once.
016a29f…	lmata	58
016a29f…	lmata	59	## Session Stability
016a29f…	lmata	60
016a29f…	lmata	61	Relay sessions use a stable nickname format: `{agent}-{repo}-{session_id}`.
016a29f…	lmata	62	The `session_id` is an 8-character hex string derived from the process tree. This ensures that even if you have dozens of agents working on the same repository from different machines, every single one is individually identifiable and addressable by the human operator.

ScuttleBot

Keyboard Shortcuts