crewbus 11.3.1 → 11.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +21 -0
- package/README.md +2 -2
- package/bin/lib/web.js +1903 -1704
- package/docs/APPROVALS.md +28 -58
- package/docs/ARCHITECTURE.md +113 -0
- package/docs/AUDIT_EXPORT.md +9 -104
- package/docs/CERT_READINESS.md +13 -120
- package/docs/COMPATIBILITY.md +65 -0
- package/docs/CONSOLIDATOR.md +8 -43
- package/docs/CONTROL_PLANE_SPEC.md +16 -340
- package/docs/CREWS.md +9 -54
- package/docs/DELIVERY.md +2 -0
- package/docs/EXPERIMENTS.md +7 -52
- package/docs/GROUPS.md +13 -109
- package/docs/HA.md +15 -151
- package/docs/IDENTITY.md +10 -162
- package/docs/ISOLATION.md +22 -39
- package/docs/LIMITS.md +12 -21
- package/docs/LONG_RUNS.md +10 -56
- package/docs/OIDC_TLS.md +8 -69
- package/docs/ORCHESTRATOR.md +8 -82
- package/docs/PAIRING.md +2 -0
- package/docs/QUICKSTART.md +10 -75
- package/docs/RBAC.md +10 -80
- package/docs/SECURITY.md +111 -0
- package/docs/SHARED_RESPONSIBILITY.md +8 -32
- package/docs/SPLIT.md +13 -82
- package/docs/STORAGE.md +9 -63
- package/docs/TENANCY.md +8 -74
- package/docs/THREAT_MODEL.md +16 -68
- package/docs/TROUBLESHOOTING.md +16 -27
- package/docs/VERIFIER.md +8 -50
- package/docs/VERSION_SKEW.md +13 -57
- package/docs/WHEN_NOT.md +11 -35
- package/documentation.html +199 -4
- package/index.html +4 -4
- package/package.json +1 -1
- package/packages/client-runtime/auth.js +7 -3
- package/packages/client-runtime/routes.js +3 -0
package/docs/HA.md
CHANGED
|
@@ -1,151 +1,15 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
## Topology
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
│ sync pull (standby-initiated, --relay-interval)
|
|
17
|
-
┌──────▼──────┐
|
|
18
|
-
readers ───────▶│ STANDBY │◀────── readers
|
|
19
|
-
(GET manifest/ │ serve │
|
|
20
|
-
file/wait) │ --standby │
|
|
21
|
-
└─────────────┘
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
- **Writes go to the primary only.** Sync clients need no changes: they push
|
|
25
|
-
to whichever relay URL they are configured with, and a standby answers
|
|
26
|
-
`503 {role: "standby", primary: <url>}` with an `X-Relay-Role: standby`
|
|
27
|
-
header so operators (and scripts) know where the writer is.
|
|
28
|
-
- **Reads scale out:** put a load balancer over primary + standbys for GET
|
|
29
|
-
paths (`/sync/manifest`, `/sync/file`, `/sync/wait`, `/api/events`,
|
|
30
|
-
`/healthz`). Never balance writes across relays — there is exactly one
|
|
31
|
-
writer.
|
|
32
|
-
- **Manual failover is recommended.** Auto-promote is opt-in (see below).
|
|
33
|
-
|
|
34
|
-
## Running a standby
|
|
35
|
-
|
|
36
|
-
Standby and primary **share the relay secret** (`--secret` /
|
|
37
|
-
`CREWBUS_SECRET`) so the standby can pull `/sync/*` from the primary.
|
|
38
|
-
Outbound TLS flags (`--insecure`, `--mtls-cert`/`--mtls-key`,
|
|
39
|
-
`--bearer`/`--oidc-token`) are honored for the upstream pull.
|
|
40
|
-
|
|
41
|
-
```
|
|
42
|
-
# primary (as before)
|
|
43
|
-
crewbus serve --port 8080 --secret "$RELAY_SECRET"
|
|
44
|
-
|
|
45
|
-
# standby: empty board that tracks the primary every 5s (default)
|
|
46
|
-
crewbus init --board /var/boards/replica.crewbus --harness opencode
|
|
47
|
-
CREWBUS_DIR=/var/boards/replica.crewbus \
|
|
48
|
-
crewbus serve --port 8081 --secret "$RELAY_SECRET" \
|
|
49
|
-
--standby http://primary:8080 [--relay-interval 5]
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
### Transport note: Tailscale
|
|
53
|
-
|
|
54
|
-
Relays bind localhost; anything multi-machine needs a transport you
|
|
55
|
-
trust (see `SECURITY.md`: never face the open internet without a tunnel
|
|
56
|
-
on top). The boring, recommended answer is a mesh VPN like Tailscale:
|
|
57
|
-
run the relay commands above unchanged but address peers by tailnet name
|
|
58
|
-
(`--standby http://pi:8080`), and you get encrypted transport, stable
|
|
59
|
-
hostnames across reboots and DHCP churn, and NAT traversal for sync
|
|
60
|
-
peers behind home routers — with nothing ever exposed publicly. Keep
|
|
61
|
-
the relay secret + OIDC/TLS layers on anyway (defense in depth, and
|
|
62
|
-
the same setup works verbatim without the mesh). Tailscale is an
|
|
63
|
-
operator choice, never a dependency: crewbus ships zero network
|
|
64
|
-
code beyond its own HTTP relay.
|
|
65
|
-
|
|
66
|
-
While a standby, the server:
|
|
67
|
-
|
|
68
|
-
- pulls via `syncRound` on `--relay-interval` seconds (per-peer cursor in
|
|
69
|
-
`sync-state/`, same overlap logic as `sync --interval`);
|
|
70
|
-
- serves GET reads from its local (replicated) board;
|
|
71
|
-
- refuses `POST /sync/put`, `POST /api/spawn`, `POST /api/launch`,
|
|
72
|
-
`POST /api/kill`, and pair writes (`POST /api/pair/issue|exchange|revoke`)
|
|
73
|
-
with **503 + `X-Relay-Role: standby`** and a JSON `{error, role, primary}`
|
|
74
|
-
hint — checked *before* the relay secret, so load balancers and clients
|
|
75
|
-
get a clean signal without credentials (pair reads such as
|
|
76
|
-
`GET /api/pair/devices` still serve locally);
|
|
77
|
-
- records state in `<board>/relay.json`
|
|
78
|
-
(`role`, `primary`, `lastSyncOk`, `lagMs`, `consecFails`, `promotion`,
|
|
79
|
-
`promotedAt`, `fence`).
|
|
80
|
-
|
|
81
|
-
## Health + status
|
|
82
|
-
|
|
83
|
-
- `GET /healthz` (no auth — safe for load-balancer probes):
|
|
84
|
-
`{role, weight, workers, advertisedRoutes, primary, lagMs, lastSyncOk,
|
|
85
|
-
lastSyncErr, promotion, promotedAt, uptimeSec}` (`advertisedRoutes` from
|
|
86
|
-
`--advertise-routes`; `weight` from `--weight`; `workers` = live spawned
|
|
87
|
-
pids) with an `X-Relay-Role` header. Route reads to `role ==
|
|
88
|
-
"standby"` **or** the primary; shed a replica when `lagMs` exceeds your
|
|
89
|
-
SLO.
|
|
90
|
-
- `crewbus relay status [--json] [--board <path>]` prints the same state
|
|
91
|
-
from `relay.json` — works with no server running.
|
|
92
|
-
|
|
93
|
-
## Failover
|
|
94
|
-
|
|
95
|
-
**Manual (recommended):**
|
|
96
|
-
|
|
97
|
-
```
|
|
98
|
-
crewbus relay promote --board /var/boards/replica.crewbus [--fence <path-or-url>]
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
A running standby re-reads `relay.json` on every request and sync tick, so
|
|
102
|
-
promotion takes effect **without restart**: the next write is accepted and
|
|
103
|
-
the pull loop stops. Verify with `relay status` and `GET /healthz`.
|
|
104
|
-
|
|
105
|
-
**Automatic (opt-in):**
|
|
106
|
-
|
|
107
|
-
```
|
|
108
|
-
crewbus serve ... --standby http://primary:8080 --promote-on-miss 30
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
After N seconds with no successful pull, the standby promotes itself.
|
|
112
|
-
This is a liveness heuristic, not consensus.
|
|
113
|
-
|
|
114
|
-
## Split-brain risk + fencing guidance (read this before --promote-on-miss)
|
|
115
|
-
|
|
116
|
-
Two writers diverge: each accepts mail/spawns, and the sync merge reunites
|
|
117
|
-
only what its rules cover (mail unions cleanly; presence/cursors take HLC
|
|
118
|
-
LWW — the loser's state is silently dropped). **There is exactly one safe
|
|
119
|
-
configuration: at most one reachable writer.**
|
|
120
|
-
|
|
121
|
-
- Default to manual failover: kill (or firewall) the old primary, then
|
|
122
|
-
`relay promote` the standby. Dead primary + promoted standby = no split
|
|
123
|
-
brain, ever.
|
|
124
|
-
- If you use `--promote-on-miss`, also pass `--fence <path-or-url>`:
|
|
125
|
-
a shared lock both relays can reach. Promotion claims it; a fresh claim
|
|
126
|
-
by a *different* owner refuses the next promotion. A local path fence
|
|
127
|
-
works when both relays share a disk (writes `{owner, at}` JSON, 120s
|
|
128
|
-
freshness window); an HTTP(S) fence URL is liveness-checked via its own
|
|
129
|
-
`/healthz` (a live `primary` there refuses). Fencing is **best-effort**:
|
|
130
|
-
it raises the bar, it does not make concurrent writers impossible under
|
|
131
|
-
partitions. `relay promote --force` overrides it (log who forced, and
|
|
132
|
-
why).
|
|
133
|
-
- After failover, treat the old primary as **poisoned** until you rebuild
|
|
134
|
-
it as a fresh standby (re-`init` an empty board, point `--standby` at the
|
|
135
|
-
new primary). Never let the old primary serve writes again with its old
|
|
136
|
-
state while the promoted one is live.
|
|
137
|
-
- `relay.json` + `sync-state/` are local-only (never synced), so a
|
|
138
|
-
re-purposed board carries no stale role into its next life — but double
|
|
139
|
-
check `relay status` before opening writes.
|
|
140
|
-
|
|
141
|
-
## Limits (honest scope)
|
|
142
|
-
|
|
143
|
-
- No consensus / quorum / term numbers: partitions are resolved by operator
|
|
144
|
-
procedure, not by the software.
|
|
145
|
-
- Replication lag is pull-interval-bound (`--relay-interval`, default 5s);
|
|
146
|
-
a standby can serve reads up to `lagMs` stale — check `/healthz`.
|
|
147
|
-
- Fencing is advisory file/HTTP checks, not distributed locks.
|
|
148
|
-
- Audit forwarder state (`audit-spool/`) is per-relay: run
|
|
149
|
-
`--audit-forward` on the primary; a promoted standby starts forwarding
|
|
150
|
-
from its own spool (at-least-once may re-deliver events the old primary
|
|
151
|
-
already forwarded — SIEM dedup on `seq`+`board` covers it).
|
|
1
|
+
# High Availability & Relay Replication
|
|
2
|
+
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#ha-sync`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#ha-sync)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/ARCHITECTURE.md`](file:///C:/Users/Surface/Documents/crewbus/docs/ARCHITECTURE.md)
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Active / Passive Relay Topology
|
|
10
|
+
|
|
11
|
+
- Single writer (Primary relay) handles writes (`POST /api/spawn`, sync push).
|
|
12
|
+
- Standby relays replicate from primary via pull (`--relay-interval 5s`).
|
|
13
|
+
- Standbys serve read endpoints (`GET /sync/manifest`, `/sync/file`, `/healthz`) locally; writes return 503 with `X-Relay-Role: standby`.
|
|
14
|
+
- Promotion: `crewbus relay promote --from orchestrator`. Split-brain prevention: ensure old primary stays down.
|
|
15
|
+
- Recommended transport: Tailscale / WireGuard private mesh.
|
package/docs/IDENTITY.md
CHANGED
|
@@ -1,166 +1,14 @@
|
|
|
1
|
-
# Identity
|
|
1
|
+
# Token-Bound Identity & Lifecycle
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#identity-tokens`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#identity-tokens)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/SECURITY.md`](file:///C:/Users/Surface/Documents/crewbus/docs/SECURITY.md)
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
---
|
|
6
8
|
|
|
7
|
-
|
|
8
|
-
(`tokenHash` + `salt`). Plaintext tokens are printed **once** at mint and
|
|
9
|
-
never again. `--json` outputs and sync payloads strip secrets.
|
|
10
|
-
- `expiresAt` (ISO string or `null`) = token expiry. `null`/missing = never.
|
|
11
|
-
- `rotatedAt` (ISO) = last `token rotate` time.
|
|
12
|
-
- `service: true` = service account (non-expiring by default).
|
|
13
|
-
- `offboarded: true` = deprovisioned. DM files stay on disk for audit, but
|
|
14
|
-
sends as that name are refused.
|
|
15
|
-
- `revoked/<hashPrefix16>.json` = revocation list entries
|
|
16
|
-
`{tokenHash, target, revokedAt, by, reason?}`. Immutable, synced
|
|
17
|
-
copy-if-missing (tombstone-like: deleted copies resurrect on next sync,
|
|
18
|
-
so a revocation is never undone).
|
|
9
|
+
## Credential Management
|
|
19
10
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
crewbus
|
|
24
|
-
# -> prints: registered alice token abt-... (save it: CREWBUS_TOKEN=...)
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
- First claim wins. Save the token in your env/vault (`CREWBUS_TOKEN`).
|
|
28
|
-
- Concurrent first-claims are atomic: exactly one wins (exclusive file
|
|
29
|
-
create); losers fail loudly as a claimed name. Minting over an existing
|
|
30
|
-
record (legacy takeover, post-revoke re-claim) verifies the write won —
|
|
31
|
-
a loser prints nothing usable and must retry.
|
|
32
|
-
- With a TTL: `register --from alice --expires-in 24h` (durations reuse the
|
|
33
|
-
prune parser: `30`, `90s`, `15m`, `24h`, `7d`, `2w`; bare = seconds).
|
|
34
|
-
- Expired tokens fail loudly everywhere with re-register guidance:
|
|
35
|
-
`token for "alice" expired at ... — re-register to renew`.
|
|
36
|
-
|
|
37
|
-
## Service accounts (one per workload)
|
|
38
|
-
|
|
39
|
-
```
|
|
40
|
-
crewbus register --service deploy-bot
|
|
41
|
-
# or: crewbus register --from deploy-bot --service
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
- Non-expiring by default (`expiresAt: null`); pass `--expires-in` to bound it.
|
|
45
|
-
- Flagged `service:true`; excluded from `agents --active` unless you pass
|
|
46
|
-
`--include-services`.
|
|
47
|
-
- **One per workload, stored in a vault/env, never pasted in chat.**
|
|
48
|
-
|
|
49
|
-
## Rotation
|
|
50
|
-
|
|
51
|
-
```
|
|
52
|
-
crewbus token rotate --from alice [--expires-in 7d]
|
|
53
|
-
crewbus token status --from alice [--json]
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
- `rotate` mints a replacement; the old token dies immediately. Records
|
|
57
|
-
`rotatedAt`. `status` shows expiry/rotation state — never secrets.
|
|
58
|
-
|
|
59
|
-
## Mover (rename / team change)
|
|
60
|
-
|
|
61
|
-
1. Offboard the old name (orchestrator, token-checked):
|
|
62
|
-
`register --offboard old-name --from orchestrator`
|
|
63
|
-
2. Register the new name: `register --from new-name`
|
|
64
|
-
3. History stays: DMs to/from the old name remain on disk and in `--all`
|
|
65
|
-
dumps for audit.
|
|
66
|
-
|
|
67
|
-
## Leaver / revocation
|
|
68
|
-
|
|
69
|
-
```
|
|
70
|
-
# kill one identity's live tokens (identity stays, they must re-register):
|
|
71
|
-
crewbus token revoke --from orchestrator --target bob [--reason "laptop lost"]
|
|
72
|
-
|
|
73
|
-
# full deprovision (revokes tokens + marks offboarded, inbox preserved):
|
|
74
|
-
crewbus register --offboard bob --from orchestrator
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
- Revoked callers get: `token for "bob" is revoked — re-register...`.
|
|
78
|
-
- Offboarded callers get: `agent "bob" is offboarded — sends ... refused`.
|
|
79
|
-
- Re-register after revoke mints fresh (no dead token needed);
|
|
80
|
-
offboarded names stay refused until the orchestrator re-onboards them.
|
|
81
|
-
|
|
82
|
-
## Sync hygiene
|
|
83
|
-
|
|
84
|
-
- Agent docs sync as mutable LWW (`hlc`, `v`): `expiresAt`, `rotatedAt`,
|
|
85
|
-
`service`, `offboarded`, `revokedAt` replicate; secrets (`token`,
|
|
86
|
-
`tokenHash`, `salt`) are stripped on push, on `/sync/file` serve, and in
|
|
87
|
-
`mergeSyncedAgent` (local secrets win).
|
|
88
|
-
- `revoked/` syncs as immutable union (copy-if-missing), like tombstones.
|
|
89
|
-
|
|
90
|
-
## Token files (long-running agents)
|
|
91
|
-
|
|
92
|
-
A worker's token is printed **once** at mint and otherwise lives in session
|
|
93
|
-
env — after compaction/restart amnesia the worker is locked out of its own
|
|
94
|
-
claimed name (first-claim-wins: re-registering a claimed name fails). So a
|
|
95
|
-
long-running agent persists its token to a file it can re-read.
|
|
96
|
-
|
|
97
|
-
- **Convention:** `.crewbus/logs/<agent-name>.token` — raw token text
|
|
98
|
-
with a trailing newline, chmod `0600` best-effort. `<agent-name>` is the
|
|
99
|
-
sanitized agent name (lowercase, `[^a-z0-9_.-]` → `-`, max 40 chars).
|
|
100
|
-
Helpers: `tokenFilePath(root, name)`, `saveTokenFile(root, name, token)`
|
|
101
|
-
(mkdir recursive, write + chmod, returns path), `loadTokenFile(root, name)`
|
|
102
|
-
(trimmed string or `null`) in `bin/lib/tokenfile.js` (`root` = the
|
|
103
|
-
`.crewbus/` dir).
|
|
104
|
-
- **Who writes it:** the worker itself, right after register/mint, as
|
|
105
|
-
instructed by the spawn prompt. Exact one-liners (replace `<name>` and
|
|
106
|
-
`<token>`; run from the project dir so `.crewbus/` resolves):
|
|
107
|
-
|
|
108
|
-
POSIX:
|
|
109
|
-
|
|
110
|
-
```
|
|
111
|
-
printf '%s\n' '<token>' > .crewbus/logs/<name>.token && chmod 600 .crewbus/logs/<name>.token
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
PowerShell:
|
|
115
|
-
|
|
116
|
-
```powershell
|
|
117
|
-
Set-Content -Path .crewbus/logs/<name>.token -Value '<token>' -NoNewline:$false
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
- **Security trade-off, stated plainly:** per `docs/THREAT_MODEL.md`,
|
|
121
|
-
local-file access already equals control — anyone with shell access can
|
|
122
|
-
read/write `.crewbus/` directly, so a `0600` token file beside the logs
|
|
123
|
-
grants nothing the filesystem doesn't already grant. It is consistent with
|
|
124
|
-
that model, not an escalation. Even so: **never commit it, never post it**
|
|
125
|
-
(not in chat, mail, PRs, or logs), and `prune`/export must never include
|
|
126
|
-
`*.token`.
|
|
127
|
-
- **Recovery order:** token file first (`loadTokenFile`, i.e. read
|
|
128
|
-
`.crewbus/logs/<name>.token`), then `CREWBUS_TOKEN` env. Re-register
|
|
129
|
-
is **impossible** for claimed names (first-claim-wins rejects it), so there
|
|
130
|
-
is no third option — protect the file.
|
|
131
|
-
|
|
132
|
-
## Post-compaction identity recovery (`crewbus recover`)
|
|
133
|
-
|
|
134
|
-
Compaction amnesia used to mint throwaway identities (`unknown` on the board,
|
|
135
|
-
`logs/unknown.token` nobody owns). Two layers now stop that:
|
|
136
|
-
|
|
137
|
-
- **Sentinel names never mint:** `unknown`, `me`, `you` are reserved —
|
|
138
|
-
`register` and `send` refuse them loudly (`ensureSender` guards them, so
|
|
139
|
-
every write path is covered). They exist only for tools that forgot who
|
|
140
|
-
they are, to force the recovery path instead of a silent identity loss.
|
|
141
|
-
- **Read-only candidate ranking:** `crewbus recover [--session <id>]
|
|
142
|
-
[--cwd <dir>]` scans `agents/*.json` ∩ `logs/*.token` and prints scored
|
|
143
|
-
candidates (best first): session-id register binding +4, token-file
|
|
144
|
-
cross-check against the stored `tokenHash`/`salt` +3 (proof), token file
|
|
145
|
-
exists +1, `lastDir` cwd match +1. It never writes or mints; it prints the
|
|
146
|
-
exact resume commands (CREWBUS_AGENT, token-file path, `inbox --unacked
|
|
147
|
-
--digest`). Offboarded agents are excluded for privacy-critical boards.
|
|
148
|
-
|
|
149
|
-
```
|
|
150
|
-
crewbus: triage on [board …/sandbox-1/.crewbus]
|
|
151
|
-
proven pilg (role worker, score 9) — session id matches register binding;
|
|
152
|
-
token file cross-checks the stored hash; worked from this directory
|
|
153
|
-
resume as 'pilg': …
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
- **Rehydrators resolve before naming "unknown":** the compaction card
|
|
157
|
-
(opencode plugin + `crewbus-hook compact`) first checks its session↔agent
|
|
158
|
-
map, then `CREWBUS_AGENT`, then a lite board-side score (binding + token
|
|
159
|
-
file + cwd, no hash cross-check in the standalone copies). Only when all
|
|
160
|
-
miss does it print the `crewbus recover` instruction — never a "you are
|
|
161
|
-
unknown" blessing.
|
|
162
|
-
- **Bindings survive daily traffic:** register stores `sessionId`; later
|
|
163
|
-
sessionless sends/re-registers/orchestrator touches must NOT wipe it
|
|
164
|
-
(`mergeAgentDoc` deletes undefined patch keys — callers add `sessionId`
|
|
165
|
-
to the patch only when given). Heartbeats merge field-by-field and never
|
|
166
|
-
touch unrelated fields.
|
|
11
|
+
- Minted on first claim; stored in `agents/<name>.json` as salted SHA-256 hashes.
|
|
12
|
+
- Plaintext printed once at minting; never written to disk or synced across relays.
|
|
13
|
+
- Commands: `crewbus register <name>`, `crewbus token rotate --from <name>`, `crewbus token revoke <name>`.
|
|
14
|
+
- Post-compaction recovery: `crewbus recover [--session <id>]` recovers identity bindings without registering dummy accounts.
|
package/docs/ISOLATION.md
CHANGED
|
@@ -1,39 +1,22 @@
|
|
|
1
|
-
# Isolation
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
my-worker-image worker-entrypoint
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
## Egress blocked
|
|
27
|
-
|
|
28
|
-
`--network none` disables container egress: crews coordinate through the
|
|
29
|
-
board mount instead of the network. If a harness needs model API access,
|
|
30
|
-
prefer a proxy you control over full egress, and keep the board mount as
|
|
31
|
-
the only host write path.
|
|
32
|
-
|
|
33
|
-
## --auto and sandboxes
|
|
34
|
-
|
|
35
|
-
`--auto` selects each harness's fully-unattended mode (no permission
|
|
36
|
-
prompts) and requires loud confirmation (`--i-understand-danger` or an
|
|
37
|
-
interactive `yes`), plus prints a DANGER banner and warns when no
|
|
38
|
-
container/CI sandbox is detected (`CONTAINER`/`DOCKER`/`CI` unset).
|
|
39
|
-
Run `--auto` crews on isolated runners only.
|
|
1
|
+
# Container Isolation & Sandboxing
|
|
2
|
+
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#container-isolation`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#container-isolation)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/SECURITY.md`](file:///C:/Users/Surface/Documents/crewbus/docs/SECURITY.md)
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Overview & Rules
|
|
10
|
+
|
|
11
|
+
- **spawn --isolate:** Attempts container isolation when Docker is available; warns when running unisolated without Docker.
|
|
12
|
+
- **Board as the ONLY mounted channel:** Mount ONLY the board directory read-write into the worker container; mount nothing else. The worker's cwd should be a checkout or worktree inside the isolation boundary.
|
|
13
|
+
```sh
|
|
14
|
+
docker run --rm --network none \
|
|
15
|
+
-v /path/to/.crewbus:/board:rw \
|
|
16
|
+
-e CREWBUS_DIR=/board \
|
|
17
|
+
-e CREWBUS_AGENT=worker-1 \
|
|
18
|
+
my-worker-image worker-entrypoint
|
|
19
|
+
```
|
|
20
|
+
- **Egress blocked:** `--network none` disables network egress; agents coordinate solely through the board mount.
|
|
21
|
+
- **--auto and sandboxes:** `--auto` selects fully-unattended execution (no permission prompts). It requires loud confirmation (`--i-understand-danger` or interactive prompt) and prints danger banners if no container/CI environment is detected (`CONTAINER`, `DOCKER`, `CI` unset).
|
|
22
|
+
- **--workdir-root:** Enforces that worker cwd cannot escape the designated root boundary.
|
package/docs/LIMITS.md
CHANGED
|
@@ -1,23 +1,14 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Scale Limits & Operational Budgets
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#scale-limits`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#scale-limits)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/COMPATIBILITY.md`](file:///C:/Users/Surface/Documents/crewbus/docs/COMPATIBILITY.md)
|
|
5
6
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
-
|
|
12
|
-
|
|
13
|
-
-
|
|
14
|
-
- Per-worker budgets: `--budget-tokens N --budget-minutes M` are recorded
|
|
15
|
-
on the agent (`spawn-status` warns when the log-size token estimate or
|
|
16
|
-
elapsed time exceeds them; `budget` object in `--json`).
|
|
17
|
-
- Fan-out cost estimate: sends over 100 recipients print estimated files +
|
|
18
|
-
bytes and require `--yes` to proceed.
|
|
19
|
-
- Dead-man timeouts: `spawn --timeout 10m` records `deadlineAt`
|
|
20
|
-
(`30`, `90s`, `15m`, `24h`, `7d`, `2w` syntax); `spawn-status` flags
|
|
21
|
-
passed deadlines — reap with `spawn-kill`/`stop`.
|
|
22
|
-
- Global stop: `crewbus stop --all --from <you>` kills every spawned
|
|
23
|
-
worker truly (whole process tree: `taskkill /T /F` on Windows).
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Budgets & Ceilings
|
|
10
|
+
|
|
11
|
+
- **Broadcast fan-out:** `--to` supports up to 10,000 recipients.
|
|
12
|
+
- **Concurrent live workers:** `spawn` caps at 20 live boots per call; budget workers like compute processes.
|
|
13
|
+
- **Thread depth:** `MAX_FWD_DEPTH` is 16.
|
|
14
|
+
- **Rate limits:** 60 messages/minute per agent (override with `--no-rate-limit`).
|
package/docs/LONG_RUNS.md
CHANGED
|
@@ -1,60 +1,14 @@
|
|
|
1
|
-
# Long
|
|
1
|
+
# Long-Running Tasks Playbook
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
playbook: keep every session short and replaceable, keep all state on
|
|
7
|
-
the board.
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#delivery`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#delivery)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/ARCHITECTURE.md`](file:///C:/Users/Surface/Documents/crewbus/docs/ARCHITECTURE.md)
|
|
8
6
|
|
|
9
|
-
|
|
7
|
+
---
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
and (on grok) the inbox skill. Re-run after every crewbus upgrade;
|
|
13
|
-
`doctor` stays green.
|
|
14
|
-
2. Tokens persist themselves: every register/mint/rotate writes
|
|
15
|
-
`.crewbus/logs/<agent>.token` (0600). Workers re-read it after any
|
|
16
|
-
restart or compaction instead of re-registering (re-registering a
|
|
17
|
-
claimed name fails). Truly lost it? The orchestrator runs `token revoke --target
|
|
18
|
-
<name>`, worker re-registers fresh. Never commit or post token files;
|
|
19
|
-
`prune`/export skip `*.token`.
|
|
20
|
-
3. Poll digest-first: `inbox --unacked --digest`, full reads only on
|
|
21
|
-
hits, `--grep`/`--priority` to narrow. A full dump every step will eat
|
|
22
|
-
any context window in days.
|
|
23
|
-
4. Bound every worker: `--budget-tokens/--budget-minutes`, `--timeout`
|
|
24
|
-
(dead-man `deadlineAt`), `--max-turns` where the harness supports it.
|
|
25
|
-
Unbounded workers are how 10-day tasks become 10-day contexts.
|
|
9
|
+
## Long Runs (Multi-Day Tasks)
|
|
26
10
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
-
|
|
30
|
-
|
|
31
|
-
thread replies: "done X / next Y"), replies, exits.
|
|
32
|
-
- Leads aggregate with `gather`, never by holding the whole crew's
|
|
33
|
-
context. The next wave respawns fresh with full windows and continues
|
|
34
|
-
from the latest checkpoints + inbox.
|
|
35
|
-
- Supervisors die too: `pool-resume` re-attaches pool supervision;
|
|
36
|
-
`respawn` reboots one dead worker in its same conversation.
|
|
37
|
-
- Push keeps everyone woke (Stop hooks, waiters, monitors); digest
|
|
38
|
-
polling keeps everyone cheap.
|
|
39
|
-
|
|
40
|
-
## Recovery ladder (tape this up)
|
|
41
|
-
|
|
42
|
-
| Symptom | Fix |
|
|
43
|
-
|---|---|
|
|
44
|
-
| Post-compaction amnesia | Identity card is auto-injected (hook compact / opencode plugin); unknown who you are? run `crewbus recover` — read-only candidate ranking (session binding → token-file↔tokenHash → cwd), then follow the printed resume script |
|
|
45
|
-
| Landed as "unknown" | Sentinel names ("unknown"/"me"/"you") never mint (register/send refuse them). Run `crewbus recover [--session <id>]` to re-find your real identity; only then re-register your true name |
|
|
46
|
-
| Token lost entirely | Orchestrator `token revoke --target`, worker re-registers |
|
|
47
|
-
| Worker silent | `spawn-status`: no reply → read its log; re-brief or `respawn` |
|
|
48
|
-
| Supervisor gone | `pool-resume --id`; stale locks expire via TTL |
|
|
49
|
-
| Reboot | `doctor` → `spawn-status --all` (stale pids read dead, not running) → `respawn`/`pool-resume`; dead coordinator: `crewbus spawn --count 0 --body "<what the crew was on>"` (C9 orchestrator revive, workers untouched) |
|
|
50
|
-
| Primary relay down | `relay promote` on the standby (see `docs/HA.md`) |
|
|
51
|
-
|
|
52
|
-
## Bottom line
|
|
53
|
-
|
|
54
|
-
Don't run one agent for 10 days — run a board for 10 days. Persistent
|
|
55
|
-
peers or rotating pool waves, checkpoints every few steps, digest-first
|
|
56
|
-
polling, token files beside the logs, budgets on everything, and
|
|
57
|
-
compaction hooks that rehydrate identity. Sessions compact, processes
|
|
58
|
-
die, machines reboot; mail, briefs, checkpoints, and session ids survive
|
|
59
|
-
all three on disk. A cold session plus a warm board is a crew that never
|
|
60
|
-
sleeps.
|
|
11
|
+
- Rotate workers in waves; sessions are a cache, the board is the database.
|
|
12
|
+
- Use `--checkpoint` to preserve intermediate progress before risky actions.
|
|
13
|
+
- Poll digest-first: `crewbus inbox --from <you> --unacked --digest`.
|
|
14
|
+
- Re-brief replacement workers on surviving threads.
|
package/docs/OIDC_TLS.md
CHANGED
|
@@ -1,73 +1,12 @@
|
|
|
1
|
-
#
|
|
1
|
+
# TLS & OIDC Bearer Authentication
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#security`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#security)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/SECURITY.md`](file:///C:/Users/Surface/Documents/crewbus/docs/SECURITY.md)
|
|
5
6
|
|
|
6
|
-
|
|
7
|
+
---
|
|
7
8
|
|
|
8
|
-
|
|
9
|
-
crewbus login --issuer <url> --client-id <id> --token <jwt> [--board <path>]
|
|
10
|
-
```
|
|
9
|
+
## In-Box TLS & Tokens
|
|
11
10
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
`iss` / `aud` (= `--client-id`) / `exp` with 60s clock-skew tolerance, then
|
|
15
|
-
binds it to board identity `oidc-<sub>` (sub lowercased/sanitized, 35 chars +
|
|
16
|
-
`oidc-` prefix), minting the local agent record linked to `sub`. No local
|
|
17
|
-
token is minted or needed while the JWT is valid. JWKS/discovery responses are
|
|
18
|
-
cached in-memory with a 10-minute TTL. Supported algs: RS256/384/512,
|
|
19
|
-
ES256/384/512. The JWT is never logged.
|
|
20
|
-
|
|
21
|
-
## Relay accepts Bearer as a secret alternative
|
|
22
|
-
|
|
23
|
-
```sh
|
|
24
|
-
crewbus serve --oidc-issuer <url> --oidc-audience <id> [...]
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
Protected endpoints (`/sync/*`, `/api/spawn`, `/api/kill`) accept
|
|
28
|
-
`Authorization: Bearer <jwt>` (verified as above) as an alternative to
|
|
29
|
-
`--secret`/`CREWBUS_SECRET`. Identity is attached to the request
|
|
30
|
-
(`req.oidc = {sub, iss}`); permission checks stay in the existing gates —
|
|
31
|
-
this phase authenticates only. Clients pass the JWT explicitly:
|
|
32
|
-
|
|
33
|
-
```sh
|
|
34
|
-
crewbus sync --with https://peer:port --bearer <jwt> [...]
|
|
35
|
-
CREWBUS_OIDC_TOKEN=<jwt> crewbus sync --with https://peer:port [...]
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
## In-box TLS
|
|
39
|
-
|
|
40
|
-
```sh
|
|
41
|
-
crewbus serve --tls-cert <pem> --tls-key <pem> [--tls-ca <pem>]
|
|
42
|
-
crewbus sync --with https://peer:port [...]
|
|
43
|
-
crewbus listen --with https://peer:port [...]
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
`--tls-cert/--tls-key` switch the relay to `node:https` (same routes).
|
|
47
|
-
`sync`/`listen` follow the URL protocol (`http:` or `https:`).
|
|
48
|
-
|
|
49
|
-
Self-signed friendly (dev/test only):
|
|
50
|
-
|
|
51
|
-
```sh
|
|
52
|
-
crewbus sync --with https://peer:port --insecure
|
|
53
|
-
CREWBUS_INSECURE=1 crewbus sync --with https://peer:port [...]
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
Skips peer-cert verification with a loud stderr warning. Never use with real
|
|
57
|
-
credentials.
|
|
58
|
-
|
|
59
|
-
## mTLS relay-to-relay (opt-in)
|
|
60
|
-
|
|
61
|
-
```sh
|
|
62
|
-
crewbus serve --mtls-ca <pem> [...] # (--tls-ca is an alias)
|
|
63
|
-
crewbus sync --with https://peer:port --mtls-cert <pem> --mtls-key <pem>
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
With a client-verify CA configured, the relay requires a verified client
|
|
67
|
-
certificate on `/sync/*` only (401 otherwise); other routes are unaffected.
|
|
68
|
-
Tunnel alternative stays fine: keep plain `http` and terminate TLS in front.
|
|
69
|
-
|
|
70
|
-
## Secrets hygiene
|
|
71
|
-
|
|
72
|
-
Tokens/JWTs are never logged (errors name the failed check, never the
|
|
73
|
-
credential) and the `web` dashboard never renders them.
|
|
11
|
+
- In-box TLS certificate generation for relay endpoints.
|
|
12
|
+
- Support for mTLS client certificates and OIDC Bearer JWTs for enterprise federated identity.
|