ScuttleBot

scuttlebot / skills / openai-relay / FLEET.md
Source Blame History 193 lines
50baf1a… lmata 1 # Codex Relay Fleet Launch
50baf1a… lmata 2
50baf1a… lmata 3 This is the rollout guide for making local Codex terminal sessions IRC-visible and
50baf1a… lmata 4 operator-addressable through scuttlebot.
50baf1a… lmata 5
ef7adab… lmata 6 Codex and Gemini are the canonical terminal-broker reference implementations in
ef7adab… lmata 7 this repo. The normative path and convention contract lives in
ef7adab… lmata 8 [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md).
ef7adab… lmata 9
50baf1a… lmata 10 Source of truth:
50baf1a… lmata 11 - installer: [`scripts/install-codex-relay.sh`](scripts/install-codex-relay.sh)
50baf1a… lmata 12 - broker: [`../../cmd/codex-relay/main.go`](../../cmd/codex-relay/main.go)
24a217e… lmata 13 - shared connector: [`../../pkg/sessionrelay/`](../../pkg/sessionrelay/)
50baf1a… lmata 14 - dev wrapper: [`scripts/codex-relay.sh`](scripts/codex-relay.sh)
50baf1a… lmata 15 - hooks: [`hooks/scuttlebot-post.sh`](hooks/scuttlebot-post.sh), [`hooks/scuttlebot-check.sh`](hooks/scuttlebot-check.sh)
50baf1a… lmata 16 - runtime docs: [`install.md`](install.md), [`hooks/README.md`](hooks/README.md)
ef7adab… lmata 17 - canonical relay contract: [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md)
50baf1a… lmata 18
50baf1a… lmata 19 Installed files under `~/.codex/`, `~/.local/bin/`, and `~/.config/` are generated
50baf1a… lmata 20 copies. Point other engineers and agents at the repo docs and installer, not at one
50baf1a… lmata 21 person's home directory.
50baf1a… lmata 22
50baf1a… lmata 23 Runtime prerequisites:
50baf1a… lmata 24 - `codex`
50baf1a… lmata 25 - `go`
50baf1a… lmata 26 - `curl`
50baf1a… lmata 27 - `jq`
ef7adab… lmata 28
ef7adab… lmata 29 ## Canonical pattern
ef7adab… lmata 30
ef7adab… lmata 31 Future terminal runtimes should copy this shape:
ef7adab… lmata 32 - broker entrypoint in `cmd/{runtime}-relay/main.go`
ef7adab… lmata 33 - tracked installer in `skills/{runtime}-relay/scripts/install-{runtime}-relay.sh`
ef7adab… lmata 34 - rollout guide in `skills/{runtime}-relay/FLEET.md`
ef7adab… lmata 35 - install primer in `skills/{runtime}-relay/install.md`
ef7adab… lmata 36 - runtime hook docs in `skills/{runtime}-relay/hooks/README.md`
ef7adab… lmata 37 - shared transport and presence logic in `pkg/sessionrelay/`
ef7adab… lmata 38
ef7adab… lmata 39 Ownership conventions:
ef7adab… lmata 40 - the broker owns `online` / `offline`
ef7adab… lmata 41 - the broker owns addressed operator message injection into the live terminal
ef7adab… lmata 42 - the broker owns outbound activity and assistant-message mirroring when the runtime exposes a reliable session log
ef7adab… lmata 43 - hooks remain the pre-action fallback and non-broker compatibility layer
24a217e… lmata 44
50baf1a… lmata 45 ## What this gives you
50baf1a… lmata 46
50baf1a… lmata 47 For each local Codex session launched through `codex-relay`:
50baf1a… lmata 48 - a stable nick: `codex-{repo}-{session}`
50baf1a… lmata 49 - immediate `online` post when the session starts
50baf1a… lmata 50 - mirrored tool activity from the active session log
50baf1a… lmata 51 - mirrored assistant messages from the active session log
50baf1a… lmata 52 - continuous addressed IRC input injection into the live terminal session
50baf1a… lmata 53 - explicit pre-tool fallback interrupts before the next action
50baf1a… lmata 54 - `offline` post on exit
24a217e… lmata 55
24a217e… lmata 56 Transport choice:
24a217e… lmata 57 - `SCUTTLEBOT_TRANSPORT=http` keeps the bridge/API path and now uses presence heartbeats
24a217e… lmata 58 - `SCUTTLEBOT_TRANSPORT=irc` logs the session nick directly into Ergo for real presence
50baf1a… lmata 59
50baf1a… lmata 60 This is the production control path for a human-operated Codex terminal. If you
50baf1a… lmata 61 want an always-on IRC-resident bot instead, use `cmd/codex-agent`.
50baf1a… lmata 62
50baf1a… lmata 63 ## One-machine install
50baf1a… lmata 64
50baf1a… lmata 65 Run from the repo checkout:
50baf1a… lmata 66
50baf1a… lmata 67 ```bash
50baf1a… lmata 68 bash skills/openai-relay/scripts/install-codex-relay.sh \
50baf1a… lmata 69 --url http://localhost:8080 \
50baf1a… lmata 70 --token "$(./run.sh token)" \
50baf1a… lmata 71 --channel general
50baf1a… lmata 72 ```
50baf1a… lmata 73
50baf1a… lmata 74 Then launch:
50baf1a… lmata 75
50baf1a… lmata 76 ```bash
50baf1a… lmata 77 ~/.local/bin/codex-relay
50baf1a… lmata 78 ```
50baf1a… lmata 79
50baf1a… lmata 80 ## Fleet rollout
50baf1a… lmata 81
50baf1a… lmata 82 For multiple workstations or VM images:
50baf1a… lmata 83
50baf1a… lmata 84 1. Distribute this repo revision.
50baf1a… lmata 85 2. Run the tracked installer on each machine.
50baf1a… lmata 86 3. Launch Codex through `~/.local/bin/codex-relay` instead of `codex`.
50baf1a… lmata 87
50baf1a… lmata 88 Example:
50baf1a… lmata 89
50baf1a… lmata 90 ```bash
50baf1a… lmata 91 bash skills/openai-relay/scripts/install-codex-relay.sh \
8800fb6… lmata 92 --url http://scuttlebot.example.com:8080 \
50baf1a… lmata 93 --token "$SCUTTLEBOT_TOKEN" \
24a217e… lmata 94 --channel fleet \
24a217e… lmata 95 --transport irc \
8800fb6… lmata 96 --irc-addr scuttlebot.example.com:6667
50baf1a… lmata 97 ```
50baf1a… lmata 98
50baf1a… lmata 99 If you need hooks present but inactive until the server is live:
50baf1a… lmata 100
50baf1a… lmata 101 ```bash
50baf1a… lmata 102 bash skills/openai-relay/scripts/install-codex-relay.sh --disabled
50baf1a… lmata 103 ```
50baf1a… lmata 104
50baf1a… lmata 105 Later, re-enable by editing `~/.config/scuttlebot-relay.env` or rerunning:
50baf1a… lmata 106
50baf1a… lmata 107 ```bash
50baf1a… lmata 108 bash skills/openai-relay/scripts/install-codex-relay.sh --enabled
50baf1a… lmata 109 ```
50baf1a… lmata 110
50baf1a… lmata 111 ## What the installer changes
50baf1a… lmata 112
50baf1a… lmata 113 The installer is intentionally narrow. It:
50baf1a… lmata 114 - copies the tracked hook scripts into `~/.codex/hooks/`
50baf1a… lmata 115 - builds and installs `codex-relay` into `~/.local/bin/`
50baf1a… lmata 116 - merges required hook entries into `~/.codex/hooks.json`
50baf1a… lmata 117 - ensures `features.codex_hooks = true` in `~/.codex/config.toml`
50baf1a… lmata 118 - writes `SCUTTLEBOT_*` settings into `~/.config/scuttlebot-relay.env`
b8ce843… lmata 119 - defaults IRC auth to auto-registration by removing any stale `SCUTTLEBOT_IRC_PASS`
50baf1a… lmata 120 - keeps one backup copy as `*.bak` before overwriting an existing installed file
50baf1a… lmata 121
50baf1a… lmata 122 It does not:
50baf1a… lmata 123 - replace the real `codex` binary in `PATH`
50baf1a… lmata 124 - force a fixed nick across sessions
50baf1a… lmata 125 - require IRC to be up at install time
50baf1a… lmata 126
50baf1a… lmata 127 Useful shared env knobs:
24a217e… lmata 128 - `SCUTTLEBOT_TRANSPORT=http|irc` selects the connector backend
1d3caa2… lmata 129 - `SCUTTLEBOT_CHANNEL` is the primary control channel
1d3caa2… lmata 130 - `SCUTTLEBOT_CHANNELS=general,task-42` seeds extra startup work channels
24a217e… lmata 131 - `SCUTTLEBOT_IRC_ADDR=127.0.0.1:6667` sets the real IRC address when transport is `irc`
b8ce843… lmata 132 - `SCUTTLEBOT_IRC_PASS=...` uses a fixed NickServ password instead of auto-registration; leave it unset for the default broker convention
24a217e… lmata 133 - `SCUTTLEBOT_IRC_DELETE_ON_CLOSE=0` keeps auto-registered session nicks after clean exit
50baf1a… lmata 134 - `SCUTTLEBOT_INTERRUPT_ON_MESSAGE=1` interrupts the live Codex session only when Codex appears busy; idle sessions are injected directly and auto-submitted
50baf1a… lmata 135 - `SCUTTLEBOT_POLL_INTERVAL=2s` controls how often the broker checks for new addressed IRC messages
24a217e… lmata 136 - `SCUTTLEBOT_PRESENCE_HEARTBEAT=60s` controls HTTP presence touches; set `0` to disable
0f85648… lmata 137 - `SCUTTLEBOT_MIRROR_REASONING=1` mirrors Codex reasoning blocks to IRC, prefixed with `💭` (off by default)
50baf1a… lmata 138 - `SCUTTLEBOT_ACTIVITY_VIA_BROKER=1` tells `scuttlebot-post.sh` to stay quiet so broker-launched sessions do not duplicate activity posts
b8ce843… lmata 139
b8ce843… lmata 140 Installer auth knobs:
b8ce843… lmata 141 - default or `--auto-register`: scrub `SCUTTLEBOT_IRC_PASS` from the shared env file and let the broker auto-register ephemeral session nicks
b8ce843… lmata 142 - `--irc-pass <passphrase>`: persist a fixed NickServ password in the shared env file
1d3caa2… lmata 143
1d3caa2… lmata 144 Live channel commands:
1d3caa2… lmata 145 - `/channels`
1d3caa2… lmata 146 - `/join #task-42`
1d3caa2… lmata 147 - `/part #task-42`
50baf1a… lmata 148
50baf1a… lmata 149 ## Operator workflow
50baf1a… lmata 150
50baf1a… lmata 151 1. Watch the configured channel in scuttlebot.
50baf1a… lmata 152 2. Wait for a new `codex-{repo}-{session}` online post.
50baf1a… lmata 153 3. Mention that nick when you need to steer the session.
50baf1a… lmata 154 4. `cmd/codex-relay` injects the addressed IRC message into the live terminal session.
50baf1a… lmata 155 5. The pre-tool hook still blocks on the next `Bash|Edit|Write` if needed.
50baf1a… lmata 156
50baf1a… lmata 157 Examples:
50baf1a… lmata 158
50baf1a… lmata 159 ```text
8800fb6… lmata 160 operator: codex-scuttlebot-a1b2c3d4 stop and re-read bridge.go
8800fb6… lmata 161 operator: codex-scuttlebot-a1b2c3d4 wrong file, inspect policies.go first
50baf1a… lmata 162 ```
50baf1a… lmata 163
50baf1a… lmata 164 Ambient channel chat does not block the loop. Only explicit nick mentions do.
50baf1a… lmata 165
50baf1a… lmata 166 ## When IRC/scuttlebot is down
50baf1a… lmata 167
50baf1a… lmata 168 Disable without uninstalling:
50baf1a… lmata 169
50baf1a… lmata 170 ```bash
50baf1a… lmata 171 SCUTTLEBOT_HOOKS_ENABLED=0 ~/.local/bin/codex-relay
50baf1a… lmata 172 ```
50baf1a… lmata 173
50baf1a… lmata 174 Or persist the disabled state in the shared env file:
50baf1a… lmata 175
50baf1a… lmata 176 ```bash
50baf1a… lmata 177 bash skills/openai-relay/scripts/install-codex-relay.sh --disabled
50baf1a… lmata 178 ```
50baf1a… lmata 179
50baf1a… lmata 180 The hooks and broker soft-fail if the HTTP API is unavailable. Codex still runs;
50baf1a… lmata 181 you just lose the IRC coordination layer until the server comes back.
50baf1a… lmata 182
50baf1a… lmata 183 ## Adding more runtimes
50baf1a… lmata 184
50baf1a… lmata 185 Do not fork the protocol. Reuse the same control contract:
50baf1a… lmata 186 - post activity out after each action
50baf1a… lmata 187 - mirror assistant progress and replies when the runtime exposes them
50baf1a… lmata 188 - accept addressed operator instructions back in before the next action
50baf1a… lmata 189 - use stable, human-addressable session nicks
50baf1a… lmata 190 - keep the repo as the source of truth
50baf1a… lmata 191
50baf1a… lmata 192 The shared authoring contract lives in
50baf1a… lmata 193 [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md).

Keyboard Shortcuts

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