Configuration

Complete reference for configuring agents-fleet at v0.60.0 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/.

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.
--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.
--forensic-viewer	false	Start or reuse the local forensic replay viewer service. See the Forensic Viewer guide.

---

~/.fleet/config.json

Persisted settings live in <FLEET_HOME>/config.json (default ~/.fleet/config.json). Edit it in-app with /config set <key> <value>, or by hand. 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).
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.

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.

---

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_CREW_V1	off	Force legacy v1 crew loading behavior.

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.

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	—	Path to a channel outbox for outbound message capture.
AGENTS_FLEET_OUTBOX_ENV	—	Companion env metadata for the outbox.
AGENTS_FLEET_TRANSPORT_BOUNCE	off	Loopback/bounce mode for channel transport testing.

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	internal	MCP registry wait timeout (ms) before boot continues without lagging servers.
AGENTS_FLEET_MCP_REGISTRY_GATE	—	MCP registry gate mode (warn or enforce).
AGENTS_FLEET_NPM_REGISTRY	—	Custom npm registry URL for MCP server package installs.
AGENTS_FLEET_NPM_PREFER_OFFLINE	off	1 passes --prefer-offline to npm when installing MCP server packages.
AGENTS_FLEET_NPM_CACHE	—	Override the npm cache directory for MCP server package installs.
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_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_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.

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.

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_SOCKET_PATH	platform default	Override the control-socket path.
AGENTS_FLEET_CONTROL_PLANE_HOME	—	Home dir for the control-plane singleton state.
AGENTS_FLEET_CONTROL_PLANE_TELEGRAM_TOKEN	—	Telegram token for the control-plane front-end.
AGENTS_FLEET_CONTROL_PLANE_AUTO_APPROVE	off	Auto-approve control-plane taps.
AGENTS_FLEET_CONTROL_PLANE_CONFIRM_TAPS	off	Require confirmation for control-plane taps.
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.

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_SEND_FSM	off	Enable the experimental send finite-state-machine path.
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	off	Enable extra cache-invalidation checks.

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	Under Ink, auto-routes stderr debug to ~/.fleet/logs/ink-suppressed.log.
AGENTS_FLEET_DEBUG_SDK_TOOLS	off	Verbose SDK tool-call tracing.
AGENTS_FLEET_VERBOSE_TOOL_ARGS	off	Log per-tool-call arg key/size (mirror of --verbose).

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.