Configuration

Complete reference for configuring agents-fleet at v0.36.3 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 .fleet/workflows/ command synthesis (now the default).
--no-trust-project-workflows	—	Disable project-tier .fleet/workflows/ command synthesis.
--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	on (no-op)	Legacy opt-in for project-tier roles/skills/crews (#487).
--no-trust-project-skills	—	Skip loading project-tier .fleet/roles, .fleet/skills, .fleet/crews.
--allow-privilege-escalation	false	Allow config/spawn permission overrides to elevate restricted agent profiles (SEC-4). Mirrors allowPrivilegeEscalation in config.json (CLI wins).

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.

---

~/.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.
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 overrides (SEC-4).
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	Project-tier .fleet/workflows/ trust (mirrors --no-trust-project-workflows).
gateDiscovery	trustProjectSources: false	Project-tier gate trust (PR-6).
intakeDiscovery	trustProjectSources: false	Project-tier intake-adapter trust (PR-7).
skillsDiscovery	trustProjectSources: true	Project-tier role/skill/crew trust (#487, default ON).
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_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_TRUST_PROJECT_WORKFLOWS	on	0 disables project-tier workflow command synthesis.
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	on	0 skips project-tier roles/skills/crews (#487).
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_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_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.

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	1 disables the centralized system-prompt assembly.
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.

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.