Configuration

Reference for configuring agents-fleet at v0.60.1 via CLI flags, environment variables, and the persisted config.json file.

Sources: CLI flags are defined in src/index.ts; the config schema + defaults live in src/config.ts (FleetConfig / DEFAULT_CONFIG); environment variables are read across src/. The environment-variable section lists every AGENTS_FLEET_* variable read by non-test code at v0.60.1, except the test-harness/build seams called out under Internal & test-only; the config-file section covers selected fields only.

Precedence

When the same setting can be supplied multiple ways, the most specific wins:

CLI flag  >  environment variable  >  ~/.fleet/config.json  >  built-in default

A handful of flags also have a config-file mirror (e.g. allowPrivilegeEscalation, workflowDiscovery.trustProjectSources); where that is the case it is noted below.

---

CLI flags

Invoke as agents-fleet [flags]. Run agents-fleet --help for the canonical list emitted by Commander. Source: src/index.ts.

Session & provider

Flag	Default	Description
-p, --prompt <prompt>	—	Run a single prompt OR slash command and exit (non-interactive).
-m, --model <model>	claude-opus-4.6	Model to use.
--provider <name>	copilot	LLM provider: copilot or claude.
-e, --effort <level>	high	Reasoning effort: low | medium | high | xhigh.
--resume [sessionId]	—	Resume a previous session (omit ID to resume latest).
--resume-all	false	Include worker/orphan sessions in the --resume picker (recover a corrupted coordinator session).
--name <label>	—	Set a name for this session.
-v, --verbose	false	Verbose per-tool-call logging in the fleet log (Ink-safe).
--unattended	false	Run without blocking for interactive askUser prompts; the coordinator self-directs. Required for goal-driven loops under --provider claude.
--no-coordinator	—	Single-agent mode (no fleet coordination).
--legacy-ui	—	Use the legacy VT100 renderer instead of Ink.
--cli-path <path>	—	Path to the Copilot CLI executable.
--cli-url <url>	—	URL of an existing Copilot CLI server.

Context window

Flag	Default	Description
--context-tier <tier>	default	Context-window tier (default = 200k, long_context = 1M). Sets BOTH coordinator + worker. Only honored by 1M-capable models.
--coordinator-context-tier <tier>	—	Context tier for the COORDINATOR session only. Overrides --context-tier for that scope.
--worker-context-tier <tier>	—	Context tier for ALL WORKER sessions. Overrides --context-tier for that scope.
--long-context	false	Shortcut for --context-tier long_context.
--context-window <size>	—	Friendly alias for --context-tier: 200k → default, 1m → long_context.

Concurrency & watchdog

Flag	Default	Description
--max-workers <n>	12	Maximum concurrent (data-plane) workers.
--hang-threshold-ms <ms>	14400000 (4h)	Override the SessionSendQueue hang-detector threshold. 0 disables.

Trust & security

