Dai Ha
a94262271b
Two defects found after the fact, both from the original brief, both fixed here. 1. confirm() is called FROM the calling lead's own turn, so its pane is still WORKING and can never report injectable inside that same call. The old confirm() sent /clear before polling for that — the poll always timed out, but only after /clear had already fired and queued, destroying the lead's context with no fresh session ever started and a refusal return that lied about what had happened. Fix: confirm() now only validates and, if every gate passes, hands a one-shot continuation to a new continuationRunner (a real virtual thread in production, Runnable::run in tests) and returns RollDecision.approved() immediately - "scheduled", not "rolled". The continuation itself does the actual work, once the calling turn has ended: wait for the SAME pane to report injectable again (new turnSettleSeconds config key, default 20) - if this never happens, /clear is NEVER sent, at all - then /clear, then wait again (clearSettleSeconds, as before), then bootstrapText. The "no timer/scheduler, only confirm() can roll" invariant is restated precisely in LeadRollover's class javadoc: it is about initiative, not synchronicity - a single-shot continuation of an already-approved confirm() call still satisfies it; a recurring background loop would not. 2. confirm() resolved the pane to clear via PrimaryRegistry.primaryTerminal(), a single-slot lookup that is correct for a background loop with no caller but wrong here: on a daemon with more than one labelled lead tab, lead X's confirm() could clear lead Y's pane, violating the charter's "identity comes from the connection, never an argument" invariant. Fix: open() and confirm() now take the caller's terminal id as a parameter (resolved by the MCP layer from the connection - the later MCP-tool unit must pass it in, never accept it as a request field). confirm() refuses with a new NOT_YOUR_ROLLOVER reason unless it matches the terminal open() recorded. LeadRollover no longer depends on PrimaryRegistry at all. Also: renamed RollResult to RollDecision (rolled -> accepted) to reflect the new meaning - approved and scheduled, not necessarily cleared yet. Added turnSettleSeconds to the leadRollover: config block (documented in fleetd.example.yaml alongside the existing keys) and updated Fleetd.java's leadRollover(...) factory to drop the primaryRegistry parameter, with FleetdLeadRolloverWiringTest's source-text pin updated to match. New tests: turnThatNeverSettlesSendsNoClearAtAll (the branch that matters most - a turn that never ends means /clear is never sent) and aDifferentLeadTerminalCannotConfirmAnotherLeadsRollover (NOT_YOUR_ROLLOVER), plus a settle-after-clear timeout test and an open() input-validation test. LeadRolloverTest: 11 -> 14 tests.
969 lines
69 KiB
YAML
969 lines
69 KiB
YAML
# fleetd configuration (example). Copy to fleetd.yaml and adjust.
|
|
#
|
|
# fleetd is the sole gateway between primary/worker Claude sessions and herdr.
|
|
# It is NOT a Claude process and must never carry ANTHROPIC_BASE_URL.
|
|
|
|
# REST + MCP listen address. Keep it on loopback unless you also switch auth.mode to `token`
|
|
# below — fleetd REFUSES TO START on a non-loopback bind under loopback-trust (see auth).
|
|
bind:
|
|
host: 127.0.0.1
|
|
port: 8765
|
|
|
|
# API authentication (CB-501). Governs how a caller that is NOT an on-host worker pane proves it
|
|
# is the primary. Worker identity never depends on this: a loopback peer PID that maps to a herdr
|
|
# pane is unforgeable and is always honoured, so turning auth on cannot lock the fleet out.
|
|
#
|
|
# mode: loopback-trust → DEFAULT, and the historical behaviour: any loopback caller that is not
|
|
# a worker is the primary, no credential needed. Sound ONLY because the
|
|
# OS refuses remote connections to a loopback socket.
|
|
# mode: token → such a caller must send `Authorization: Bearer <token>`; without it it
|
|
# is anonymous and authorized for nothing. REQUIRED for a non-loopback
|
|
# bind — the daemon fails fast otherwise, because "unauthenticated ⇒
|
|
# primary" on a reachable port would hand spawn/stop/send to anyone.
|
|
# tokenEnv → host env var holding the token (never the literal value). Default
|
|
# FLEETD_API_TOKEN. Read only in token mode; empty ⇒ startup fails.
|
|
#
|
|
# TLS is deliberately NOT terminated in the daemon (CB-501 D3): run a reverse proxy in front and
|
|
# let it own certificate lifecycle, e.g.
|
|
# location / { proxy_pass http://127.0.0.1:8765; proxy_set_header Authorization $http_authorization; }
|
|
# The broker link gets TLS from its own URI (amqps://…) — see `broker` below.
|
|
# auth:
|
|
# mode: token
|
|
# tokenEnv: FLEETD_API_TOKEN
|
|
|
|
# Optional pinned primary terminal (CB-307). Names the herdr pane the PRIMARY itself runs in:
|
|
# a caller whose connection maps to this pane resolves as the primary (no credential needed —
|
|
# the pane mapping is as unforgeable as a worker's), and reply nudges are pushed to it.
|
|
# REQUIRED when the primary runs inside a herdr pane — without it the pane match reads the
|
|
# primary as a worker and refuses spawn/send/stop. Get the id from fleet_whoami; re-pin if
|
|
# the primary moves panes.
|
|
# primary:
|
|
# terminal: term_0123456789abcd
|
|
# pushReminders: 5 # max nudges before giving up (default 5)
|
|
# pushBackoffMs: 15000 # delay between nudges (default 15000)
|
|
|
|
# CB-530: MORE THAN ONE LEAD. `primary:` above is singular by construction — every other pane
|
|
# resolves as a worker — which is right for one lead driving a fleet and wrong the moment two leads
|
|
# (say a Claude lead and an opencode lead) work as peers: the second is silently demoted and refused
|
|
# every orchestration call. List each lead's pane here and all of them resolve as leads.
|
|
#
|
|
# tab → the ONLY field identity depends on (CB-579); the exact label of the tab hosting the lead.
|
|
# Label the tab yourself, or let fleetd label one it launches — see `fleet.leaders:` below.
|
|
# kind/model → descriptive; they document what runs in the pane and are echoed by fleet_whoami
|
|
#
|
|
# A lead's tab must already carry its label (or be launched by fleetd, which labels it) — there is
|
|
# no terminal id to paste in and nothing to re-pin when the session restarts: the tab survives, so
|
|
# the same label resolves the same lead again on the next scan.
|
|
# `fleet_whoami` reports `{"role":"primary","leader":"<name>"}`; role stays "primary" because a lead
|
|
# IS a primary for authorization, so nothing that keys on the role breaks.
|
|
#
|
|
# KEEP `primary:` when adding leads: it still addresses the CB-307 push loop, which needs a single
|
|
# destination for its nudges, and is a separate mechanism from lead identity — see `fleet.leaders:`.
|
|
#
|
|
# Leads are configured under `fleet.leaders:` — see THE FLEET further down.
|
|
#
|
|
# Two things stop the tab-name convention from becoming a way to claim leadership: the configured
|
|
# member spaces are excluded from the scan, so nothing fleetd places can land in a matching tab;
|
|
# and startup REFUSES a `tabPrefix` that the fleet tabLabel template, or any per-profile `tabLabel`
|
|
# override, also matches — so the two namespaces cannot overlap by accident. The label is a NAME,
|
|
# never a capability: what a pane may do is decided by the role the daemon resolves for it.
|
|
|
|
# CB-551: IDLE-LEAD HEARTBEAT — nudge the single lead back to work when it has been continuously
|
|
# idle (no open fleet_send driving it) past the quiet period. The fleet is one lead + architects +
|
|
# workers, so a lead that stalls is a single point of failure; the ReplyPushLoop only nudges when a
|
|
# reply lands, and this timer catches the gap where nothing lands and the lead just sits idle.
|
|
#
|
|
# Opt-in on purpose — it SPENDS the operator's subscription on its own initiative (each nudge starts
|
|
# a lead turn nobody asked for), so upgrading the daemon must never switch it on for you. Absent
|
|
# block = feature off, exactly as before.
|
|
#
|
|
# Three knobs, each with a default that errs on the side of not burning context:
|
|
# idleAfterSeconds: 300 # how long the lead must stay idle before the FIRST nudge (default 300 —
|
|
# # absorbs normal post-turn pauses; re-prompting every pause burns context)
|
|
# backoffMs: 60000 # re-check cadence / spacing between nudges past the quiet period (default 60000)
|
|
# quietNudgeCap: 3 # cap on consecutive nudges that find NOTHING pending, then it stops
|
|
# # until real state appears (default 3 — never nag an empty fleet forever)
|
|
# leadHeartbeat:
|
|
# idleAfterSeconds: 300
|
|
# backoffMs: 60000
|
|
# quietNudgeCap: 3
|
|
|
|
# Lead rollover (fleetd #480): replace a lead session that has decided it is ready to be replaced,
|
|
# without an operator doing it by hand. A lead writes a handover file, then asks fleetd to clear its
|
|
# own pane and bootstrap a fresh session against that file.
|
|
#
|
|
# Opt-in on purpose — it clears the lead's own pane on request, so upgrading the daemon must never
|
|
# acquire that ability for you. Absent block = feature off, and nothing is constructed at all. Even
|
|
# once present, nothing but an explicit confirm() call — one that passes every check — can ever
|
|
# cause a /clear: there is no recurring timer, heartbeat or scheduler anywhere in this feature that
|
|
# fires one on its own initiative. confirm() itself is called FROM the calling lead's own turn, so
|
|
# it cannot clear the pane inline (that pane is still WORKING); instead it schedules a one-shot
|
|
# continuation that waits for the SAME confirm() call's turn to end, then does the actual work. See
|
|
# dev.ltms.fleet.lead.LeadRollover's class javadoc for the exact order (fleetd #480 correction).
|
|
#
|
|
# handoverPath: REQUIRED when this block is present — where the handover file a fresh lead session
|
|
# reads must live. No default (an operator-specific path); a present block with no
|
|
# handoverPath refuses to start.
|
|
# requireOperatorConfirm: true # default true — confirm() refuses unless the caller also passes
|
|
# # operatorConfirmed: true
|
|
# maxDocAgeSeconds: 3600 # default 3600 — refuse a handover file older than this
|
|
# turnSettleSeconds: 20 # default 20 — how long the deferred roll waits for the CALLING
|
|
# # lead's own turn to end (its pane to report injectable again)
|
|
# # before sending /clear at all. If this elapses, /clear is NEVER
|
|
# # sent — a lead that never goes idle is still doing real work.
|
|
# clearSettleSeconds: 20 # default 20 — how long to wait for the pane to become injectable
|
|
# # again AFTER /clear before giving up (never sends bootstrapText
|
|
# # if this elapses). A separate, second wait from turnSettleSeconds.
|
|
# bootstrapText: "..." # default names handoverPath — sent to the lead once its pane
|
|
# # settles after /clear
|
|
# leadRollover:
|
|
# handoverPath: /path/to/handover.md
|
|
# requireOperatorConfirm: true
|
|
# maxDocAgeSeconds: 3600
|
|
# turnSettleSeconds: 20
|
|
# clearSettleSeconds: 20
|
|
# bootstrapText: "Fresh lead session: read the handover file and carry on."
|
|
|
|
# Fleet health detection is dormant unless enabled (CB-573). It reads one whole-fleet agent list
|
|
# per tick.
|
|
# intervalSeconds → how often a tick runs (default 30). ENFORCED floor of 15: the code computes
|
|
# Math.max(15, intervalSeconds), so a lower value is silently raised, not
|
|
# rejected.
|
|
# workingSuspectAfterSeconds → age before a BUSY member is suspected of a stall (default 600).
|
|
# ENFORCED floor of 300: a lower value is silently raised.
|
|
# paneProbeIntervalSeconds → accepted and parsed, but NOT YET READ by anything. Setting it changes
|
|
# nothing right now. It exists so a later build can start honouring it without
|
|
# another config-shape change.
|
|
# notifications.mode → "webhook" flips what fleet_list REPORTS (healthCoverage: "full" instead
|
|
# of "detection-only") — it does NOT make fleetd send any webhook call; no
|
|
# delivery mechanism is implemented yet. Any other value, or omitting the
|
|
# block, reports "detection-only".
|
|
# health:
|
|
# enabled: true
|
|
# intervalSeconds: 30 # floor 15
|
|
# workingSuspectAfterSeconds: 600 # floor 300 — how long BUSY with no activity means STALL_SUSPECTED
|
|
# paneProbeIntervalSeconds: 60 # parsed, but nothing reads it yet — changing it changes nothing
|
|
# notifications:
|
|
# mode: disabled
|
|
|
|
# Idle-sleep guard: while at least one member is live, hold an OS-level assertion against idle
|
|
# sleep (macOS only — a `caffeinate -i` child; a no-op elsewhere or if caffeinate is missing), so
|
|
# an unattended host does not idle-sleep out from under a member's long turn. Unlike health/
|
|
# configReload above, this is ON BY DEFAULT — omitting the block entirely leaves it enabled, the
|
|
# same as `enabled: true`. Uncomment only to turn it off:
|
|
# idleSleepGuard:
|
|
# enabled: false
|
|
|
|
# herdr Unix socket. Omit to use the client default
|
|
# (${HERDR_SOCKET_PATH:-~/.config/herdr/herdr.sock}).
|
|
herdrSocket: ~/.config/herdr/herdr.sock
|
|
|
|
# Optional socket for member panes. Omit this to use herdrSocket for both leads and members.
|
|
# memberHerdrSocket: /Users/member/.config/herdr/herdr.sock
|
|
|
|
# fleetd #213: the login shell the member OS user (memberHerdrSocket above) actually runs. ONLY
|
|
# read when memberHerdrSocket is set — fleetd's own $SHELL says nothing about a pane running
|
|
# under a different OS user, and there is no channel to ask herdr for that user's shell, so this
|
|
# must be told rather than guessed. Absent, blank, or anything not ending in "zsh" is treated the
|
|
# same as "not zsh": the memberCredentials.policy: allow-list ZDOTDIR scrub (see worktreeGroup
|
|
# below) is skipped in favour of the weaker CB-596 sentinel overlay — a degraded control, never a
|
|
# refusal to spawn. When memberHerdrSocket is absent this key is never consulted at all.
|
|
# memberLoginShell: /bin/zsh
|
|
|
|
# How member sessions are spawned. Define one or more named profiles (backends) under
|
|
# `profiles`; each key is the profile name (also the ccs profile). A profile says only WHICH
|
|
# BACKEND — model, CLI adapter, credentials, cost. It says nothing about what a member spawned on
|
|
# it is for; that is the member's role, and roles live under `fleet:` below. Which profile an
|
|
# unqualified spawn lands on comes from that role's pool, not from a global default.
|
|
#
|
|
# Shared knobs (placement/workspace) can be repeated per profile; they usually match.
|
|
# placement: tab → each worker lands in its OWN tab in a dedicated worker space (default).
|
|
# Use `pane` for the legacy behaviour (split the focused tab).
|
|
# mcpUrl → fleetd mounts the bridge MCP (--mcp-config, inline) + reply charter
|
|
# (--append-system-prompt) as launch flags; nothing is written to the profile.
|
|
# ideMcpUrl → opt-in (CB-634), default off. When set, fleetd mounts the IDE Index MCP as a
|
|
# second inline server named `intellij`, and adds an IDE charter that pins every
|
|
# ide_* call to the member's own worktree. A URL, not a boolean — host and port
|
|
# are host-specific. Set it only on a host where the IDE actually runs.
|
|
# ideProjectDir → repo-relative module dir the IDE opens and the overlay pins (CB-634). Only read
|
|
# when ideMcpUrl is set. This repo's Maven pom lives in `fleetd/`, not at the
|
|
# worktree root, so opening the root imports no module and ide_* resolves nothing;
|
|
# set this to `fleetd`. Omit for a repo whose project is the worktree root.
|
|
# ideOpenCommand → host command that opens ideProjectDir in the IDE at spawn (CB-634 auto-open).
|
|
# Only read when ideMcpUrl is set. `{dir}` is replaced with the absolute module
|
|
# dir and the command runs through `/bin/sh -c`, so set env inline if needed —
|
|
# e.g. `env DISPLAY=:10.0 idea {dir}`. Best-effort: a failure is logged, never
|
|
# fails the spawn. Omit to open the member's module by hand. There is no close
|
|
# half yet — an opened module stays open until the operator closes it.
|
|
# autoCompactWindow → opt-in, default off. A bounded token window that forces a spawned member to
|
|
# compact its context instead of running on the backend's own default and dying
|
|
# mid-turn (losing its fleet_reply — the whole point of the turn — with it).
|
|
# Validated at config load to [100000, 1000000] — the band Claude Code's own
|
|
# --autocompact flag accepts.
|
|
# CROSS-BACKEND SEMANTICS DIFFER: on claude-code this is a launch-time
|
|
# `--autocompact <tokens>` flag — the member compacts AT this window. opencode
|
|
# has no equivalent flag (it only forces `compaction.auto: true`, unconditionally,
|
|
# already), so this is instead applied as the model's `limit.context` in the
|
|
# generated opencode.json — the member compacts WITHIN this window, not exactly
|
|
# at it — and only when this profile's `model:` is in `provider/model` form; if it
|
|
# isn't, fleetd logs a WARN naming the profile rather than silently doing nothing.
|
|
# tokenEnv → host env var holding the worker's auth token (value never stored in config);
|
|
# omit for a backend that needs no token (e.g. a local ollama).
|
|
# cwd → pin this profile's working directory (CB-112). Omit to inherit the primary's
|
|
# cwd on an MCP spawn, else the daemon's cwd — never $HOME. See
|
|
# docs/Worker-Startup-and-Trust.md.
|
|
# configDir → CLAUDE_CONFIG_DIR for the worker, so it inherits that profile's
|
|
# skills/MCP/hooks. Omit to leave the worker on the host default.
|
|
# parityOverlay → repo-relative paths copied primary→worktree so a worker in a provisioned
|
|
# worktree sees the same local config (CB-301-ext). Omit for the default set:
|
|
# [.env] only (CB-148). .envrc is left out of the default on purpose: it is
|
|
# executable shell that direnv runs on every cd, so copying it carries
|
|
# behaviour into the worker, not just values, unlike .env. An operator who
|
|
# wants it copied can still write parityOverlay: [.env, .envrc] explicitly.
|
|
# (.claude/settings.local.json is NOT in the default — it
|
|
# pre-approves IDE/tool grants a member must not hold ambiently; CB-525/CB-634.)
|
|
#
|
|
# Do NOT add .mcp.json (CB-525). A worker's tools are whatever its launcher
|
|
# mounts — the bridge, and nothing else. Replicating the primary's MCP config
|
|
# handed a worker the primary's IDE servers, which are bound to the primary's
|
|
# checkout, so its navigation returned paths OUTSIDE its own worktree: one
|
|
# worker made all 59 of its edits in the primary tree while compiling its
|
|
# worktree, and every build it ran was of code that did not contain them.
|
|
# fleetd neutralizes a provisioned worktree's .mcp.json for this reason;
|
|
# listing it here would copy the primary's back over that.
|
|
# gitTokenEnv → host env var holding the git-forge API token. When set, its value is injected
|
|
# as GITEA_TOKEN so the worker can open its OWN PR at checkpoint (CB-302).
|
|
# Opt-in by design — omit and the worker gets no PR-create grant (push over
|
|
# SSH is unaffected). The token value itself is never stored in this file.
|
|
# gitHostEnv → host env var holding the forge host (default GITEA_HOST). Injected as
|
|
# GITEA_HOST *only* alongside a resolved gitTokenEnv.
|
|
# exhaustedPattern → regex matched against a completion-fallback scrape (CB-578 stage A) to
|
|
# classify a turn that ended with no fleet_reply as the backend having
|
|
# refused on a subscription usage limit, rather than a real answer. Opt-in —
|
|
# omit and this profile's completion fallback behaves exactly as before.
|
|
# Every backend words its refusal differently, so this is config, never a
|
|
# vendor string baked into fleetd itself.
|
|
# HOT (fleetd #446): read live, cached by profile name, at every
|
|
# completion-fallback check AND by fleet_profiles' exhaustionDetectionArmed —
|
|
# editing it and reloading arms or disarms usage-limit detection for this
|
|
# profile with no daemon restart. (Before fleetd #446 this was DEFERRED,
|
|
# compiled once into a startup pattern map like model/baseUrl/argv still are —
|
|
# see errorPattern below, which is still deferred that way on purpose.)
|
|
# credentialId → CB-578 stage B: the credential this profile quarantines WITH when a
|
|
# BACKEND_EXHAUSTED classification fires. Two profiles that set the SAME
|
|
# credentialId share one quarantine — the case this exists for is two models
|
|
# on one account (e.g. sol and terra both billing one OpenAI credential): an
|
|
# exhaustion on either one must lock out both, or the fleet just walks onto
|
|
# the same dead account under the sibling's name. Opt-in — omit and this
|
|
# profile quarantines alone, under its own name, exactly as if the field did
|
|
# not exist. Cooldown length is the top-level quarantineCooldownSeconds below.
|
|
# HOT: read live at every spawn/exhaustion check — no restart needed.
|
|
# errorPattern → fleetd #201 / #227: regex matched against a completion-fallback scrape to
|
|
# classify a turn that ended with no fleet_reply as a BACKEND ERROR — a
|
|
# credential outage or a provider 5xx — rather than a real answer or a
|
|
# usage-limit exhaustion (exhaustedPattern above always wins when a line
|
|
# matches both). Opt-in. Omit it and this profile falls back to fleetd's
|
|
# built-in legacy pattern `(?i)\bAPI Error\s*:` — classification still
|
|
# happens, just without a profile-specific match; every backend words its
|
|
# failure differently, so a hardcoded sentence would only ever match one
|
|
# of them.
|
|
# DEFERRED: compiled once into a startup pattern map — editing it needs a
|
|
# daemon restart. Unlike exhaustedPattern above (made hot by fleetd #446),
|
|
# errorPattern was scoped out of that ticket on purpose and stays deferred.
|
|
# # errorPattern: "503 Service Unavailable" # opt-in: classify a backend outage
|
|
#
|
|
# What happens once a match fires (BackendOutagePolicy, credentialId-keyed,
|
|
# SEPARATE from the CB-578 stage B quarantine above and never merged with it):
|
|
# - threshold 2 — TWO DISTINCT TARGETS (never raw events) on the same
|
|
# effective credential inside a 60-second window start an "incident" and a
|
|
# 60-second cool-off for that credential. One member repeating the same
|
|
# classified line twice never cools anything off — a real outage hits
|
|
# every target on that credential, so requiring a second, independent
|
|
# target loses nothing against the case this guards against, while
|
|
# protecting against a heuristic misfire on one flaky member.
|
|
# - a fresh error while a credential is already cooling off is ignored
|
|
# outright: it neither extends the 60s deadline nor starts a new incident.
|
|
# - `fleet_list`/`fleet_profiles` report a cooling credential with
|
|
# `coolingOffForSeconds` (never `quarantinedForSeconds`, unless CB-578
|
|
# exhaustion quarantine is ALSO independently active for the same
|
|
# credential — the two checks can both fire at once). A spawn onto a
|
|
# cooling profile is refused with a message naming the credential and
|
|
# remaining seconds — "cooling off", never "exhausted", so an operator can
|
|
# tell a short transient fault from a spent subscription at a glance.
|
|
# - the lead gets ONE nudge per incident (not one per affected target), via
|
|
# the same push loop that already delivers ticket/question reminders.
|
|
# env → extra environment for this profile's workers, as a literal key/value map
|
|
# (CB-511). Use it to give workers a toolchain.
|
|
#
|
|
# A worker's environment does NOT come from your shell. fleetd hands herdr an
|
|
# explicit env map and herdr merges it into ITS OWN process env — so before
|
|
# CB-511 a worker inherited whatever PATH the herdr server happened to be
|
|
# started with, which on a long-lived herdr can predate your toolchain entirely
|
|
# and leave workers unable to run `mvn` or `java` at all.
|
|
# fleetd now propagates ITS OWN PATH to every worker by default; set `env:`
|
|
# only to override that or add more (JAVA_HOME, …). Since the default is the
|
|
# daemon's PATH, make sure the daemon is started with a good one — see the PATH
|
|
# lines in deploy/dev.ltms.fleet.plist and deploy/fleetd.service.
|
|
#
|
|
# Adapter-owned variables always win over `env:`: ANTHROPIC_BASE_URL and the
|
|
# rest of the ANTHROPIC_*/CLAUDE_* wiring are applied after it, so an `env:`
|
|
# entry cannot repoint a worker past the SubscriptionGuard — which is checked
|
|
# against `baseUrl` alone.
|
|
# Put `defaultMode: "auto"` in each ccs profile so the worker runs autonomously.
|
|
profiles:
|
|
gx10: # ccs profile name (NOT a hostname)
|
|
kind: claude-code # which adapter spawns this profile (default; may omit)
|
|
baseUrl: http://gx01.gw:8000 # the vLLM host this profile targets (gx00.gw / gx01.gw)
|
|
model: coder
|
|
placement: tab
|
|
workspace: fleetd-workers
|
|
# tabLabel: an optional per-profile override; the fleet template usually covers it
|
|
mcpUrl: http://127.0.0.1:8765/mcp
|
|
tokenEnv: FLEETD_WORKER_TOKEN
|
|
argv: ["ccs", "gx10"]
|
|
# weight: relative selection weight for automatic placement (weighted, round-robin, and
|
|
# fixed's fallback walk). Absent defaults to 1.0. An explicit 0 or negative value means
|
|
# "never auto-select this profile" (CB-554) — it stays reachable via an explicit
|
|
# `fleet_spawn{profile:"gx10"}`, which bypasses placement entirely; only automatic
|
|
# selection skips it.
|
|
weight: 0.5
|
|
# maxLoad: max live workers on this profile. Omit for unlimited. An explicit 0 (CB-585) caps
|
|
# the profile at zero live members — it is excluded from automatic placement and an explicit
|
|
# `fleet_spawn{profile:"gx10"}` against it is refused too; a cap holds even when the profile
|
|
# is named directly. Negative is refused at config load — there is no sane meaning for it.
|
|
maxLoad: 2
|
|
# subscription: true
|
|
# THE KNOB THAT DECIDES WHO PAYS (CB-539). Default false. When true, this profile's members
|
|
# run on the OPERATOR'S OWN Claude subscription instead of a metered endpoint — every spawn
|
|
# bills your plan and eats your usage limit. Off-subscription is the whole point of this
|
|
# daemon, so treat `true` as a deliberate exception, not a convenience.
|
|
#
|
|
# What changes when it is set (ClaudeCodeLauncher):
|
|
# - no ANTHROPIC_BASE_URL and no ANTHROPIC_AUTH_TOKEN are injected — the member inherits
|
|
# the operator's own Claude Code auth, which is exactly why it bills the plan;
|
|
# - SubscriptionGuard never vets it, because there is no baseUrl to vet;
|
|
# - no token is required, so `tokenEnv` is irrelevant here.
|
|
#
|
|
# MUTUALLY EXCLUSIVE with `baseUrl` — setting both is refused at config load (CB-542). On the
|
|
# subscription path no guard would vet the URL, so allowing both would be a way around the
|
|
# guard rather than a configuration.
|
|
#
|
|
# GOTCHA 1 — it is invisible to the startup secret check. `Fleetd.reportRequiredSecrets`
|
|
# skips subscription profiles on purpose (they need no token), so a boot log that reports
|
|
# every secret as fine says nothing about these profiles.
|
|
#
|
|
# GOTCHA 2 — `maxLoad` is the ONLY throttle you have here. There is no metering, no budget
|
|
# and no refusal on cost; the cap on live members is the single thing standing between a
|
|
# fan-out and your monthly limit. Set it deliberately and keep it small.
|
|
#
|
|
# GOTCHA 3 (fleetd #176, corrected by fleetd #257) — `maxLoad` counts members, never the lead
|
|
# itself. The lead is a live `claude` session on this SAME account (a lead is never moved
|
|
# off-subscription, whatever its own profile says), so it already holds one seat before any
|
|
# member spawns. If a lead's `fleet.leaders.<name>.profile` names THIS profile — or ANY OTHER
|
|
# `subscription: true` profile that shares this one's account (see THE SENTINEL, just below,
|
|
# next to `credentialId:`) — `fleet_list` reports that seat count under `leadSeats`; see
|
|
# `profile:` under THE FLEET below. `free` itself is NEVER reduced by `leadSeats`: `free` means
|
|
# "what the real placement gate (`CompositePeerLauncher#enforceMaxLoad`) will actually grant a
|
|
# fresh `fleet_spawn` right now", and that gate only ever compares live members against
|
|
# `maxLoad` — it has no notion of the lead's own seat. An earlier cut of this feature
|
|
# subtracted `leadSeats` from `free` on the theory it made `free` describe the true ceiling on
|
|
# the account, but no backend seat ceiling shared with the lead has ever actually been
|
|
# measured, and the subtraction just made `free` disagree with the one thing it is supposed to
|
|
# describe — the fleetd #257 fix. `maxLoad: 3` means 3 member slots, full stop; a lead sharing
|
|
# the account is a fact you can see in `leadSeats`, not a reason `free` undercounts spawns that
|
|
# will, in practice, succeed.
|
|
#
|
|
# THE SENTINEL (fleetd #176 stage 2, correcting an inert stage 1 fix): every `subscription:
|
|
# true` profile that leaves `credentialId` unset shares ONE implicit account-wide credential
|
|
# id with every other such profile on this host — because a subscription profile doesn't
|
|
# authenticate with a credential of its own, it authenticates as the operator's own Claude
|
|
# login, and there is exactly one of those. So on a typical host, `opus` (the lead's profile)
|
|
# and `sonnet` (the members' profile) are linked automatically, with NOTHING to set here — that
|
|
# is what makes GOTCHA 3 above work without also writing matching `credentialId:` values on
|
|
# both. This linkage is not just cosmetic: it is the same key `BackendQuarantine`/cool-off use,
|
|
# so a usage-limit hit on `opus` now quarantines `sonnet` too (and vice versa) — correct, since
|
|
# they are one Claude account, but worth knowing before you wonder why an unrelated-looking
|
|
# profile went quarantined.
|
|
#
|
|
# WHEN TO OVERRIDE — set explicit, DIFFERENT `credentialId:` values on two `subscription: true`
|
|
# profiles only when they are genuinely two separate Claude logins on the same host (a real,
|
|
# if unusual, setup). An explicit `credentialId` always wins over the sentinel, so this is the
|
|
# one way to keep two subscription profiles from being treated as one account for lead-seat
|
|
# counting AND for quarantine/cool-off grouping alike.
|
|
# gitTokenEnv: GITEA_TOKEN # opt-in: let this profile's workers open their own PR (CB-302)
|
|
# gitHostEnv: GITEA_HOST # defaults to GITEA_HOST; injected only with gitTokenEnv
|
|
# exhaustedPattern: "usage limit has been reached" # opt-in: classify a usage-limit refusal (CB-578)
|
|
# credentialId: shared-openai # opt-in: quarantine together with every other profile sharing this id (CB-578)
|
|
# errorPattern: "503 Service Unavailable" # opt-in: classify a backend outage (fleetd #201/#227) — see the key doc above
|
|
# configDir: /Users/me/.ccs/instances/gx10 # CLAUDE_CONFIG_DIR — inherit that profile's skills/MCP
|
|
# cwd: /Users/me/src/myrepo # pin the working dir; omit to inherit the primary's
|
|
# parityOverlay: [".env"] # the default; add ".envrc" explicitly if you want it copied too (CB-148) — never add .mcp.json or .claude/settings.local.json — see above
|
|
# ideMcpUrl: http://127.0.0.1:29170/index-mcp/streamable-http # opt-in (CB-634): IDE code intelligence, pinned to the worktree
|
|
# ideProjectDir: fleetd # CB-634: module dir the IDE opens + the overlay pins (this repo's pom is in fleetd/)
|
|
# ideOpenCommand: env DISPLAY=:10.0 idea {dir} # CB-634 auto-open: opens {dir} in the IDE at spawn; omit to open by hand
|
|
# autoCompactWindow: 250000 # opt-in: bound member context; claude-code compacts AT this, opencode within it (model limit.context)
|
|
gx11: # a second backend, so `placement: weighted` has a choice
|
|
baseUrl: http://gx01.gw:8000 # self-hosted; ccs handles the model + token
|
|
placement: tab
|
|
workspace: fleetd-workers
|
|
# tabLabel: an optional per-profile override; the fleet template usually covers it
|
|
mcpUrl: http://127.0.0.1:8765/mcp
|
|
argv: ["ccs", "gx11"]
|
|
weight: 0.5
|
|
maxLoad: 2
|
|
# Pin an auto-compact window BELOW the served model's context ceiling. The global
|
|
# ~/.claude/settings.json value is shared by every ccs instance and the primary, so the
|
|
# per-profile override belongs here. Equal to the ceiling means auto-compact never fires
|
|
# before the server rejects the prompt, which kills a worker mid-turn (CB-523).
|
|
env:
|
|
CLAUDE_CODE_AUTO_COMPACT_WINDOW: "280000"
|
|
# CB-402: a second coding-agent kind, proving the PeerLauncher SPI is provider-neutral.
|
|
# opencode is provider-agnostic and uses NONE of Claude's private seams: no ANTHROPIC_BASE_URL /
|
|
# SubscriptionGuard (so it needs no `guard` host entry), no --mcp-config / --append-system-prompt.
|
|
# The bridge MCP + reply charter mount via a generated OPENCODE_CONFIG file, and the model is a
|
|
# `provider/model` selector. Placement, tabs, cwd, and the readiness gate are shared with Claude.
|
|
#
|
|
# Dogfood-verified 2026-07-29 against opencode 1.18.5 (spawn → readiness gate → fleet_send →
|
|
# structured fleet_reply → teardown). The `opencode/*-free` models run on opencode's own gateway
|
|
# and need NO credentials — check `opencode models` for the current free list, since the names
|
|
# change. That also makes the worker off-subscription by construction.
|
|
# opencode-free:
|
|
# kind: opencode
|
|
# model: opencode/north-mini-code-free # `provider/model` selector, injected as `-m`
|
|
# placement: tab
|
|
# workspace: fleetd-workers
|
|
# tabLabel: "opencode: {profile} #{n}"
|
|
# mcpUrl: http://127.0.0.1:8765/mcp
|
|
# argv: ["opencode"]
|
|
#
|
|
# CB-508: point an opencode profile at your OWN OpenAI-compatible endpoint (local vLLM, llama.cpp,
|
|
# LM Studio, TGI…) instead of opencode's gateway. Setting `baseUrl` on a `kind: opencode` profile
|
|
# makes the bridge emit a custom `provider` block into the generated opencode.json — opencode has
|
|
# no ANTHROPIC_BASE_URL seam, so this is how the endpoint is pinned.
|
|
# baseUrl → a bare host:port gets `/v1` appended (where these servers mount the API); a URL that
|
|
# already has a path is used verbatim, so a custom mount point still works.
|
|
# model → MUST be "<provider>/<model>". The provider half names the generated block; the model
|
|
# half must match an id the server reports at /v1/models. One field drives both the
|
|
# declaration and the `-m` flag, so they cannot drift apart. A bare model name with a
|
|
# baseUrl set is rejected at spawn rather than silently using the default gateway.
|
|
# tokenEnv → optional; its value becomes the provider apiKey. Most local servers ignore the key,
|
|
# so a placeholder is used when unset (the AI SDK still requires a non-empty one).
|
|
# NOTE: no `guard` entry is needed even with a baseUrl set. The SubscriptionGuard exists to stop a
|
|
# worker borrowing the primary's Anthropic subscription, and an opencode process has no Anthropic
|
|
# credential path at all.
|
|
# opencode-local:
|
|
# kind: opencode
|
|
# baseUrl: http://127.0.0.1:8000
|
|
# model: local-vllm/deepseek-v4-flash
|
|
# placement: tab
|
|
# workspace: fleetd-workers
|
|
# tabLabel: "opencode: {profile} #{n}"
|
|
# mcpUrl: http://127.0.0.1:8765/mcp
|
|
# argv: ["opencode"]
|
|
# How an unqualified spawn chooses a profile: fixed (default, reproduces pre-CB-518 behaviour),
|
|
# round-robin, or weighted. Omitting this key is a strict no-op for existing configs.
|
|
#
|
|
# `weighted` IS NOT "cheapest first" — read this before you set weights (CB-589).
|
|
# It is smooth weighted round-robin: it spreads spawns across EVERY profile that has a free slot,
|
|
# in weight ratio. It has no idea which profile costs money. So with local:10 / paid:2 you do not
|
|
# get "use local, overflow to paid" — you get roughly one spawn in six going to the paid profile
|
|
# while the local box still has a free slot.
|
|
#
|
|
# There is a sharper second effect. The policy's running score map lives for the daemon's whole
|
|
# life. While a profile is at maxLoad it is filtered out and its score FREEZES, so the paid
|
|
# profiles keep accumulating against it. When the local slot frees up it returns with a stale
|
|
# score and can LOSE the next pick — a paid spawn while the free box sits idle.
|
|
#
|
|
# Until a real cost-first policy exists, the workaround is to make the ratio decisive rather than
|
|
# proportional: give the free profile a weight so large that it wins every pick it is eligible
|
|
# for, and paid profiles only ever take genuine overflow. On this host that is local weight 100
|
|
# against paid weights of ~1.
|
|
#
|
|
# The gotcha with that workaround: it expresses a PREFERENCE ORDER through a RATIO knob. Add a
|
|
# future profile at weight 150 and it silently outranks the free box, with nothing to warn you.
|
|
# Re-check the weights whenever you add a profile.
|
|
placement: weighted
|
|
|
|
# How long a credential sits out after a BACKEND_EXHAUSTED classification (CB-578 stage B), in
|
|
# seconds, before a spawn may land on it again. Applies to every profile's effective credential
|
|
# (its own name, or its credentialId if set above) — there is no per-profile override. Default
|
|
# 1800 (30 minutes) when omitted or non-positive.
|
|
#
|
|
# fleetd #466: this is now only the BASE of an escalating backoff, not a flat retry rate. A
|
|
# credential quarantined again within one base cooldown of the previous quarantine ending (still
|
|
# reporting exhausted — e.g. a weekly subscription limit that hasn't reset) backs off further:
|
|
# cooldown doubles each such time, capped at 12x this value (~6 hours at the 1800s default). A
|
|
# quarantine that starts after a base-cooldown's worth of quiet resets back to this value. Not
|
|
# configurable per se — the multiplier and ceiling are constants in BackendQuarantine, not new
|
|
# YAML keys; see its class doc for the exact formula and why there is no automatic probe to clear
|
|
# it early (the operator's own design constraint — a probe spends the quota it's measuring).
|
|
# DEFERRED: baked once into the BackendQuarantine built at startup — a running quarantine keeps
|
|
# its original cooldown regardless; a new value only applies to a quarantine that starts after a
|
|
# restart. Editing this needs a daemon restart to take effect.
|
|
#
|
|
# This does NOT govern the fleetd #201 / #227 backend-error cool-off documented under errorPattern
|
|
# above — that mechanism is a separate, shorter-lived, NOT-configurable policy (threshold 2 distinct
|
|
# targets, 60-second window, 60-second cool-off), on purpose: it exists to survive a brief transient
|
|
# fault, not to replace this 30-minute exhaustion quarantine. Do not conflate the two when reading
|
|
# fleet_list/fleet_profiles — coolingOffForSeconds and quarantinedForSeconds are independent facts.
|
|
# quarantineCooldownSeconds: 1800
|
|
|
|
# Re-read this file without restarting the daemon (CB-559). Off unless you add this block, so an
|
|
# upgraded fleetd keeps the old behaviour: the file is read once at boot and never again.
|
|
# enabled → turn the watch on. fleetd checks the file's modified time on a timer and
|
|
# reloads when it moves.
|
|
# intervalSeconds → how often to check (default 10). One `stat` per tick, so this is cheap.
|
|
#
|
|
# Not every key can move under a running daemon, and the difference is about what already exists
|
|
# when the reload happens — not about how important the key is:
|
|
# HOT → takes effect on the next spawn: the whole `fleet:` block (every role pool,
|
|
# `charters`, and `tabLabel`), `placement:`, and an existing profile's weight / maxLoad
|
|
# / credentialId / exhaustedPattern. Those are hot because the placement policy (and,
|
|
# for credentialId, the CB-578 stage B quarantine check; for exhaustedPattern, fleetd
|
|
# #446's LiveExhaustedPatterns) reads them through a supplier — being config is not by
|
|
# itself enough to make a key hot.
|
|
# EXCEPT `fleet.leaders`: Fleetd.main reads it once at startup to build the lead tab
|
|
# scanner and launcher, and neither is rebuilt on reload. A changed/added/removed
|
|
# `fleet.leaders` entry is silently accepted — the reload reports "config reloaded"
|
|
# with nothing in the deferred list — but has NO effect until you restart. Treat it
|
|
# as deferred in practice, even though today's reload output does not say so.
|
|
# DEFERRED → accepted into the new config, but the wiring built at startup keeps the old value
|
|
# until you restart: `lifecycle:`, `leadHeartbeat:`, `guard:`, `worktreeRoot:`,
|
|
# `spawnReadyTimeoutMs` / `spawnReadyPollMs`, `quarantineCooldownSeconds` (CB-578
|
|
# stage B — baked once into the quarantine tracker built at startup), ADDING or
|
|
# REMOVING a profile (a new backend needs its own launcher, and launchers are built
|
|
# once), AND an existing profile's launch settings — model, baseUrl, argv, env,
|
|
# configDir, mcpUrl, tabLabel, errorPattern (fleetd #201 / #227 — compiled once into
|
|
# a startup pattern map; exhaustedPattern used to be compiled the same way until
|
|
# fleetd #446 made it hot — see above). The launcher takes a copy of `profiles:` at
|
|
# startup and resolves every spawn out of that copy, so those never
|
|
# reach a launch until you restart. The reload logs them by name rather than
|
|
# pretending they applied.
|
|
# COLD → cannot change at all: `bind:`, `herdrSocket:`, `broker:` and `auth:`. The socket is
|
|
# bound, the broker connection is open, and the auth mode decides who may reach the
|
|
# port that is already listening.
|
|
#
|
|
# A changed COLD key refuses the WHOLE reload — not the hot half applied and the cold half warned
|
|
# about. A half-applied reload would leave the daemon matching no file on disk, which is the worst
|
|
# thing a reload can do to an operator debugging one. A file that fails to parse or fails a startup
|
|
# validator is refused the same way, and the running config stays live.
|
|
# configReload:
|
|
# enabled: true
|
|
# intervalSeconds: 10
|
|
|
|
# THE FLEET (CB-557) — who the daemon may run, and under which role. This one block replaced four
|
|
# older keys: `leaders:`, `members:`, `leadScan:` and `defaultProfile:`.
|
|
#
|
|
# A member is anything a lead spawns, and every member has two INDEPENDENT attributes:
|
|
# role — which contract: architect, dev or reviewer. It picks the launch charter, the role
|
|
# file, the playbook skill and the authz row.
|
|
# profile — which backend: one of the `profiles:` keys above (model, CLI adapter, cost).
|
|
# They vary on their own. A reviewer may run on the same profile as the dev whose diff it reads,
|
|
# which is why the two cannot be one field.
|
|
#
|
|
# The ROLE IS THE CONTAINING KEY, not a `role:` field. That is not only tidier: a misspelled role
|
|
# used to parse into a member with no contract at all, while a misspelled pool name here simply
|
|
# declares nothing.
|
|
#
|
|
# Each pool lists the profiles that role MAY run on — these are pools, not identities. That is also
|
|
# what replaced `defaultProfile:`: an unqualified spawn names a role, and that role's pool supplies
|
|
# the candidates, in definition order. A dev and a reviewer staying anonymous is exactly compatible
|
|
# with being listed here; the entry key just names the entry.
|
|
fleet:
|
|
# Optional launch-charter text, keyed only by the singular role wire names: architect, dev,
|
|
# reviewer. Changes are HOT and reach the next spawn without a daemon restart. Do not put secrets
|
|
# here: a later launch step writes this text to a world-readable temp file, and ${ENV} interpolation
|
|
# is deliberately not supported.
|
|
charters:
|
|
architect: |-
|
|
You are an architect in this fleet. You refine work before anyone builds it:
|
|
scope, acceptance criteria, risks, and a unit split. You read the repo and
|
|
write analysis. You never commit production code and never open a PR.
|
|
A design task is worked by two architects. Design alone first, then exchange
|
|
and say plainly where you disagree. Do not concede just to agree.
|
|
dev: |-
|
|
You implement the one unit you were given, and nothing else. You test it,
|
|
commit it, and open your own pull request. You never merge.
|
|
reviewer: |-
|
|
You review the diff you were given. You report bugs, risks and missing tests.
|
|
You do not change code.
|
|
|
|
# Optional. Template for a member tab's label; {role}, {profile}, {model} and {n} are substituted.
|
|
# {n} counts per role+profile, so `dev: sonnet #2` really is the second sonnet dev. Because {role}
|
|
# comes from a closed enum, a generated label can never begin with a lead's tabPrefix.
|
|
# tabLabel: "{role}: {profile} #{n}"
|
|
|
|
# Panes that orchestrate rather than are orchestrated. A lead may now be CREATED as well as
|
|
# recognised: give it a `profile:` and the daemon launches the shortfall when fewer than
|
|
# `instances` are live. Omit `profile:` and it is recognise-only, as before.
|
|
#
|
|
# `profile:` has a SECOND job as of fleetd #176, even for a recognise-only lead you never want
|
|
# auto-launched: it is also how fleetd learns which account this lead's own session shares. A
|
|
# `subscription: true` profile bills the operator's Claude account, and the lead itself is always
|
|
# a live `claude` session on that same account — `maxLoad` never counted that seat. If a lead
|
|
# entry here names a profile that shares a worker profile's account, `fleet_list` reports the
|
|
# lead's live seat(s) on that worker profile under `leadSeats` — informational only, as of fleetd
|
|
# #257 it is NEVER subtracted from `free` (see GOTCHA 3, next to `maxLoad:`, in THE WORKERS above,
|
|
# for why). "Shares the account" is decided by matching `effectiveCredentialId()`, which (fleetd
|
|
# #176 stage 2 — see THE SENTINEL, next to `credentialId:`, in THE WORKERS above) means: an
|
|
# explicit, matching `credentialId:` on both, OR — the common case, needing NO extra config — both
|
|
# being `subscription: true` with `credentialId` left unset, since those all share one implicit
|
|
# account-wide id. A lead on `opus` and workers on `sonnet` link automatically this way; they do
|
|
# NOT need the same profile name. Setting `profile:` on an already-running, recognise-only lead is
|
|
# safe — the daemon only launches the SHORTFALL below `instances`, so naming a profile here does
|
|
# not, by itself, start anything. Omit it and fleetd has no way to derive the sharing — there is
|
|
# no other reliable signal on the daemon's side — so that lead's seat never appears in `leadSeats`.
|
|
#
|
|
# `tab:` (CB-579) is REQUIRED and is the only field identity depends on — the exact label of the
|
|
# tab hosting the lead, matched case-insensitively. Label the tab yourself and put that same
|
|
# string here, and the pane is recognised on the next rescan. Reopen the tab later, or the session
|
|
# inside it restarts — the terminal id changes; the tab, and its label, do not, so no config edit
|
|
# follows a restart.
|
|
#
|
|
# A lead the daemon launches is labelled BY the daemon with this same `tab:` value, so it is found
|
|
# by the same scan. A lead counts as live only when herdr also reports a running agent in that
|
|
# tab — a label left behind by a session that died does not block the relaunch, and a tab that is
|
|
# gone entirely drops out of the next scan rather than being remembered forever.
|
|
#
|
|
# An auto-launched lead is NOT a member: it gets no worker reply charter, is never registered with
|
|
# the session lifecycle (the idle reaper would kill your orchestrator), and stays on the
|
|
# subscription — ANTHROPIC_BASE_URL/AUTH_TOKEN are stripped from its env whatever the profile says.
|
|
#
|
|
# GET THE `tab:` VALUE RIGHT. A pane that does not match any configured `tab:` (a typo, a renamed
|
|
# tab, a pane no entry names at all) is not recognised as a lead — it resolves as an ordinary
|
|
# WORKER instead, silently, and every orchestration call it makes (spawn/stop/send/drain) is
|
|
# refused. There is no error at startup for this: an unmatched pane is simply not a lead. If your
|
|
# primary suddenly can't spawn or send, check this section first.
|
|
# leaders:
|
|
# opus-5.0:
|
|
# profile: opus # omit to never create this lead, only recognise it
|
|
# instances: 1 # desired live count; only the shortfall is launched. 0 = off
|
|
# tab: "lead: opus-5.0" # REQUIRED — the exact tab label this lead lives in
|
|
# tabPrefix: "lead:" # only used to guard against a worker tabLabel colliding with
|
|
# # this convention at startup; plays no part in matching a lead
|
|
# scanIntervalSeconds: 10 # rescan cadence, and the worst case before a new tab is seen
|
|
# workspace: leads # where a launched lead's tab is created (default "leads").
|
|
# # MUST NOT be a member workspace — those are excluded from the
|
|
# # scan, so a lead placed in one is never found again.
|
|
# cwd: /path/to/repo # the launched lead's working directory (default: fleetd's own)
|
|
# kind: claude # descriptive; reported by fleet_whoami
|
|
# gpt-sol-5.6:
|
|
# tab: "lead: gpt-sol-5.6"
|
|
# kind: opencode
|
|
# model: openai/gpt-5.6-terra
|
|
|
|
# architects:
|
|
# architect-1:
|
|
# profile: opus # a strong model, on the operator's subscription
|
|
# architect-2:
|
|
# profile: sol # a different vendor on purpose — two architects that share a
|
|
# # model share its blind spots
|
|
developers:
|
|
gx10:
|
|
profile: gx10
|
|
# reviewers:
|
|
# gx10:
|
|
# profile: gx10 # the same backend may serve two roles; that is the point
|
|
|
|
# Subscription boundary. A worker's base_url host MUST be one of these; the primary
|
|
# must carry none. Every profile above must have its host listed here.
|
|
guard:
|
|
offSubscriptionHosts:
|
|
- gx00.gw
|
|
- gx01.gw
|
|
|
|
# Member credential policy (CB-596, gitea issue #82). A herdr pane runs a LOGIN shell, and that
|
|
# shell re-sources the operator's own secret store — so a spawned member inherits every credential
|
|
# the operator's shell holds, not just the ones fleetd means to give it. Measured on this host:
|
|
# 31 credential names, all set, with only ONE (GITEA_ACCESS_TOKEN) blocked before this — and that
|
|
# block was a single name hardcoded in HerdrPeerLauncher.java, not driven by this file. This block
|
|
# replaces that hardcoded shadow with a config-driven list of names.
|
|
#
|
|
# ROUND-2 CORRECTION, measured live: the pane-creation env overlay below (applied at tab.create /
|
|
# pane.split, BEFORE the pane's login shell runs) does NOT survive that login shell for any name
|
|
# secrets.sh actually exports — the shell re-exports it afterwards and overwrites the sentinel.
|
|
# Proof: GITEA_ACCESS_TOKEN comes back blocked only because secrets.sh itself carries a guarded
|
|
# export (`[ -n "${BRIDGED_MEMBER:-}" ] || export GITEA_ACCESS_TOKEN=...`) — that guard, not this
|
|
# file, is what wins. No other name in `known` below has a matching guard in secrets.sh yet (1
|
|
# guard measured against 33 export lines there). So today this block's overlay is REAL protection
|
|
# only for a name secrets.sh does not export, or a peer kind whose pane never runs a login shell —
|
|
# for everything secrets.sh exports and guards, the guard in secrets.sh (out of scope for this
|
|
# ticket) is what actually blocks it, not this list. An exec-time fix (winning after the login
|
|
# shell finishes, before the agent process starts) was attempted and found to have no seam in the
|
|
# current herdr protocol — AgentControl.start takes a fixed `kind` (herdr resolves the executable)
|
|
# plus trailing CLI args for that binary, not an arbitrary argv or an env map; only tab.create /
|
|
# pane.split accept `env`, and that is this same pane-creation overlay. See gitea #82 for the open
|
|
# design question this leaves.
|
|
#
|
|
# DENY-BY-DEFAULT, NOT A DENY-LIST. A deny-list (name the bad ones, let everything else through) is
|
|
# silently wrong the moment the operator's store gains a new secret — nothing would ever report it.
|
|
# Deny-by-default inverts that: `known` bounds the blast radius to names actually enumerated below,
|
|
# and EVERY one of them is blocked UNLESS it is also in `allow`. Omitting this block entirely (the
|
|
# shipped default) blocks NOTHING — unlike most optional blocks in this file, absence here is a real
|
|
# gap, not a safe "feature off". A name that is neither `known` nor `allow`-ed is not silently let
|
|
# through either: the daemon logs a WARN naming any credential-shaped env var it finds on neither
|
|
# list (never its value), so a secret added to the store later does not go unnoticed forever.
|
|
#
|
|
# policy → "deny-by-default" (the default; also accepted spelled "deny-list") overlays each
|
|
# known-but-not-allowed name BEFORE the pane's login shell runs — real protection only
|
|
# where that shell does not re-export the name (see ROUND-2 CORRECTION above). An
|
|
# unrecognized value refuses to start, naming it.
|
|
# policy → "allow-list" (CB-633) moves the control to a per-spawn ZDOTDIR directory the daemon
|
|
# generates and passes through tab.create's env map. Each generated startup file sources
|
|
# its ~/ counterpart FIRST and then runs the scrub, so the scrub happens after the
|
|
# operator's whole chain and no sourced file can undo it.
|
|
# The scrub is sourced from BOTH the generated .zshrc and the generated .zlogin, because
|
|
# herdr does not open the same kind of shell everywhere: macOS panes run a LOGIN zsh (so
|
|
# .zlogin runs), Linux panes run a plain interactive zsh (so .zlogin never runs at all).
|
|
# A scrub in .zlogin alone would be a control that silently does nothing on Linux.
|
|
# The allow-list is DERIVED, never typed:
|
|
# every profile's tokenEnv/gitTokenEnv/gitHostEnv values and env-map keys, plus an
|
|
# infrastructure set (PATH HOME SHELL TERM LANG LC_* TMPDIR USER LOGNAME PWD SHLVL EDITOR
|
|
# PAGER JAVA_HOME XDG_* ZDOTDIR), plus whatever keys this spawn's own env overlay carries.
|
|
# Adding a profile can therefore only widen the list, never break another spawn's scrub.
|
|
# Under this policy `known`/`allow` below become REPORTING ONLY — they feed the gap WARN,
|
|
# they are no longer a control. If the member's login shell is NOT zsh, the daemon logs a
|
|
# loud WARN saying protection is off and falls back to deny-by-default's overlay.
|
|
# Each pane writes a scrub-report.txt naming how many variables it kept of how many it
|
|
# saw; the daemon logs that "allowed N of M" line when the pane stops. If the report is
|
|
# MISSING the daemon logs a WARN instead — the scrub cannot then be confirmed to have
|
|
# run, and a silently-dead control is exactly what this policy exists to prevent.
|
|
# allow → credential names a member legitimately needs. Under deny-by-default, left OUT of the
|
|
# pane's env overlay entirely, so the value the pane's own (login) shell exports passes
|
|
# through untouched. Under allow-list: reporting only.
|
|
# known → every credential name the operator's store is known to export. Under deny-by-default,
|
|
# every name here NOT also in `allow` is overlaid with a non-secret sentinel value before
|
|
# the pane's login shell runs — real protection only for names that shell does not itself
|
|
# re-export (see the ROUND-2 CORRECTION note above). Under allow-list: reporting only.
|
|
# sshAgentEnv → whether SSH_AUTH_SOCK may pass through under allow-list ("inherit") or is omitted
|
|
# from the member environment ("omit", the default). Omitting it only omits the
|
|
# inherited ssh-agent path. It discourages automatic use of the operator's agent.
|
|
# It does not deny same-user access to that socket. It also does not block SSH keys that
|
|
# are readable on disk. Git over SSH may still work from inside a member. Keep the block:
|
|
# it is correct and costs nothing, but it is not a control. A member runs as the same OS
|
|
# user as the lead. Inside one uid, ordinary Unix permissions provide no meaningful
|
|
# confidentiality boundary. A real boundary needs a different OS user or OS-level
|
|
# confinement, such as a container or VM. That is the open question in fleetd #184.
|
|
#
|
|
# Still do not set this to "inherit" casually. SSH_AUTH_SOCK is a live handle to YOUR
|
|
# ssh-agent, so a member holding it can sign with EVERY key the agent holds. It sits in
|
|
# no secret file and looks like no credential, which is why it slipped past three
|
|
# earlier tickets (gitea #110). Blocking it does not contain a member, but allowing it
|
|
# hands one a signing capability for no gain — the block costs nothing, so keep it.
|
|
#
|
|
# Both halves of this are measured, not argued. 2026-08-28: a member with
|
|
# SSH_AUTH_SOCK blanked pushed to the forge over SSH successfully, because `ssh -G`
|
|
# resolves an IdentityFile outside ~/.ssh that is readable and has no passphrase. An
|
|
# earlier version of this comment claimed blocking the socket BREAKS git over SSH. It
|
|
# does not. That claim came from looking only in ~/.ssh, which holds nothing but four
|
|
# `Include` lines — looking in one place and concluding about the whole host.
|
|
#
|
|
# HOT-RELOADABLE the same way `fleet:` is (CB-559): read fresh on every spawn, so editing this list
|
|
# and reloading config (or restarting) changes what the NEXT spawn inherits; already-running members
|
|
# are unaffected either way.
|
|
# memberCredentials:
|
|
# policy: deny-by-default # or "deny-list", or "allow-list" (CB-633) — see above
|
|
# sshAgentEnv: omit # allow-list only; see the sshAgentEnv note above
|
|
# allow:
|
|
# - AI_GATEWAY_TOKEN # named in a profile's tokenEnv (local/gx) — a member reaching the
|
|
# # gateway is by design, not a leak
|
|
# - WORKER_GITEA_TOKEN # the repo-scoped forge token a member needs to open its own PR (CB-302)
|
|
# - CONTEXT7_TOKEN # already decided as allowed by CB-593
|
|
# - GITEA_HOST # not a credential — a hostname, paired with the forge token above
|
|
# known:
|
|
# - AI_GATEWAY_TOKEN
|
|
# - BESZEL_ADMIN_EMAIL
|
|
# - BESZEL_ADMIN_PASSWORD
|
|
# - BESZEL_HUB_URL
|
|
# - BESZEL_KEY
|
|
# - BESZEL_UNIVERSAL_TOKEN
|
|
# - BRAIN_MCP_TOKEN
|
|
# - CF_ACCOUNT_ID
|
|
# - CF_API_TOKEN
|
|
# - CF_USER_TOKEN
|
|
# - CONFLUENCE_API_TOKEN
|
|
# - CONFLUENCE_USERNAME
|
|
# - CONTEXT7_TOKEN
|
|
# - GITEA_ACCESS_TOKEN
|
|
# - GITEA_HOST
|
|
# - GITLAB_OAUTH_CLIENT_SECRET
|
|
# - GITLAB_PERSONAL_ACCESS_TOKEN
|
|
# - GRAFANA_ADMIN_PASSWORD
|
|
# - GRAFANA_ADMIN_USER
|
|
# - HASS_TOKEN
|
|
# - HW_PASSWORD
|
|
# - HW_USER
|
|
# - LTMS_API_KEY
|
|
# - MEMORY_MCP_TOKEN
|
|
# - METRICS_PUSH_TOKEN
|
|
# - OPENCODE_AUTOMODE_MODEL
|
|
# - TELEGRAM_BOT_TOKEN
|
|
# - TELEGRAM_CHAT_ID
|
|
# - TS_API_KEY
|
|
# - TS_AUTHKEY
|
|
# - WORKER_GITEA_TOKEN
|
|
|
|
# Spawn-readiness gate (CB-306). The launcher blocks until the worker's herdr status is
|
|
# injectable (IDLE/BLOCKED/DONE) or the timeout elapses. 0 disables the gate.
|
|
# NOTE: keys are camelCase — config is bound by plain Jackson with no naming strategy and
|
|
# unknown keys are ignored, so a snake_case key would be silently dropped (default kept).
|
|
# spawnReadyTimeoutMs: 20000
|
|
# spawnReadyPollMs: 300
|
|
|
|
# Worktree provisioning root (CB-301-ext). Where per-worker git worktrees are checked out so
|
|
# each worker owns an isolated branch instead of sharing the primary's tree. Omit to default
|
|
# to a sibling directory of the repo root.
|
|
# worktreeRoot: /Users/me/src/.bridged-worktrees
|
|
|
|
# Worktree group sharing (fleetd #185 stage 3). OPTIONAL, off by default. Names an OS group
|
|
# that a provisioned worktree's repo is made group-writable for (git config
|
|
# core.sharedRepository group, plus a one-time chgrp/chmod/setgid fix-up), so a member spawned
|
|
# under a DIFFERENT OS user (see memberHerdrSocket) can write its own worktree, its
|
|
# per-worktree git metadata, and its own commit objects — without it, every file GitWorktrees
|
|
# creates is owned by fleetd's own uid and unwritable by another user.
|
|
# CAUTION: this isolates credentials, not the repository — a member in the group can still
|
|
# write the operator's git objects and refs in the shared repo. The operator running fleetd
|
|
# must already be a member of the named group, or every provisioning spawn fails loudly.
|
|
#
|
|
# fleetd #213: this is also the ONE group the memberCredentials.policy: allow-list ZDOTDIR scrub
|
|
# reuses when memberHerdrSocket is set — deliberately not a second config key. Under
|
|
# memberHerdrSocket, the scrub directory is generated under worktreeRoot (never java.io.tmpdir,
|
|
# which the member OS user cannot reach) and shared read-only with this group. If worktreeGroup
|
|
# is unset while memberHerdrSocket is set, the scrub cannot be guaranteed reachable by the member,
|
|
# so fleetd falls back to the weaker CB-596 sentinel overlay instead (a WARN names the gap).
|
|
# worktreeGroup: fleet-workers
|
|
|
|
# fleetd #362: a directory of skill folders (each a subdirectory holding a SKILL.md, the same
|
|
# shape as this repo's own .claude/skills/) copied into every PROVISIONED worktree's
|
|
# .claude/skills/, so a member spawned against ANY repo — not only one that already ships its own
|
|
# copy — can load a bridge skill (e.g. implementer). Unset (the default): no worktree is touched
|
|
# beyond today's behaviour. A skill folder the target repo already carries under
|
|
# .claude/skills/<name> is never overwritten — the repo's own copy always wins. Best-effort like
|
|
# worktreeGroup above: a missing/unreadable directory here is logged and skipped, never a failed
|
|
# spawn. Every non-hidden subdirectory of this directory is copied wholesale, with no per-file
|
|
# allowlist — don't park scratch files or drafts alongside the real skill folders, they will be
|
|
# copied into every provisioned worktree too.
|
|
#
|
|
# fleetd #393: which member KINDS actually consume this once it is copied. kind: claude-code —
|
|
# the Claude Code CLI discovers .claude/skills/ on its own; nothing else is needed. kind: opencode
|
|
# — opencode has no such discovery, so OpenCodeLauncher reads whatever landed under
|
|
# .claude/skills/ and appends each seeded skill's SKILL.md to the generated instructions[] file
|
|
# (opencode's only channel for static guidance text; unlike Claude Code's Skill tool, the content
|
|
# is always part of the system prompt, not loaded on demand). Both kinds are covered as of #393 —
|
|
# earlier builds copied the files for every kind but only claude-code could read them, and the
|
|
# seeding log said "N of M" regardless. Check the per-spawn launcher log (not just the seeding
|
|
# log) to see what a given member actually got.
|
|
# memberSkills: /path/to/fleetd/checkout/.claude/skills
|
|
|
|
# Session lifecycle limits (CB-303). All knobs are opt-in; omit or set to null to keep
|
|
# the feature disabled. By default the daemon never reaps, caps, or drains sessions.
|
|
# idleTtlSeconds → reap READY/DONE sessions idle longer than this (never BUSY/SPAWNING)
|
|
# contextCap → force-release a session after this many delegated turns
|
|
# drainTimeoutSeconds → seconds to wait for BUSY sessions on shutdown before forced teardown
|
|
# clearAfterTurn → whether a reusable worker discards its conversation context after every
|
|
# completed delegated turn (default false). Works for claude-code workers
|
|
# only — any other peer kind (e.g. opencode) logs "context reset is
|
|
# unsupported for peer kind …" once and the reset is a no-op.
|
|
# lifecycle:
|
|
# idleTtlSeconds: 300
|
|
# contextCap: 10
|
|
# drainTimeoutSeconds: 5
|
|
# clearAfterTurn: false
|
|
|
|
# Durable reply delivery (CB-307 Stage 2). OMIT this block entirely to keep the default
|
|
# in-memory, soft-state reply inbox (late worker replies are held only until a daemon bounce).
|
|
# Set a broker uri to swap in the AMQP-backed inbox: worker replies with no open send are held
|
|
# on a durable per-target queue (agent.<target>.inbox) and survive a restart — the broker
|
|
# redelivers anything the primary had not yet drained. Production default is LavinMQ; a stock
|
|
# RabbitMQ speaks the same AMQP 0-9-1, so it is a URI-only swap.
|
|
# uri → AMQP connection URI. No trailing slash ⇒ the default vhost "/"; an empty path ("/")
|
|
# is vhost "" and will NOT connect. Encode a named vhost as .../%2Fmyvhost.
|
|
# uriEnv → CB-151: name of a host env var holding the AMQP URI, preferred over `uri` (wins
|
|
# whenever set). The URI carries `user:pass@` inline, so naming a variable keeps the
|
|
# password out of fleetd.yaml — same pattern as auth.tokenEnv/Profile.tokenEnv. A
|
|
# uriEnv that resolves to an unset or blank variable is treated as NOT configured and
|
|
# the daemon falls back to the in-memory inbox, warning loudly.
|
|
# prefetch → CB-527: consumer basicQos, capping how many unacked messages the inbox holds
|
|
# in-heap per owned target (the rest sits on the broker's durable queue instead of
|
|
# growing the JVM heap). Default 32 when omitted.
|
|
# broker:
|
|
# uriEnv: LAVINMQ_URI
|
|
# prefetch: 32
|
|
|
|
# Shared cross-host LEADER coordination broker. OMIT this block to leave lead-to-lead messaging
|
|
# off entirely (config-only in this ticket — nothing here wires it into a live LeadMailbox yet).
|
|
# This is a SEPARATE AMQP vhost from `broker:` above: member/worker inboxes always stay on the
|
|
# per-fleet `broker:` vhost, and this vhost carries only leader-to-leader traffic, so two fleets
|
|
# whose members must never see each other can still share one coordination vhost for their leads.
|
|
# uriEnv → name of a host env var holding the coordination AMQP URI, same convention as
|
|
# broker.uriEnv (keeps the credential out of fleetd.yaml). Wins over `uri` when set.
|
|
# selfId → this daemon's own lead coord-id — the name its mailbox is owned under
|
|
# (lead.<selfId>.inbox), e.g. "mac-opus" or "fleet01-lead". Must be globally unique
|
|
# across every daemon sharing this vhost.
|
|
# prefetch → consumer basicQos, capping how many unacked messages the mailbox holds in-heap.
|
|
# Default 32 when omitted.
|
|
# peers → fleetd #361: the coord-ids of the OTHER daemons on this vhost, declared by the
|
|
# operator (the daemon never guesses). fleet_list reports each one's live reachability
|
|
# (a passive queue check, never a presence protocol) alongside this daemon's own
|
|
# mailbox state. Omit, or leave empty, for a daemon with no known peers yet — an
|
|
# undeclared peer can still reach you and be reached by fleet_send, it just will not
|
|
# show up as a row in fleet_list.
|
|
# coordinator:
|
|
# uriEnv: LEAD_COORD_URI
|
|
# selfId: mac-opus
|
|
# prefetch: 32
|
|
# peers: [fleet01-lead]
|
|
|
|
# Active push-to-primary (CB-307 Stage 3). When a worker reply lands with no open fleet_send,
|
|
# the ReplyPushLoop injects a *drain nudge* (never the payload) into the primary's own herdr
|
|
# pane — status-gated (only when injectable, never mid-turn) and bounded. Ack = drain: the loop
|
|
# stops as soon as the primary's inbox is empty.
|
|
# terminal → pin the primary's herdr terminal id. Omit to learn it from the connection on
|
|
# the first orchestration-side MCP call (the normal case). An off-host or
|
|
# non-herdr primary leaves this unresolved → the loop is a no-op and delivery
|
|
# degrades to pull; the reply is still never lost.
|
|
#
|
|
# REQUIRED (CB-522) if the primary itself runs inside a herdr pane. Caller
|
|
# identity resolves a loopback PID to its herdr pane, and PaneLocator scans
|
|
# EVERY pane — not just fleetd-spawned ones — so such a primary is otherwise
|
|
# classified as a WORKER and refused SPAWN/SEND/STOP. That failure is
|
|
# self-locking: the learned terminal is populated by the very orchestration
|
|
# calls being refused, so only this pinned value can break the cycle. Read the
|
|
# id off fleet_whoami (it reports the current terminal even while
|
|
# misclassified) and re-pin whenever the primary moves panes.
|
|
# pushReminders → max nudges before giving up (default 5)
|
|
# pushBackoffMs → delay between nudges in ms (default 15000)
|
|
# primary:
|
|
# terminal: term_65619bd6174568
|
|
# pushReminders: 5
|
|
# pushBackoffMs: 15000
|
|
|
|
# Central allow-list of models any profiles: entry may name. Nothing checked a profile's model:
|
|
# value before this block existed — it was a free-form string handed straight to the backend
|
|
# adapter, and a withdrawn or misspelled name failed silently instead of at config load (opencode
|
|
# falls back to a default model rather than erroring on an unknown -m).
|
|
#
|
|
# Absent, or present with an empty allow:, is OFF: no profile's model: is checked, exactly like
|
|
# before this block existed. fleetd.yaml is gitignored on every host, so an upgrade must not force
|
|
# every operator to enumerate their models before the daemon will start.
|
|
#
|
|
# The list is the authority; profiles: is checked against it, never the reverse — adding or
|
|
# editing a profiles: entry cannot, by itself, widen what is permitted here.
|
|
#
|
|
# Enforcement is at CONFIG LOAD only (a bad model: fails the daemon at startup, naming both the
|
|
# model and the profile). There is no spawn-time enforcement, no runtime on/off switch, and no
|
|
# interaction with BackendQuarantine — those are separate, later units.
|
|
#
|
|
# allow → the permitted models. Each entry is its own block (not a bare string) so a later unit
|
|
# can add an on/off state or a load limit per model without changing this shape.
|
|
# model → the model id exactly as a profiles: entry's model: field would write it. One flat,
|
|
# opaque-string namespace: a bare Claude id (claude-sonnet-5) and an opencode
|
|
# provider-prefixed id (openai/gpt-5.6-terra) both fit here unchanged — the check is a
|
|
# plain string match, never a parse of the provider prefix or a branch on kind:.
|
|
# models:
|
|
# allow:
|
|
# - model: claude-sonnet-5
|
|
# - model: claude-opus-5
|
|
# - model: openai/gpt-5.6-terra
|
|
# - model: amazon.nova-pro-v1:0
|