Flag	Default	Description
--trust-project-mcp	off	Load project-level MCP server configs (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, agency.toml). Disabled by default per SEC-1.
--trust-project-workflows	on (no-op)	Legacy explicit opt-in for project-tier workflow command synthesis, which is enabled by default. Project workflows load regardless of this gate.
--no-trust-project-workflows	—	Disable command synthesis from project-tier workflows; the workflows still load for direct and crew references.
--trust-project-gates	off	Load project-tier .fleet/gates/*.gate.md validation gates (PR-6).
--no-trust-project-gates	—	Explicit opt-out for project-tier gate discovery (already the default).
--trust-project-intake	off	Load project-tier .fleet/intake/*.intake.md adapters (PR-7).
--no-trust-project-intake	—	Explicit opt-out for project-tier intake discovery (already the default).
--trust-project-skills	off	Load project-tier .fleet/roles/*.role.md, .fleet/skills/*.skill.md, .fleet/crews/*.crew.md (#487). Bundled and user tiers always load.
--no-trust-project-skills	—	Explicitly skip project-tier roles, skills, and crews (already the default).
--trust-team	off	Confirm the --team meta-repo on first use and pin its fingerprint (TOFU); also required to re-trust a changed repository URL.
--team	off	EXPERIMENTAL: enable the shared meta-repo "team" artifact tier (resolved from <cwd>/.fleet/team.toml). Mirror: AGENTS_FLEET_TEAM=1.
--enable-cybersec-skills	off	Opt in to the vendored, dual-use cybersecurity skills library at lowest precedence. Authorized-scope use only. Mirror: AGENTS_FLEET_CYBERSEC_SKILLS=1.
--allow-privilege-escalation	false	Allow config/spawn overrides to enable shell/write/meta/full trust, raise privilege level, or widen write scopes beyond a canonical profile (SEC-4). Mirrors allowPrivilegeEscalation in config.json (CLI wins).

Artifact precedence is bundled < user < team(main) < team(member) < trusted project. The optional team tier also requires --team; see Team Meta-Repo for setup, member overlays, and TOFU behavior.

Deprecated --yolo bypass

--yolo no longer bypasses anything on its own; it requires at least one --acknowledge-* flag.

Flag	Default	Description
--yolo	false	Request deprecated yolo bypass mode. Requires an --acknowledge-* flag.
--acknowledge-sec2	false	With --yolo, re-enable SEC-2 Claude bypassPermissions.
--acknowledge-sec4	false	With --yolo, re-enable SEC-4 restricted-agent approve-all/write/shell bypass.
--acknowledge-mcp-bypass	false	With --yolo, re-enable the MCP allowlist bypass.
--acknowledge-sec-r3-2	false	With --yolo, re-enable SEC-R3-2 unknown-kind fail-closed bypass.
--acknowledge-all-sec	false	With --yolo, acknowledge all SEC bypasses (legacy full-bypass behavior).

Channels & experimental

Flag	Default	Description
--telegram	false	Enable the Telegram remote-steering channel. Incompatible with --legacy-ui, -p/--prompt, and --no-coordinator.
--inbox	false	Enable the EXPERIMENTAL file-queue inbox at ~/.fleet/inbox/*.task.json.
--inbox-trust-all	false	With --inbox, allow kind: spawn_worker descriptors (refused by default).
--control-plane	false	EXPERIMENTAL: boot the machine-orchestration control plane instead of a data-plane fleet.
--control-socket	false	EXPERIMENTAL: expose a per-fleet control socket so an attached client can drive this fleet remotely.
--hub	false	EXPERIMENTAL: opt this fleet in to the control-plane Telegram hub (one forum topic per fleet). Implies --control-socket (fail-loud). The hub operator must still approve the fleet once.
--forensic-viewer	false	Start or reuse the local forensic replay viewer service. See the Forensic Viewer guide.
--native-root	off	Use native ROOT orchestration for fresh sessions (saved sessions keep their mode).
--no-native-root	—	Use legacy Fleet execution; cannot resume a native saved session.
--root-integration-target <refs...>	—	In native ROOT mode, authorize exact local refs for accepted root integration.

---

~/.fleet/config.json

Persisted settings live in <FLEET_HOME>/config.json (default ~/.fleet/config.json). Edit it by hand, or in-app with /config set <key> <value> (accepted keys: model, reasoningEffort, maxWorkers, verbose, and the worktrees.*, steering.*, and evolution.* fields listed below) and /config model-routing for modelRouting. The schema is FleetConfig in src/config.ts; unknown keys are ignored and malformed values fall back to defaults with a warning.

Selected top-level fields

Key	Default	Description
model	claude-opus-4.6	Default model.
provider	copilot	copilot or claude.
reasoningEffort	high	low | medium | high | xhigh.
contextTier	default	Legacy fleet-wide context tier; seeds both coordinator + worker tiers.
coordinatorContextTier	—	Coordinator-only context tier.
workerContextTier	—	Worker-session context tier.
workerReasoningEffort	—	Reasoning effort for worker sessions (low | medium | high | xhigh). Unset = provider default (today's behaviour); it does not inherit reasoningEffort. Silently omitted for models that don't support it (e.g. claude-sonnet-4.5, haiku). Set it by editing config.json — there is no slash command for it (/effort changes the coordinator's reasoningEffort only).
modelRouting	—	Per-agent-type default worker model, e.g. { "explorer": "claude-sonnet-4.5" }. Keys must be known agent types and values non-empty strings (invalid entries are skipped with a warning). Precedence: explicit definition.model (spawn/role/crew pin) > modelRouting[agentType] > session/config model > provider default. Manage with /config model-routing (show), /config model-routing set <agentType> <model>, clear <agentType>, clear-all; /fleet-intel apply <id> also writes it for model-swap suggestions.
maxWorkers	12	Data-plane worker pool size.
maxCoordinatorWorkers	max(1, ⌊maxWorkers/3⌋)	Independent coordinator-tier worker pool (additive to maxWorkers).
verbose	false	Verbose tool-call logging.
resumeWindow	500	Max transcript entries shown on resume (0 = unlimited).
allowPrivilegeEscalation	false	Allow permission-profile elevation via wildcard, type, or spawn overrides (SEC-4). Required for false-to-true canShell/canWrite and write-scope widening.
yolo	false	Deprecated bypass; each bypass still needs a matching yoloAcks entry.
controlSocket	false	Enable the per-fleet control socket without a flag. Read early and fail-soft (a bind failure warns and the fleet keeps booting). Precedence: --control-socket > AGENTS_FLEET_CONTROL_SOCKET > this key. Edit config.json by hand.

Nested config objects

Key	Notable fields (defaults)	Description
worktrees	enabled: true, directory: '.worktrees', symlinkNodeModules: false	Git-worktree isolation for workers.
steering	enabled: true, timeoutMs: 60000, maxInsights: 10, maxMessages: 50, memoryThreshold: 70	Remote-steering / insight-extraction knobs.
mcpServers	[]	Explicit MCP server entries (managed via /mcp).
mcpDiscovery	enabled: true, trustProjectSources: false	MCP auto-discovery; project sources off by default (SEC-1).
evolution	enabled: true, autoEvolve: false, maxPromptTokens: 4000, minSampleSize: 5, confidenceThreshold: 75, rollbackAfterSessions: 5	Skill-evolution pipeline.
experiment	enabled, schedulerEnabled, maxVariants, maxTrialsPerRun, …	A/B experiment framework knobs.
intel	captureLabeledOutcomes	Intel/telemetry capture knobs.
shadow	minShadowRuns: 5, winRateThreshold: 0.6	Shadow-skill promotion thresholds.
heartbeat	enabled, heartbeatIntervalMs, stallTimeoutMs, bridgedStallTimeoutMs, maxRespawnAttempts, …	Worker heartbeat / stall-recovery tuning.
instructions	enabled, discover, files, excludePatterns, injectIntoWorkers	Project-instruction injection.
workflowDiscovery	trustProjectSources: true	Controls project-tier workflow command synthesis only; project workflows still load when false.
gateDiscovery	trustProjectSources: false	Project-tier gate trust (PR-6).
intakeDiscovery	trustProjectSources: false	Project-tier intake-adapter trust (PR-7).
skillsDiscovery	trustProjectSources (unset; resolves false)	Project-tier role/skill/crew trust (#487, opt-in).
coordinator	—	Coordinator-engine tuning.
permissions	—	Per-agent-type permission overrides (Record<AgentType | '*', PermissionOverrides>).
yoloAcks	—	Per-SEC acknowledgements for the deprecated yolo bypasses.
telegramHub	attach: false	{"attach": true} opts this fleet in to the control-plane Telegram hub and implies the control socket (fail-soft). Precedence: --hub > AGENTS_FLEET_TELEGRAM_HUB_ATTACH (0 forces off) > this key.

---

Environment variables

All boolean-style flags below treat '1' (and where noted '0') as the active value. Unless stated otherwise, a variable being unset keeps the default behavior.

Paths & storage

Variable	Default	Description
FLEET_HOME	~/.fleet	Root for all fleet state (config, sessions, logs, intel DB). Enables multi-instance isolation.
AGENTS_FLEET_HOME	—	Alternate fleet-home override (resolved by resolveFleetHome).
AGENTS_FLEET_SESSION_STORE_DB	—	Override path to the SQLite session-store DB.
AGENTS_FLEET_HOST_SESSION_STATE_DIR	~/.copilot/session-state	Override the Copilot host session-state root used for stat-only oversized-log resume checks.
AGENTS_FLEET_NO_MIGRATE	off	Skip session-schema / skill migrations on boot.
AGENTS_FLEET_REGISTRY_DIR	~/.fleet/sockets	Directory for the machine-wide registry of running-fleet discovery descriptors (<id>.json). Non-empty value wins over the default.

Worktrees

Variable	Default	Description
AGENTS_FLEET_WORKTREE_REAP	on	Startup reclamation of old worker-prefixed (and unattributed) agent worktrees that pass every /worktree cleanup safety guard (dirty, unmerged, locked, live-agent, nested, and similar entries are refused). At most 25 removals per pass; best-effort, never throws or blocks boot. 0/false/no/off (case-insensitive) disables.
AGENTS_FLEET_WORKTREE_REAP_RETENTION_DAYS	7	Age window before a preserved worktree becomes reclaimable. 0 removes the age gate (every guard-passing candidate is reclaimable, not "disabled" — use AGENTS_FLEET_WORKTREE_REAP=0 to turn reaping off). Negative or unparseable values fall back to 7.
AGENTS_FLEET_WORKTREE_GIT_TIMEOUT_MS	60000	Timeout for each git worktree subprocess (raise on slow filesystems). Non-positive/invalid values use the default.

Native ROOT (--native-root only)

Variable	Default	Description
AGENTS_FLEET_ROOT_REAP	on	Reap old root-run records from the ROOT run store (terminal, abandoned-draft, or budget-expired roots past retention; up to 100 per pass). 0/false disables.
AGENTS_FLEET_ROOT_REAP_RETENTION_DAYS	30	Retention window for root-run reaping. Non-positive/unparseable values fall back to 30.
AGENTS_FLEET_ROOT_MAX_WALLCLOCK_MS	off	Optional raw wall-clock ceiling for a live root, independent of the metered root clock's stall credit. Unset, 0, false, or garbage disables.

Provider & permissions

Variable	Default	Description
AGENTS_FLEET_CLAUDE_BYPASS_PERMISSIONS	off	Re-enable global Claude bypassPermissions (SEC-2; otherwise gated behind --yolo --acknowledge-sec2).
AGENTS_FLEET_UNATTENDED	off	Equivalent to --unattended.
AGENTS_FLEET_CLAUDE_HISTORY_WINDOW	40	--provider claude: number of most-recent messages re-injected as conversation history on each send. 0 injects the full history (legacy, O(n²) over a long session); negative/invalid values use the default.
AGENTS_FLEET_QUIET_MODEL_LOG	off	1 suppresses the per-session "resolved model" log line written at session creation.
AGENTS_FLEET_MCP_RECOVERY_MAX_ATTEMPTS	5	MCP health monitor: reload attempts (spaced 30 s, the registry breaker window) while MCP servers stay blocked after a registry outage.
AGENTS_FLEET_MCP_RECOVERY_BOUNCE	off	1 lets the MCP health monitor escalate once to a transport bounce (fresh subprocess) when reloads are exhausted. Off by default because bouncing recreates sessions.

Telegram & channels

Variable	Default	Description
AGENTS_FLEET_TELEGRAM_TOKEN	—	Telegram bot token. Always wins over ~/.fleet/telegram.json.
AGENTS_FLEET_TG_DEBUG	off	Verbose Telegram transport logging.
AGENTS_FLEET_OUTBOX	off	Set to 1 by the control-plane supervisor on the data-plane fleets it spawns; enables the structured JSONL event outbox at <FLEET_HOME>/outbox/events.jsonl. Any other value is a no-op.
AGENTS_FLEET_TRANSPORT_BOUNCE	off	1 lets the Copilot provider restart (bounce) a dead CLI transport before creating/resuming sessions.

Trust & security

Variable	Default	Description
AGENTS_FLEET_MCP_TRUST_PROJECT	off	Mirror of --trust-project-mcp (1 loads project MCP sources).
AGENTS_FLEET_MCP_REGISTRY_WAIT_MS	120000	Startup wait budget while the Copilot MCP registry allowlist endpoint returns 503; boot proceeds (fail-open) when it expires. 0 = no wait; an unparseable value is also treated as 0. Only applies when MCP servers are configured and a registry token plus GitHub owner/repo resolve.
AGENTS_FLEET_MCP_REGISTRY_GATE	on	0 disables the startup MCP registry probe/gate and the in-session MCP health monitor. The gate only runs when MCP servers are configured and a registry token plus GitHub owner/repo resolve.
AGENTS_FLEET_NPM_REGISTRY	—	Registry URL injected into spawned worker sessions as npm_config_registry (e.g. a proxy). Never applied to the coordinator or parent process.
AGENTS_FLEET_NPM_PREFER_OFFLINE	off	Truthy (1/true/yes/on) injects npm_config_prefer_offline=true into worker sessions.
AGENTS_FLEET_NPM_CACHE	—	Shared npm cache directory injected into worker sessions as npm_config_cache.
AGENTS_FLEET_TRUST_PROJECT_WORKFLOWS	on	0 disables project-tier workflow command synthesis; workflow loading is unaffected.
AGENTS_FLEET_TRUST_PROJECT_GATES	off	1 loads project-tier validation gates (PR-6).
AGENTS_FLEET_TRUST_PROJECT_INTAKE	off	1 loads project-tier intake adapters (PR-7).
AGENTS_FLEET_TRUST_PROJECT_SKILLS	off	1 loads project-tier roles/skills/crews; 0 explicitly skips them (#487).
AGENTS_FLEET_TRUST_TEAM	off	1 mirrors --trust-team for first-use TOFU confirmation or explicit re-trust of a changed team meta-repo URL.
AGENTS_FLEET_TEAM	off	1 (strict) mirrors --team: enable the shared meta-repo team tier.
AGENTS_FLEET_TEAM_DIR	—	With the team tier on, use this already-local checkout as the team main tier; skips the team.toml sync and the TOFU gate.
AGENTS_FLEET_TEAM_MEMBER_DIR	—	Companion to AGENTS_FLEET_TEAM_DIR: local checkout for the members/<name> overlay tier.
AGENTS_FLEET_CYBERSEC_SKILLS	off	1 (strict) mirrors --enable-cybersec-skills.
AGENTS_FLEET_COORD_ALLOW_INLINE_EDIT	off	1 (strict) gives the coordinator back its built-in file-mutation tools (Copilot and Claude providers). By default code changes must be delegated via spawn_worker.
AGENTS_FLEET_INBOX_TRUST_ALL	off	Mirror of --inbox-trust-all.
AGENTS_FLEET_YOLO_LEGACY	off	Re-enable legacy full --yolo bypass semantics.

Watchdog & stall recovery

See the coordinator stall ladder (T1–T4) for the full design.

Variable	Default	Description
AGENTS_FLEET_WATCHDOG_DISABLED	off	1 turns off ALL watchdog tiers (interval never starts).
AGENTS_FLEET_STALL_WARN_THRESHOLD_MS	60000 (60 s)	T1 warn threshold. Raise (e.g. 180000) to quiet benign "Coordinator appears stalled" warnings from long mid-stream thinking gaps (high-effort Opus on 1M context). The T2 auto-abort / T3 escalation thresholds are unaffected; note the T1.5 zombie probe starts counting from this threshold, so a higher value slightly delays that probe's start (its recovery still fires well before T2).
AGENTS_FLEET_STALL_WARN_DISABLED	off	1 suppresses the T1 warn (emit + channel notify + heartbeat) entirely while keeping T1.5/T2/T3 recovery.
AGENTS_FLEET_AUTO_ABORT_DISABLED	off	1 disables T2 auto-abort + T1.5 zombie probe; T1 warn still fires.
AGENTS_FLEET_AUTO_ABORT_THRESHOLD_MS	2400000 (40 min)	T2 auto-abort threshold for a wedged coordinator.
AGENTS_FLEET_FIRST_DELTA_TIMEOUT_MS	600000 (10 min)	Caps how long the watchdog tiers stay suppressed while a sent prompt waits for its first streaming delta, so a dead pre-stream connection is caught in minutes instead of at T2.
AGENTS_FLEET_HANG_THRESHOLD_MS	14400000 (4 h)	T4 SessionSendQueue hang-detector threshold (mirror of --hang-threshold-ms; 0 disables).
AGENTS_FLEET_STALL_HEARTBEAT_MS	internal	Heartbeat interval for the stall watchdog.
AGENTS_FLEET_WAKE_ON_COMPLETION	on	0 disables the CompletionWaker (auto-wake on terminal agent events).
AGENTS_FLEET_AUTOPILOT_ESCALATION	on	0 disables autopilot-stuck channel notify + in-app chip.
AGENTS_FLEET_HEARTBEAT_BRIDGED_EXEMPT	on	0 restores the legacy heartbeat kill for bridged sub-coordinators.
AGENTS_FLEET_HEARTBEAT_BRIDGED_STALL_MS	2700000 (45 min)	Non-destructive bridged-stall detection threshold.
AGENTS_FLEET_HEARTBEAT_MAX_TOOL_RUNTIME_MS	1800000 (30 min)	Maximum age of an active worker tool before heartbeat recovery may proceed. Valid values are clamped to 1 min–24 h; invalid values fall back to config/default.
AGENTS_FLEET_LOOP_MAX_NOOPS	internal	Max consecutive no-progress loop iterations before a loop self-stops.
AGENTS_FLEET_LEAK_DETECTOR_DISABLED	off	1 disables the resource-leak detector.
AGENTS_FLEET_IDLE_WITH_WORK_WATCHDOG	on	Mode C IdleWithWorkWatchdog: wakes an idle coordinator that still has outstanding work (max 3 wakes per stagnation episode). 0/false/no/off disables; AGENTS_FLEET_WATCHDOG_DISABLED also turns it off.
AGENTS_FLEET_IDLE_WITH_WORK_RECOVER	off	Opt in (1/true/yes/on) to the destructive escalation (session recovery) after wakes are exhausted. Keep off unless you need it.
AGENTS_FLEET_IDLE_WITH_WORK_THRESHOLD_MS	900000 (15 min)	Idle time with outstanding work before the first wake.
AGENTS_FLEET_COORD_INLINE_TOOL_CAP	on	off (or 0) disables the per-call cap on the coordinator's inline shell / file-mutation built-ins. Never applies to in-process fleet tools.
AGENTS_FLEET_COORD_INLINE_TOOL_CAP_MS	25000	Duration cap for one inline coordinator built-in tool call; on breach the call is aborted and the coordinator is told to delegate via spawn_worker. 0 disables; garbage uses the default.
AGENTS_FLEET_COORD_QUEUED_ACK	on	off disables the one-time "queued" acknowledgement shown when you send a prompt while the coordinator is busy.

Workflows & sub-coordinator bridge

Variable	Default	Description
AGENTS_FLEET_WORKFLOW_SUBCOORD_BRIDGE	on	0 reverts bridged autopilots to the legacy LLM-driven workflow-runner path.
AGENTS_FLEET_WORKFLOW_WATCHDOG_DISABLED	off	1 disables the workflow-runner watchdog.
AGENTS_FLEET_WORKFLOW_WATCHDOG_THRESHOLD_MS	per-workflow	Override the workflow-runner warn threshold.
AGENTS_FLEET_WORKFLOW_AUTO_ABORT_THRESHOLD_MS	per-workflow	Override the workflow-runner auto-abort threshold.
AGENTS_FLEET_WORKFLOW_HANG_THRESHOLD_MS	per-workflow	Override the workflow-runner hang threshold.
AGENTS_FLEET_WORKFLOW_COMPLETE_GRACE_MS	internal	Grace period before a completed workflow is finalized.
AGENTS_FLEET_STAGE_GATE_REMINDER_MS	internal	Interval for stage-gate reminder nudges.
AGENTS_FLEET_SUBGRAPH_MAX_DEPTH	5	Max nested-subgraph recursion depth for workflows.
AGENTS_FLEET_FOREACH_COMMAND	off	Enable the experimental forEach stage command.
AGENTS_FLEET_LANGGRAPH_DISABLED	off	1 disables the LangGraph execution path.
AGENTS_FLEET_EVAL_SCHEDULER_DISABLED	off	1 disables the background evaluation scheduler.
AGENTS_FLEET_EXPERIMENT_SCHEDULER_DISABLED	off	1 (strict) disables the A/B experiment scheduler even when experiment.enabled and experiment.schedulerEnabled are set in config.
AGENTS_FLEET_STAGE_SPAWN_TIMEOUT_MS	1800000 (30 min)	Bridged per-stage spawn wait used when a workflow declares no phaseTimeoutMs (a workflow's own phaseTimeoutMs wins). Non-positive/invalid values use the default.
AGENTS_FLEET_HANDOFF_STRICT	off	1/true/yes (case-insensitive): malformed workflow handoff: entries throw INVALID_WORKFLOW_HANDOFF at load instead of being warned about and dropped.
AGENTS_FLEET_WEBHOOK_SECRET_<NAME>	—	HMAC secret for a webhook handoff target. <NAME> is the target's name: (or the URL hostname when omitted), uppercased, with non-alphanumerics replaced by _.

Planning & DoD

Variable	Default	Description
AGENTS_FLEET_DOD_GATE	warn	Controls the self-healing DoD execute-gate: off (no gating), warn (auto-remediate then proceed), enforce (auto-remediate then hold if gap remains). See the Coordinator Planning guide.

Control plane & control socket

Variable	Default	Description
AGENTS_FLEET_CONTROL_SOCKET	off	Mirror of --control-socket.
AGENTS_FLEET_CONTROL_PLANE_HOME	—	Home dir for the control-plane singleton state.
AGENTS_FLEET_CONTROL_PLANE_NO_REPL	off	1 forces the control plane headless (no Ink REPL or line reader), regardless of stdin.
AGENTS_FLEET_CONTROL_PLANE_TELEGRAM_TOKEN	—	Telegram token for the control-plane front-end.
AGENTS_FLEET_CONTROL_PLANE_AUTO_APPROVE	off	1 runs control-plane mutating tools WITHOUT a Telegram confirm prompt.
AGENTS_FLEET_CONTROL_PLANE_CONFIRM_TAPS	1	Number of taps the control-plane Telegram confirm prompt requires (positive integer).
AGENTS_FLEET_CONTROL_PLANE_CONFIRM_TTL_MS	internal	TTL for a pending tap confirmation.
AGENTS_FLEET_DATA_PLANE_BIN	resolved	Override the data-plane launcher binary.
AGENTS_FLEET_DATA_PLANE_ARGS_PREFIX	—	Argument prefix injected when spawning data-plane fleets.
AGENTS_FLEET_TELEGRAM_HUB	on (with a CP token)	Control-plane Telegram hub. Enabled whenever AGENTS_FLEET_CONTROL_PLANE_TELEGRAM_TOKEN is set; a bound group is not required. 0 is the killswitch (legacy control-plane bot behaviour).
AGENTS_FLEET_TELEGRAM_HUB_DISCOVERY_MS	3000	Hub registry poll interval (~/.fleet/sockets). Overrides hub.json discoveryIntervalMs.
AGENTS_FLEET_TELEGRAM_HUB_RATE_PER_MIN	20	Shared per-group send budget (all topics + General). Overrides hub.json groupRatePerMin.
AGENTS_FLEET_TELEGRAM_HUB_ATTACH	off	Fleet side: 1 mirrors --hub (fail-loud), 0 forces attach off (overrides telegramHub.attach). The control-plane supervisor sets 1 on the fleets it spawns while the hub is enabled.

Telegram hub file: <control-plane home>/hub.json

Optional, validated key by key (an invalid value falls back to the default with a warning). Precedence: env > hub.json > defaults. Persisted hub state (binding, trust decisions, topics, watermarks) lives in <control-plane home>/telegram-hub/state.json.

Key	Default	Description
enabled	true	false disables the hub like AGENTS_FLEET_TELEGRAM_HUB=0.
exclude	[]	Globs matched against a fleet's cwd / name; matching fleets are ignored.
discoveryIntervalMs	3000	Registry poll interval.
groupRatePerMin	20	Shared per-group send budget.
coalesceMs	2000	Per-topic, per-class outbound coalescing window.
titleMinIntervalMs	30000	Per-topic floor between topic-title (status emoji) edits.
defaultVerbosity	default	default | verbose for new topics (/verbose on|off per topic).
maxReplyChars	12000	Reply cap before …(truncated, see terminal).
maxInboundAgeMs	600000	Mandatory (> 0): inbound prompts, /stop and Control commands older than this (e.g. typed while the hub was down) are rejected with a stale notice.
queueAgingMs	60000	Queued status/verbose items older than this are promoted one class.
detachAfterMs	60000	Unreachable link + dead pid ⇒ detach.
trustPromptTtlMs	86400000	An unanswered fleet approval prompt expires (re-prompted on the next sighting).
errorStickyMs	600000	How long a fleet error keeps the 🔴 status emoji.

There is deliberately no "trust all fleets" switch: every fleet is approved once by the operator, including children the control plane spawned itself.

Inbox

Variable	Default	Description
AGENTS_FLEET_INBOX_POLL_MS	internal DEFAULT_POLL_MS	Inbox file-queue poll interval.
AGENTS_FLEET_INBOX_TRUST_ALL	off	See Trust & security above.

Restart, timeouts & misc

Variable	Default	Description
AGENTS_FLEET_RESTART_DELAY_SECONDS	internal	Delay before /restart relaunches the new window.
AGENTS_FLEET_RESTART_MAX_WAIT_SECONDS	internal	Max wait for /restart handoff.
AGENTS_FLEET_SINGLE_SHOT_TIMEOUT_MS	internal	Timeout for single-shot (-p/--prompt) runs.
AGENTS_FLEET_POST_QUERY_IDLE_MS	internal	Idle window after a query completes before considering the turn done.
AGENTS_FLEET_POST_QUERY_TIMEOUT_MS	internal	Hard timeout for post-query settle.
AGENTS_FLEET_DELEGATION_NUDGE	on	0 disables the coordinator delegation nudge.
AGENTS_FLEET_DISABLE_CENTRAL_PROMPT	off	Diagnostic-only legacy killswitch. 1 disables the generated coordinator invariant core; it is not a supported extension or production setting. The mandatory worker core remains enabled.
AGENTS_FLEET_DISABLE_TIERED_LIMITER	off	1 collapses worker + coordinator pools into a single maxWorkers limiter (pre-3a behavior).
AGENTS_FLEET_INVALIDATION_CHECK	on unless NODE_ENV=production	State-store cache-invalidation contract check: 1 forces it on, 0 forces it off (e.g. benchmarks).

Forensics & telemetry

Variable	Default	Description
AGENTS_FLEET_SESSION_TELEMETRY	on	Full-payload forensic event capture to ~/.fleet/sessions/<sessionId>.events.ndjson is enabled by default. Set to 0 (or false, case-insensitive) to opt out; any other value — including 1, true, or an unrecognized value — leaves capture on. Unredacted — see caution below. Prints a one-time startup security caution whenever capture is on.
AGENTS_FLEET_SESSION_TELEMETRY_MAX_MB	50	Maximum ledger file size in megabytes. Must be a positive number.
AGENTS_FLEET_SESSION_TELEMETRY_RETENTION_DAYS	30	Age window for the startup ledger reaper. Ledgers last modified more than this many days ago are deleted. 0 disables age-based reaping; an unparseable value falls back to 30.
AGENTS_FLEET_SESSION_TELEMETRY_MAX_TOTAL_MB	2048	Total on-disk budget across ALL ledgers. When exceeded, the reaper deletes oldest-first until the remainder fits. 0 disables budget-based reaping; an unparseable value falls back to 2048.
AGENTS_FLEET_FORENSIC_VIEWER_DESCRIPTOR	~/.fleet/forensics/viewer-server.json	Override the path to the forensic replay service descriptor file (port, token, PID).
AGENTS_FLEET_FORENSIC_VIEWER_SWEEP	on	Best-effort sweep at normal startup that unlinks a viewer descriptor left behind by a crashed service (PID check, then authenticated /api/health + instanceId probe, 1s timeout). Makes no network call when no descriptor file exists. Set to 0 (or false, case-insensitive) to opt out; any other value — including a typo — leaves it on.

⚠️ Forensic capture is ON BY DEFAULT and writes secrets to disk in plaintext. Opt out with AGENTS_FLEET_SESSION_TELEMETRY=0. Capture applies zero redaction. The ledger records LLM prompts, LLM completions, tool arguments, tool results, permission/decision-dialog payloads, inter-agent messages, and token-usage snapshots — all verbatim. Any API key, bearer token, or credential passed as a tool argument is persisted in cleartext.

Ledgers are created with POSIX mode 0o600 in directories at 0o700, but NTFS does not enforce POSIX mode bits — on Windows the full conversation history is readable by any local user unless you apply ACLs to ~/.fleet/sessions/ (and ~/.fleet/forensics/) yourself.

Ledgers are not deleted at session end. They are reaped at the NEXT startup on two dimensions: an age window (AGENTS_FLEET_SESSION_TELEMETRY_RETENTION_DAYS, default 30 days) and a total on-disk budget across all ledgers (AGENTS_FLEET_SESSION_TELEMETRY_MAX_TOTAL_MB, default 2048 MB, trimmed oldest-first). The budget is the dimension that bounds the worst case: an age window alone cannot stop a burst of sessions that each saturate the 50 MB AGENTS_FLEET_SESSION_TELEMETRY_MAX_MB per-session cap. Set either to 0 to disable that dimension and take retention back yourself. See Forensic Session Viewer.

Debugging

Variable	Default	Description
AGENTS_FLEET_DEBUG	off	Raw SDK event firehose to the fleet log.
AGENTS_FLEET_DEBUG_STDERR	off	1 (exactly), together with AGENTS_FLEET_DEBUG, mirrors the SDK event firehose to stderr; under Ink that stderr output is redirected to ~/.fleet/logs/ink-suppressed.log. With --provider claude, 1 also shows the expected, normally suppressed Permission deny rule … matches no known tool warnings (aliases the current SDK doesn't register). Unknown deny names always warn, and a load-bearing name (one the SDK really registers, e.g. Write, Edit, Bash, Task, NotebookEdit, TodoWrite, EnterWorktree) escalates loudly regardless.
AGENTS_FLEET_DEBUG_SDK_TOOLS	off	Verbose SDK tool-call tracing.
AGENTS_FLEET_VERBOSE	off	Any non-empty value (or DEBUG) logs unknown Claude SDK message types to stderr (redacted).
AGENTS_FLEET_VERBOSE_TOOL_ARGS	off	Log per-tool-call arg key/size (mirror of --verbose).

Internal & test-only

These are read by non-test source but are build/test seams, not operator knobs. They are listed for completeness; do not rely on them.

Variable	Purpose
AGENTS_FLEET_COMMIT	Build metadata: commit SHA reported in runtime metadata (falls back to GITHUB_SHA, then package.json gitHead).
AGENTS_FLEET_TEST_OFFLINE	Test harness: 1 disables live provider integration tests and auth/health probes.
AGENTS_FLEET_CONTROL_PLANE_REPL_MARKER	e2e harness: 1 makes the control-plane line reader print an idle marker line between turns.

Removed / never wired: AGENTS_FLEET_SEND_FSM (send state machine removed in #680), AGENTS_FLEET_CREW_V1, AGENTS_FLEET_CONTROL_SOCKET_PATH, and AGENTS_FLEET_OUTBOX_ENV (a source constant naming AGENTS_FLEET_OUTBOX, not a variable) were listed in earlier versions of this page but are not read by any agents-fleet code; setting them has no effect.

Note: Variables marked internal read a hard-coded default from source when unset; consult the cited module (src/fleet/, src/coordinator/, src/skills/) for the exact numeric value, which may change between releases.