Environment Variables

Complete reference for all Agent Swarm environment variables — server configuration, API keys, MCP base URL, Slack tokens, GitHub credentials, and integration settings for self-hosted deployments

Complete reference for all environment variables used by Agent Swarm.

Server Variables

Variable	Default	Description
`PORT`	`3013`	Port for MCP HTTP server
`AGENT_SWARM_API_KEY`	—	Preferred, namespaced API key for server authentication — takes precedence over `API_KEY` (set either one). Always read via `getApiKey()` (`src/utils/api-key.ts`), never `process.env.API_KEY` / `process.env.AGENT_SWARM_API_KEY` directly.
`API_KEY`	—	Legacy API key for server authentication (required unless `AGENT_SWARM_API_KEY` is set). See `AGENT_SWARM_API_KEY` above for the preferred, namespaced variable.
`RBAC_ENABLED`	`true`	Gates REST requests authenticated with `aswt_` user tokens against RBAC role grants. Operator API-key requests and agent-authenticated calls are unaffected. Built-in roles and missing user assignments are seeded at boot. Set `false` to opt out.
`EXTENSION_ALLOW_LEAD_ACTIVATION`	`true`	Allows trusted leads to enable, disable, and activate extension versions. Set `false` or `0` in the API deployment environment and restart every replica to reserve these operations for operators/dashboard users. Cannot be changed through swarm configuration APIs. Existing enabled extensions continue to run. See extension trust and activation.
`SCRIPTS_ONLY_MCP`	`false` (unset/off)	Experimental code-mode. Set to `true` on the API server and agent containers to expose only the eight script tools over MCP while keeping the full swarm SDK available through `script-run`. It can also be configured per agent/repository/global scope through `swarm_config`; see Scripts-only mode.
`MCP_BASE_URL`	`https://api.example-swarm.dev`	Internal/worker-facing API base — the URL workers, the UI, and the setup command use to reach the API server. In split deploys this may be an internal/cluster address.
`PUBLIC_MCP_BASE_URL`	Falls back to `MCP_BASE_URL`	Public, browser/externally-reachable API origin used for OAuth redirect URIs and webhook URLs. Defaults to `MCP_BASE_URL` when unset; set it in split deploys where `MCP_BASE_URL` is an internal/cluster address that external providers (Linear, Jira, GitHub) can't reach.
`MCP_OAUTH_ALLOW_PRIVATE_HOSTS`	`false`	When `true`, disables the SSRF guard that otherwise refuses `localhost`/RFC1918 private-IP hosts when the server connects to an operator-registered MCP server's OAuth discovery/token endpoints. Only needed to reach an internal-only MCP server, or for local dev/testing — keep the default deny-list in production.
`CORS_ALLOWED_ORIGINS`	Hosted/dev allowlist (below)	Comma-separated exact origins or wildcard-subdomain patterns. Unset or blank uses built-in defaults; a nonblank value replaces them. Unlisted origins receive neither Allow-Origin nor Allow-Credentials unless the non-credentialed compatibility option below is enabled. Applies to API and page-session endpoints.
`CORS_ALLOW_ANY_ORIGIN`	`false`	Deployment-only compatibility opt-out (requires API restart; cannot be stored in Configuration): reflect any origin for non-credentialed requests only (`credentials: "omit"` for bearer clients). Cookie-authenticated responses still require an allowlisted origin; this flag never grants credentials to unlisted origins. Warns once per process when enabled. Prefer listing trusted SPA origins instead.
`OAUTH_KEEPALIVE_DISABLE`	`false`	Disables the background job that proactively refreshes Linear/Jira OAuth refresh tokens every 12h to prevent silent expiry.
`SWARM_URL`	`localhost`	Base domain for service discovery
`APP_URL`	—	Dashboard URL for Slack message links. `DASHBOARD_URL` is a deprecated alias of `APP_URL`.
`SWARM_DASHBOARD_URL`	Falls back to `APP_URL`	Optional override for the dashboard base URL used to build the "View in Agent Swarm" link posted back to a Linear `AgentSession`.
`TRUST_BODY_REQUESTED_BY_USER_ID`	`true` (unset/on)	When on (default), the server may honor a body-supplied `requestedByUserId` on `POST /api/tasks` (validated against a real user row) if no authenticated/owned-task identity is available — this keeps UI/API task attribution working under a shared operator key. Set to `false` in multi-tenant deployments where callers of the shared key are not all equally trusted, restoring the strict anti-spoofing behavior (body field ignored for operator/global-key callers).
`STEERING_ENABLED`	`true`	Task steering is enabled by default. Set `false` or `0` (API server and worker containers) to opt out: steering routes reject writes, `steer-task`/`accept-steer` are not registered, and workers skip steering delivery polls.
`ENV`	—	Environment mode (`development` adds prefix to Slack agent names)
`DATABASE_PATH`	`./agent-swarm-db.sqlite`	SQLite database file path
`SESSION_LOG_RETENTION_DAYS`	— (disabled)	Permanently delete `session_logs` rows older than this many whole days. Accepted range: 1–1,000,000. Leave unset to disable this table's sweep. Start with `DB_RETENTION_DRY_RUN=true`; deleted session transcripts cannot be restored without a backup. See Database retention.
`AGENT_LOG_RETENTION_DAYS`	— (disabled)	Permanently delete `agent_log` rows older than this many whole days. Accepted range: 1–1,000,000. Leave unset to disable this table's sweep. Deleted task and agent history cannot be restored without a backup. See Database retention.
`EVENTS_RETENTION_DAYS`	— (disabled)	Permanently delete `events` rows older than this many whole days. Accepted range: 1–1,000,000. Leave unset to disable this table's sweep. Event aggregates become retention-window totals, and deleted telemetry cannot be restored without a backup. See Database retention.
`DB_RETENTION_DRY_RUN`	`false`	When `true` or `1`, report the exact number of rows each enabled retention policy would delete without deleting or vacuuming data. Only `true`, `false`, `1`, and `0` are accepted through configuration writes. Use dry run before every first production activation.
`DB_RETENTION_TICK_BUDGET_MS`	`30000`	Wall-clock budget for one retention tick, shared across enabled tables. Accepted range: 1,000–300,000 ms. Read on every tick; out-of-range environment values fall back to the default.
`DB_RETENTION_CATCHUP_INTERVAL_MS`	`60000`	Delay before another retention tick when at least one table remains undrained. Accepted range: 5,000–3,600,000 ms. The normal cadence returns to hourly after the backlog drains.
`DB_RETENTION_MAX_STATEMENT_MS`	`250`	Target maximum driver execution time for one retention DELETE. Accepted range: 25–5,000 ms; the adaptive batch sizer tunes each table toward this ceiling.
`ASSET_KEY_AUDIT_DISABLE_STARTUP_HARD_FAIL`	`false`	Temporary recovery switch. When `true`, the startup asset-namespace audit logs structural key failures instead of aborting the server. Repair the data and remove the switch before normal operation; mapping-drift warnings never abort startup. See Asset Namespaces.
`SQLITE_VEC_EXTENSION_PATH`	—	Path to `vec0.so` native extension for sqlite-vec vector search. Set automatically in the Docker image (`/app/extensions/vec0.so`). Only needed for non-Docker deployments.
`SCRIPT_RUNTIME_DIR`	—	Directory holding the pre-built script-runtime bundles (`eval-harness.bundle.js`, `stdlib.bundle.js`, `swarm-sdk.bundle.js`, `zod.bundle.js`). Set automatically in the Docker image (`/app/scripts-runtime`). Required by the scripts runtime when running as a compiled binary, since the harness subprocess cannot read the binary's `/$bunfs/` virtual filesystem.
`TS_LIB_DIR`	—	Directory holding the TypeScript `lib.*.d.ts` files used by script typecheck. Set automatically in the Docker image (`/app/typescript-lib`). Required in compiled-binary mode so the TypeScript compiler can resolve the default lib.
`MIGRATIONS_DIR`	—	Directory for packaged `.sql` migration files in compiled-binary mode. It is selected explicitly when `import.meta.dir` resolves inside Bun's `/$bunfs/` virtual filesystem, even if that directory can be read. Set automatically in the Docker image (`/app/migrations`); a missing or empty directory now stops a fresh database from booting without its baseline schema. Only needed for non-Docker compiled deployments.
`SCRIPT_TYPES_DIR`	—	Directory whose `node_modules` holds the type declarations for the scripts SDK's bare imports (currently `zod`). Set automatically in the Docker image (`/app/script-types`). Required for script typecheck to resolve `zod` in compiled-binary mode, since the binary doesn't ship `node_modules`.
`SCRIPT_WORKFLOW_RUNTIME_DIR`	—	Directory holding the pre-built script-workflow harness bundle (`harness.bundle.js`), needed by durable script-run subprocesses. Set automatically in the Docker image (`/app/script-workflows-runtime`). Required when running as a compiled binary.
`MODELSDEV_CACHE_PATH`	—	Override path to the vendored `modelsdev-cache.json` pricing/model snapshot, checked before the built-in candidate paths. Only needed for non-standard deployment layouts; boot-time pricing fallback only (live updates are owned by the pricing-refresh job).
`SECRETS_ENCRYPTION_KEY`	Auto-generated on first boot	Master key for encrypting `swarm_config` secret rows at rest. Accepts base64 (43-char, e.g. `openssl rand -base64 32`) or 64-char hex (e.g. `openssl rand -hex 32`). Decodes to exactly 32 bytes. Reserved: cannot be stored in the DB config store. See Encryption Key.
`SECRETS_ENCRYPTION_KEY_FILE`	—	Alternative to `SECRETS_ENCRYPTION_KEY`: absolute path to a file whose contents are the base64- or hex-encoded key. Useful with Docker secrets or k8s `Secret` volume mounts.
`SCHEDULER_INTERVAL_MS`	`10000`	Polling interval for scheduled tasks (ms)
`SCRIPT_RUN_CONCURRENCY_CAP`	`10`	Maximum number of concurrently active script runs the API server allows. New run requests are rejected with HTTP 429 once the cap is reached.
`SCRIPT_RUN_SUPERVISOR_DISABLE`	`false`	When `true`, disables the background script-run supervisor (subprocess spawn, periodic reconcile, and abort-on-limit) — durable script runs will never be started or reconciled.
`SCRIPT_WORKFLOW_DEBUG`	`false`	When `true`, logs verbose debug output (auth override flag, resolved API key length) each time the script-run supervisor spawns a durable script-workflow subprocess.
`WORKFLOW_MAX_ITERATIONS`	`100`	Max times a single workflow node may execute within one run before the engine aborts with an infinite-loop circuit-breaker error.
`WORKFLOW_MAX_STEPS_PER_RUN`	`500`	Max total steps (across all nodes) allowed in a single workflow run before the engine's circuit breaker aborts it.
`OPENAI_API_KEY`	—	Fallback key for memory embeddings (used when `EMBEDDING_API_KEY` is unset).
`EMBEDDING_API_KEY`	—	API key for the embedding provider. Takes precedence over `OPENAI_API_KEY`.
`EMBEDDING_API_BASE_URL`	—	Optional custom OpenAI-compatible base URL (e.g. Azure OpenAI, Together, vLLM, Ollama). Leave unset to hit `api.openai.com`.
`EMBEDDING_MODEL`	`text-embedding-3-small`	Embedding model slug sent to the provider.
`EMBEDDING_DIMENSIONS`	`512`	Vector dimensions requested from the model. Must match what the model supports.
`MEMORY_RECENCY_HALF_LIFE_DAYS`	`14`	Optional global override for memory recency decay. When unset, recency defaults are source-aware: manual memories do not decay, `file_index` uses 180 days, `task_completion` uses 14 days, and `session_summary` uses 7 days.
`MEMORY_HYBRID_SEARCH`	`1` (on)	Hybrid memory retrieval blends vector similarity with a full-text pass before reranking. Set to `0` or `false` to use vector-only search.
`MEMORY_GRAPH_EXPANSION`	`1` (on)	Expands search candidates with 1-hop memory-link neighbors (resolved `[[wikilink]]` targets) before reranking. Neighbors are damped (`parentRawSimilarity × strength × 0.7`), capped at 5 per search, respect the caller's scope/source/lead ACL, and carry `retrievalSource: "graph"` so `GET /api/memory/usefulness` can measure the arm's citation rate. Set to `0` or `false` to disable expansion.
`MEMORY_MIN_SIMILARITY`	`0.1`	Minimum raw cosine similarity required before a memory candidate survives reranking. Filters low-relevance noise before recency/access boosts are applied.
`MEMORY_ACCESS_BOOST_MAX`	`1.5`	Maximum access boost multiplier for reranking
`MEMORY_ACCESS_RECENCY_HOURS`	`48`	Hours within which access counts for full boost
`MEMORY_CANDIDATE_MULTIPLIER`	`3`	Candidate set size relative to requested limit
`MEMORY_DEMOTION_FLOOR`	`1.0`	Floor for the Beta-Binomial usefulness multiplier applied during memory reranking (paired with `MEMORY_RATERS`). Default `1.0` disables demotion entirely; lower values (e.g. `0.5`) let poorly-rated memories sink below neutral relevance.
`OPENROUTER_API_KEY`	—	Required for the Stop-hook session summarizer + LLM memory rater (calls go through the Vercel AI SDK against OpenRouter). When unset, both session-summary indexing and the `llm` rater are no-ops
`OPENROUTER_BASE_URL`	`https://openrouter.ai/api/v1`	Optional OpenAI-compatible gateway for every OpenRouter consumer, including harness sessions, credential checks, memory/session summarizers, and raw-LLM or validation workflow nodes. The target is not required to be openrouter.ai — any gateway serving OpenRouter-compatible `GET /models` and `POST /chat/completions` works (see Model Gateways). Trailing slashes are removed. Leave unset or blank for direct OpenRouter traffic. Also settable from Settings → Configuration.
`MEMORY_RATERS`	`implicit-citation,explicit-self`	Comma-separated list of memory raters to enable (`noop`, `implicit-citation`, `explicit-self`, `llm`). Gates the server-side rating pass fired after task completion (`implicit-citation`) and worker-side gates: the Stop-hook's LLM-rating piggyback (`llm`) and the explicit self-rating tool hint (`explicit-self`). Unknown names are logged and skipped; unset enables citation ratings and self-rating hints on new and existing deployments. Set `MEMORY_RATERS=` explicitly to disable all raters. Deleting a swarm config override restores the deployment value, or the runtime default when unset.
`MEMORY_RATER_MODEL`	Pinned per credential kind (`MEMORY_RATER_DEFAULT_MODEL`): `openrouter/deepseek/deepseek-v4.1-flash`, `anthropic/claude-haiku-4-5`, `openai/gpt-6-luna`, `openai-codex/gpt-6-luna`, or `haiku` (Claude CLI)	Overrides the resolved model slug for the Stop-hook session-summarizer + LLM memory rater, across whichever credential (OpenRouter/Anthropic/OpenAI/Codex OAuth/Claude CLI) the shared `internal-ai` abstraction resolves. The defaults are pinned for the rater only: they do not follow the general default models (e.g. workflow LLM nodes), so a bump there never swaps the judge. Each `llm` rating records the model that produced it in `memory_rating.model`. On the OpenRouter path `completeStructured` sends `tool_choice: "required"`, so the model must accept forced tool calls: OpenRouter answers 400 for `anthropic/claude-sonnet-5.5` (`tool_choice: type tool and any are not supported`) and for `qwen/qwen3.8-flash`, so neither can be the rater model there.
`MEMORY_RATER_WEIGHTS`	`1.0` per rater	Optional `name:multiplier,...` overrides (e.g. `llm:0.5,implicit-citation:2`) applied to each rater's emitted rating weight before it's persisted. Unlisted raters use `1.0`; the final per-event weight is clamped to `[0, 1]`.
`CAPABILITIES`	`core,task-pool,scripts,config,mcp,profiles,scheduling,memory,workflows,pages,metrics,kv,slack,tracker,skills,repo`	Comma-separated capability flags gating which MCP tool groups the API server registers. Disabled by default: `services`, `prompt-templates`, `messaging`, `swarm-x`, `agentmail`, `kapso`. Setting this replaces the default list (not additive) — include every capability you want. Can also be set as a global swarm-config entry, which takes precedence over the env var at server creation. Upgrade note: when an explicit env value is set and no swarm-config `CAPABILITIES` row exists, boot auto-seeds a row backfilling the previously always-registered groups (`core`, `config`, `scripts`, `mcp`, `slack`, `tracker`, `skills`, `repo`) so legacy lists don't silently lose those tools — edit or delete the seeded row to take full control. Note: this shapes the externally exposed MCP tool list only — it is not a feature kill-switch. The scripts SDK bridge always sees the full tool surface (governed by its own allowlist), and HTTP REST routes are generally not gated. See MCP tools reference for the tool-to-capability mapping.
`SKILL_FILES_MAX_COUNT`	`100`	Max number of files allowed in a single skill file-set upsert.
`SKILL_FILES_MAX_FILE_BYTES`	`512000` (500 KB)	Max size in bytes for a single file within a skill file-set upsert.
`SKILL_FILES_MAX_TOTAL_BYTES`	`10485760` (10 MB)	Max combined size in bytes for all files in a single skill file-set upsert.
`BUDGET_ADMISSION_DISABLED`	`false`	Operator escape hatch — set to `true` at process boot to make budget admission always return allowed, bypassing the agent/global/user daily-spend budget gates on task claiming.
`MULTI_RUNTIME_ENABLED`	`true`	Lets several worker processes serve one logical agent. Set consistently on the API server and every worker; runtimes sharing an `AGENT_ID` need compatible workspace state. The agent-scoped `AGENT_MAX_TASKS` setting remains the shared logical task limit.
`HEARTBEAT_INTERVAL_MS`	`90000`	Heartbeat sweep interval (ms)
`HEARTBEAT_CHECKLIST_DISABLE`	`false`	Set to `true` or `1` to disable the periodic `HEARTBEAT.md` checklist polling loop and the boot-triage task (separate from the infrastructure sweep). `false` and `0` keep it on.
`HEARTBEAT_CHECKLIST_INTERVAL_MS`	`1800000`	Interval (ms) between `HEARTBEAT.md` checklist checks (default 30 min). `0` turns the recurring check off; boot triage still runs.
`HEARTBEAT_DISABLE`	`false`	Set to `true` to disable the heartbeat module
`HEARTBEAT_STALL_THRESHOLD_MIN`	`30`	Minutes before an in-progress task is considered stalled
`HEARTBEAT_STALL_NO_SESSION_MIN`	`5`	Minutes before an in-progress task with no active worker session is considered stalled
`HEARTBEAT_STALL_STALE_HB_MIN`	`15`	Minutes before an in-progress task with a stale worker heartbeat is considered stalled
`HEARTBEAT_STALE_CLEANUP_MIN`	`30`	Minutes before stale resources (sessions, reviewing tasks) are cleaned up
`HEARTBEAT_MAX_AUTO_ASSIGN`	`5`	Max pool tasks to auto-assign per sweep
`HEARTBEAT_MAX_RESUME_GENERATIONS`	`3`	Max crash-recovery resume generations for a task before it is failed for Lead triage instead of resumed again
`HEARTBEAT_PIN_CRASH_RESUME`	`true` (on)	Rollback kill-switch for pinning `crash_recovery` resumes back to their original agent. Set to `0` to restore the pre-pin behavior requiring the `WORKER_LIVENESS_WINDOW_SECONDS` freshness check
`HEARTBEAT_PIN_GRACEFUL_RESUME`	`true` (on)	Rollback kill-switch for pinning `graceful_shutdown` resumes back to their original agent. Set to `0` to restore the old pool-based follow-up path
`HEARTBEAT_RESUME_PIN_GRACE_MIN`	`10`	Grace window (minutes) a same-agent-pinned crash-recovery or graceful-shutdown resume waits before the reaper escalates it to a Lead re-delegation decision. Set to `0` to disable the reaper
`RUNTIME_STALE_THRESHOLD_MIN`	`5`	Minutes without runtime traffic before an active runtime stops counting and the heartbeat sweep retires it. Used only when `MULTI_RUNTIME_ENABLED` is on.
`APPROVAL_REQUEST_AUTO_CANCELLATION_DAYS`	`7`	Days a pending approval request with no explicit timeout waits before the heartbeat cancels it. A request that gates a running or waiting workflow run cancels that run too. Set to `0` to disable
`MODEL_LATEST_SOAK_DAYS`	`2`	Days a newly released model must age before a `latest:<provider>/<target>@stable` model-tier alias can resolve to it. `0` disables the soak. `@any` aliases ignore it
`MODEL_AUTO_UPGRADE`	`true`	Set to `false` or `0` to freeze each `latest:` model-tier alias at its last recorded resolution (an alias never resolved before still resolves once). See Model tiers
`WORKER_LIVENESS_WINDOW_SECONDS`	`30`	Seconds within which a worker's last-activity timestamp must be fresh to be treated as "online" for resume pre-assignment / same-agent crash-pin freshness checks

Encryption key resolution (see Encryption Key for the full guide):

SECRETS_ENCRYPTION_KEY env var
SECRETS_ENCRYPTION_KEY_FILE env var (path to a file containing the key)
<data-dir>/.encryption-key on the API's data volume
Auto-generated on first boot only when the DB does not yet contain encrypted secret rows

Losing the key while keeping the database means losing every encrypted secret with no recovery path. Back up the key alongside every database backup.

Docker Worker Variables

Harness Provider

Variable	Required	Default	Description
`HARNESS_PROVIDER`	No	`claude`	AI provider: `claude` (Claude Code), `codex`, `opencode`, `pi` (pi-mono), `devin` (Devin), or `claude-managed` (Anthropic Managed Agents). See Harness Configuration

Credentials

Which credentials you need depends on your selected harness provider:

Claude Code (HARNESS_PROVIDER=claude, default):

Variable	Required	Default	Description
`CLAUDE_CODE_OAUTH_TOKEN`	Yes*	—	OAuth token for Claude CLI. Supports comma-separated values for multi-credential load balancing
`ANTHROPIC_API_KEY`	Alt*	—	Alternative to `CLAUDE_CODE_OAUTH_TOKEN`. Also supports comma-separated values
`SWARM_USE_CLAUDE_BRIDGE`	No	`false`	Reloadable boolean (`true`/`1` enables, `false`/`0`/unset disables). When enabled, the Claude adapter routes through the installed `claude-bridge` binary from pinned package `@desplega.ai/claude-bridge@0.2.2`, a Desplega-owned `claude -p` drop-in that drives interactive Claude Code through `tmux`. Requires Bun, `claude`, and `tmux` on PATH. Claude Bridge requires `CLAUDE_CODE_OAUTH_TOKEN`; if only `ANTHROPIC_API_KEY` is present, the adapter logs a warning and falls back to stock `claude`. See Claude Bridge.
`CLAUDE_BINARY`	No	`claude`	Low-level argv prefix for the Claude CLI. Accepts a single binary name (`claude`), an absolute path, or a whitespace-separated command string. Legacy bridge commands remain supported only as a deprecated compatibility path; prefer `SWARM_USE_CLAUDE_BRIDGE=true`. Reloadable via `swarm_config` (precedence: repo > agent > global > env > `claude`) so you can flip a worker via `set-config CLAUDE_BINARY=...` without a container restart.
`ENABLE_PROMPT_CACHING_1H`	No	`1`	Enables Anthropic's 1-hour prompt cache for every Claude Code session spawned by the worker. Default-on since `v1.69.1`; set to `0` (env or `swarm_config`) to opt out. Injected by `ClaudeAdapter` into the spawned `claude` process env.

* One of CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY is required.

pi-mono (HARNESS_PROVIDER=pi):

Variable	Required	Default	Description
`ANTHROPIC_API_KEY`	One of*	—	Anthropic API key for Claude models via pi-mono
`OPENROUTER_API_KEY`	One of*	—	OpenRouter API key for multi-provider model access
`OPENROUTER_BASE_URL`	No	`https://openrouter.ai/api/v1`	OpenAI-compatible gateway used for OpenRouter model and summarizer traffic. Any chat-completions gateway works — see Model Gateways
`BEDROCK_AUTH_MODE`	No	inferred from `MODEL_OVERRIDE`	Optional Bedrock mode override. `sdk` uses the AWS SDK credential chain; `bearer` requires `AWS_BEARER_TOKEN_BEDROCK`. Both probe credentials and enumerate models
`AWS_BEARER_TOKEN_BEDROCK`	In Bedrock bearer mode	—	Bedrock API key required when `BEDROCK_AUTH_MODE=bearer`
`AWS_REGION`	In either Bedrock mode	—	Required region for Bedrock credential probing and account-accurate model enumeration in SDK or bearer mode
`PI_TOOL_DEFERRAL`	No	`false`	Reloadable boolean. Hides non-core swarm tools behind pi's `tool_search`. See pi tool deferral
`PI_CODEMODE`	No	`false`	Reloadable boolean. Adds pi's codemode tool, a bounded QuickJS sandbox in which the model's JavaScript calls swarm tools. See pi codemode

* At least one credential source is required (API key, ~/.pi/agent/auth.json, or the AWS SDK default chain in Bedrock SDK mode). Do not pass CLAUDE_CODE_OAUTH_TOKEN when using pi-mono — it will override the configured provider. See Harness Configuration and Harness Providers for details.

Codex (HARNESS_PROVIDER=codex):

Variable	Required	Default	Description
`OPENAI_API_KEY`	Optional	—	Standard OpenAI API key for Codex
`API_KEY`	Yes	—	Swarm API key used to fetch `codex_oauth` from the config store
`MCP_BASE_URL`	Yes	`http://host.docker.internal:3013`	Swarm API URL reachable by the worker
`CODEX_SKILLS_DIR`	No	`~/.codex/skills`	Directory used by the Codex inline slash-command resolver to find `<name>/SKILL.md` (mirrors `OPENCODE_SKILLS_DIR`)
`CODEX_PATH_OVERRIDE`	No	Set automatically in the Docker image (`/usr/bin/codex`)	Absolute path to the Codex CLI wrapper or binary. The app-server transport invokes this path with `app-server --listen stdio://`. Use it for non-Docker or custom installs.
`AGENT_SWARM_CODEX_RUNNER_ARGV`	No	Inferred from `process.argv` (dev vs. compiled-binary layout)	JSON-encoded string array overriding the argv prefix used to re-launch the `codex-session-runner` subprocess. Niche escape hatch for nonstandard install/packaging layouts
`NODE_EXTRA_CA_CERTS`	No	—	Path to an extra CA certificate bundle, forwarded to the spawned Codex CLI subprocess so it trusts custom/corporate CAs on outbound HTTPS calls

Codex can also authenticate through ~/.codex/auth.json, including ChatGPT OAuth restored from the swarm config store. See Provider Auth: Codex OAuth.

opencode (HARNESS_PROVIDER=opencode):

Variable	Required	Default	Description
`OPENROUTER_API_KEY`	One of*	—	OpenRouter API key (primary — unlocks 100+ models at openrouter.ai)
`OPENROUTER_BASE_URL`	No	`https://openrouter.ai/api/v1`	OpenAI-compatible gateway used by the OpenRouter provider, model refreshes, and the session summarizer plugin. Any chat-completions gateway works — see Model Gateways
`ANTHROPIC_API_KEY`	One of*	—	Anthropic API key for Claude models
`OPENAI_API_KEY`	One of*	—	OpenAI API key for GPT models
`OPENCODE_BINARY`	No	`opencode`	Path to the opencode CLI binary (if not in `$PATH`)
`OPENCODE_SKILLS_DIR`	No	`~/.opencode/skills`	Directory used by the OpenCode inline resolver for `/<skill>` prompts
`OPENCODE_SERVER_TIMEOUT_MS`	No	`30000`	Timeout (ms) for the opencode SDK's server-start call; override when cold-start on slow disks (e.g. E2B) exceeds the SDK's own 5s default and spawn fails with "Timeout waiting for server to start"
`OPENCODE_SWARM_PLUGIN_PATH`	No	Set automatically in the Docker image	Explicit override for the absolute path to the agent-swarm opencode plugin entrypoint; falls back to the Docker path if present, else a dev-relative path from source
`CONTEXT_MODE_OPENCODE_PLUGIN_PATH`	No	Auto-discovered under the global npm root	Override for the absolute path to context-mode's built opencode plugin entry, used when the default global npm-root search can't find it — otherwise context-mode is silently skipped for that session
`MODEL_OVERRIDE`	No	`openrouter/qwen/qwen3-coder-flash`	Model string passed to opencode. Use `provider/model-id` format (e.g. `anthropic/claude-sonnet-4-6`, `openai/gpt-4o`)

* At least one of OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, or ~/.local/share/opencode/auth.json is required.

Devin (HARNESS_PROVIDER=devin):

Variable	Required	Default	Description
`DEVIN_API_KEY`	Yes	—	Devin API key (prefix: `cog_*`)
`DEVIN_ORG_ID`	Yes	—	Devin organization ID (prefix: `org-*`)
`DEVIN_POLL_INTERVAL_MS`	No	`15000`	Polling interval for Devin session events (ms)
`DEVIN_ACU_COST_USD`	No	`2.25`	USD per ACU for cost tracking
`DEVIN_API_BASE_URL`	No	`https://api.devin.ai`	Devin API base URL (override for testing)
`DEVIN_MAX_ACU_LIMIT`	No	—	Per-session ACU cap (sent to Devin API + UI budget bar)
`MAX_SKILL_CHARS`	No	`100000`	Max chars for inlined `SKILL.md` content
`HAS_MCP`	Conditional	`false`	Declares whether the Devin environment/session has MCP tool access. `true` is not yet supported and throws at session creation; a Devin worker configured with `AGENT_ROLE=lead` also requires MCP access, since a lead needs the MCP to function
`DEVIN_SKILLS_DIR`	No	`<project-root>/plugin/pi-skills`	Directory used by the Devin inline `@skills:<name>` resolver to find `SKILL.md` files

Starter env file: .env.docker-devin.example at the repo root.

Claude Managed Agents (HARNESS_PROVIDER=claude-managed):

Variable	Required	Default	Description
`ANTHROPIC_API_KEY`	Yes	—	Anthropic API key (used by both the setup CLI and the runtime adapter)
`MANAGED_AGENT_ID`	Yes	—	Anthropic Agent ID. Written by `claude-managed-setup`
`MANAGED_ENVIRONMENT_ID`	Yes	—	Anthropic Environment ID. Written by `claude-managed-setup`
`MCP_BASE_URL`	Yes	—	Must be HTTPS-public so Anthropic's sandbox can reach `/mcp`. Worker fails fast at boot otherwise
`MANAGED_AGENT_MODEL`	No	`claude-sonnet-5`	Default model on `sessions.create`; per-task `task.model` overrides
`MANAGED_GITHUB_VAULT_ID`	No	—	Anthropic vault ID holding a GitHub PAT, for repo-bound tasks (recommended for prod)
`MANAGED_GITHUB_TOKEN`	No	—	Literal GitHub PAT injected as `authorization_token` on `github_repository` resources (dev-only fallback)
`MANAGED_MCP_VAULT_ID`	No	—	Anthropic vault ID holding the static-bearer credential for the swarm's `/mcp` endpoint, passed via `vault_ids` on `sessions.create` alongside `MANAGED_GITHUB_VAULT_ID`. Written by `claude-managed-setup` and auto-restored from `swarm_config` at worker boot
`CLAUDE_MANAGED_RUNTIME_FEE_USD_PER_HOUR`	No	`0.08`	USD-per-session-hour runtime fee used by the local cost snapshot shown in worker logs before the API server's canonical pricing table recomputes the final cost. Override for ops pricing bumps without a redeploy

Run the one-time bunx @desplega.ai/agent-swarm claude-managed-setup from your laptop to bootstrap the Anthropic-side Agent + Environment and persist IDs into swarm_config. See Harness Configuration § Claude Managed Agents.

General Worker Settings

Variable	Required	Default	Description
`API_KEY`	Yes	—	API key for MCP server
`AGENT_ID`	No	Auto-generated	Agent UUID. Keep stable for task resume
`AGENT_ROLE`	No	`worker`	Role: `worker` or `lead`
`AGENT_NAME`	No	Auto-generated	Display name for the agent
`MCP_BASE_URL`	No	`http://host.docker.internal:3013`	MCP server URL
`WORKER_API_READY_TIMEOUT_SECONDS`	No	`90`	Positive-integer deadline for `docker-entrypoint.sh` to reach `${MCP_BASE_URL}/health` before provider-specific setup. This is bootstrap-only: set it in the worker/lead container environment rather than only in `swarm_config`.
`SESSION_ID`	No	Auto-generated	Log folder name
`LOG_DIR`	No	`/logs`	Base directory for session `.jsonl` log files (`<LOG_DIR>/<sessionId>/<timestamp>-<taskId8>.jsonl`)
`YOLO`	No	`false`	Continue on errors
`SYSTEM_PROMPT`	No	—	Custom system prompt text
`SYSTEM_PROMPT_FILE`	No	—	Path to system prompt file
`CONTEXT_MODE_DISABLED`	No	`false`	Set to `true` to disable the default context-mode MCP wiring for local Claude Code, Codex, and opencode workers. Leaves the worker running but hides/skips the `ctx_*` tools.
`SCRIPTS_ONLY_MCP`	No	`false`	Experimental code-mode. Set alongside the API server value so worker prompts explain the reduced eight-tool MCP surface; all other swarm operations remain available through `script-run` and the scripts SDK.
`CONTEXT_MODE_EXTERNAL_MCP_NUDGE_EVERY`	No	`3`	How often (in turns) the context-mode MCP plugin surfaces its external-MCP guidance nudge, across Claude Code, Codex, and opencode alike
`CONTEXT_PREAMBLE_MAX_TOKENS`	No	`2000`	Token budget for the universal follow-up context preamble prepended to a child task's prompt; applies across all harness providers
`CONTEXT_PREAMBLE_RESUME_MAX_TOKENS`	No	`4000`	Token budget for the resume-task preamble (2x the regular budget — carries the original task brief plus a tool-call summary so the resumed agent doesn't redo completed work)
`STARTUP_SCRIPT_STRICT`	No	`false`	Exit on startup script failure. By default, per-agent `setupScript` failures log a v1.106.0 privilege-boundary migration warning and the worker continues booting
`SHUTDOWN_TIMEOUT`	No	`30000`	Grace period (ms) before pausing tasks
`MAX_CONCURRENT_TASKS`	No	`1`	Maximum parallel tasks per worker
`SWARM_URL`	No	`localhost`	Base domain for service URLs
`LEAD_PORT`	No	`3020`	Host port for lead service. Example variable used in `docker-compose.example.yml` — adjust to your setup. In isolated network namespaces all services can share the same port.
`WORKER1_PORT`	No	`3021`	Host port for worker-1 service. Example — see `LEAD_PORT`.
`WORKER2_PORT`	No	`3022`	Host port for worker-2 service. Example — see `LEAD_PORT`.
`PM2_HOME`	No	`/workspace/.pm2`	PM2 state directory
`TEMPLATE_ID`	No	—	Template for initial profile on first boot (e.g., `official/coder`)
`TEMPLATE_REGISTRY_URL`	No	`https://templates.agent-swarm.dev`	URL of the templates registry
`MODEL_TIER_MAP`	No	—	JSON object overriding portable tier-to-model resolution for the current worker, for example `{\"smol\":\"gpt-5.4-mini\",\"smart\":\"gpt-5.5\"}`. Applies when a task, schedule, or workflow uses `modelTier`.
`MODEL_TIER_<TIER>`	No	—	Per-tier override for `smol`, `regular`, `smart`, or `ultra` (for example `MODEL_TIER_SMART=gpt-5.5`). Wins over `MODEL_TIER_MAP`.
`SWARM_DEP_POSTGRES_ENABLED`	No	`false`	Set to `true` to start the optional bundled PostgreSQL 16 cluster on worker boot. The root-stage entrypoint runs `scripts/init-local-postgres.sh` before privilege drop; binaries ship dormant in the worker image since `v1.93.0`
`LOCAL_POSTGRES_DATA_DIR`	No	`/tmp/postgres-data`	Data directory for the optional local Postgres cluster
`LOCAL_POSTGRES_PORT`	No	`5433`	Port for the optional local Postgres cluster
`LOCAL_POSTGRES_USER`	No	`postgres`	Superuser name for the optional local Postgres cluster
`LOCAL_POSTGRES_PASSWORD`	When local Postgres is enabled	None	Explicit non-empty superuser password; applied to new and existing clusters on each helper invocation
`LOCAL_POSTGRES_DB`	No	`app`	Database created in the optional local Postgres cluster

Git Configuration

Variable	Default	Description
`GITHUB_TOKEN`	—	GitHub token for git operations
`GITHUB_EMAIL`	`worker-agent@desplega.ai`	Git commit email
`GITHUB_NAME`	`Worker Agent`	Git commit name

Slack Integration

Variable	Description
`SLACK_MODE`	Transport selection: `socket` (default) or `http`. Invalid values fail closed. HTTP is configuration-only until its receiver is installed and never falls back to Socket Mode.
`SLACK_BOT_TOKEN`	Bot User OAuth Token (`xoxb-...`), required in both modes
`SLACK_APP_TOKEN`	App-Level Token for Socket Mode (`xapp-...`), required only in `socket` mode
`SLACK_SIGNING_SECRET`	Signing Secret, required only in `http` mode
`SLACK_DISABLE`	Set to `true` to disable Slack
`SLACK_ALLOW_DEV_SOCKET_MODE`	Set to `true` to explicitly allow a `NODE_ENV=development` API process to connect through Socket Mode (default: `false`)
`SLACK_RENDER_V2`	One persistent task tree per physical Slack thread plus streamed, immutable outcome cards (default: `true`; set `false` to opt out)
`SLACK_WORK_OBJECTS_ENABLED`	Set to `true` to populate task Work Object flexpanes (default: `false`). Apply the updated Slack manifest, reinstall the app, and enable Work Object Previews. See Slack setup.
`SLACK_RENDER_V2_DELEGATION`	Set to `true` to defer an ask's conclusion card until its whole closure (delegated tasks, children, follow-ups) settles, post child result cards, and gate the checkmark reaction on the closure instead of the ask alone. Requires `SLACK_RENDER_V2=true` (default: `false`)
`SLACK_CONCLUSION_SETTLE_SEC`	Quiet seconds after a closure goes fully terminal before its conclusion card posts (default: `10`)
`SLACK_CONCLUSION_TIMEOUT_MIN`	Idle minutes before a closure concludes with unfinished work and a `warning` reaction (default: `240`)
`SLACK_TREE_STALL_MIN`	Minutes without a task update before the thread tree shows a stalled glyph for that task (default: `15`)
`SLACK_ALLOWED_EMAIL_DOMAINS`	Comma-separated email domains
`SLACK_ALLOWED_USER_IDS`	Comma-separated user IDs to always allow
`ADDITIVE_SLACK`	Set to `true` to enable non-mention thread message buffering and batching
`ADDITIVE_SLACK_BUFFER_MS`	Debounce window for thread buffer in ms (default: `10000`)
`SLACK_THREAD_FOLLOWUP_REQUIRE_MENTION`	Set to `true` to require @mention for thread follow-up routing (default: `false`)
`LEAD_MONITOR_CHANNELS`	Set to `true` to have the lead agent additionally poll monitored Slack channels for non-mention activity (not just @mentions/DMs), throttled to once per 60s per poll cycle
`LEAD_MONITOR_CHANNEL_IDS`	Comma-separated Slack channel IDs allowlist restricting `LEAD_MONITOR_CHANNELS` activity monitoring to specific channels. Unset monitors every channel the bot is a member of
`SLACK_ALERTS_CHANNEL`	Slack channel ID/name for setup-blocked automation, OAuth/Jira keepalive failures, and claimable-queue stall/recovery alerts. Repeated identical schedule setup failures are suppressed within a UTC day; workflow setup alerts are limited to one per workflow per UTC day. Unset means alerts are logged only, not sent

GitHub Integration

Variable	Description
`GITHUB_WEBHOOK_SECRET`	Webhook secret for GitHub App
`GITHUB_BOT_NAME`	Bot name for @mentions (default: `agent-swarm-bot`)
`GITHUB_BOT_ALIASES`	Comma-separated additional @mention aliases (e.g. `heysidekick,sidekick`)
`GITHUB_EVENT_LABELS`	Comma-separated labels that trigger agent action on PR/issue label events (default: `swarm-review`)
`GITHUB_APP_ID`	GitHub App ID (for bot reactions)
`GITHUB_APP_PRIVATE_KEY`	GitHub App private key (base64-encoded)
`GITHUB_DISABLE`	Set to `true` to disable GitHub

GitLab Integration

Variable	Description
`GITLAB_TOKEN`	GitLab PAT or Group Access Token for API calls
`GITLAB_URL`	GitLab instance URL (default: `https://gitlab.com`)
`GITLAB_WEBHOOK_SECRET`	Shared secret for webhook verification
`GITLAB_BOT_NAME`	Bot username for @mention detection (default: `agent-swarm-bot`)
`GITLAB_EMAIL`	Git commit email for GitLab repos
`GITLAB_NAME`	Git commit name for GitLab repos
`GITLAB_DISABLE`	Set to `true` to disable GitLab integration

AgentMail Integration

Variable	Description
`AGENTMAIL_DISABLE`	Set to `true` to skip AgentMail integration
`AGENTMAIL_WEBHOOK_SECRET`	Svix signing secret for webhook verification
`AGENTMAIL_INBOX_DOMAIN_FILTER`	Comma-separated domains to allow for incoming inbox webhooks (e.g., `yourdomain.com,example.com`). Unmatched inbox domains are silently dropped
`AGENTMAIL_SENDER_DOMAIN_FILTER`	Comma-separated sender domains to allow (e.g., `gmail.com,company.com`). Unmatched sender domains are silently dropped
`ADDITIVE_AGENTMAIL`	Set to `true` to enable non-mention thread message buffering and batching for AgentMail, mirroring `ADDITIVE_SLACK`
`ADDITIVE_AGENTMAIL_BUFFER_MS`	Debounce window (ms) for buffering rapid AgentMail follow-up messages into a single task when `ADDITIVE_AGENTMAIL=true` is set (default: `10000`)

Kapso / WhatsApp Integration

Variable	Description
`KAPSO_API_KEY`	Kapso API key used for outbound sends and optional webhook registration (`X-API-Key`)
`KAPSO_PHONE_NUMBER_ID`	Default WhatsApp Business phone-number ID the swarm sends from
`KAPSO_WEBHOOK_HMAC_SECRET`	Shared secret used to verify Kapso's `X-Webhook-Signature` header on inbound webhooks
`KAPSO_API_BASE_URL`	Optional Kapso API base URL override (default: `https://api.kapso.ai`)

Setup Steps

Set the values above in your .env or integrations dashboard.
Have the lead call register-kapso-number to point the number at /api/integrations/kapso/webhook and store the routing mapping.
Use send-whatsapp-message / reply-whatsapp-message for the common text path, or the kapso-whatsapp skill for templates, media, and reactions.

Sentry Integration

Variable	Description
`SENTRY_AUTH_TOKEN`	Sentry Organization Auth Token
`SENTRY_ORG`	Sentry organization slug

Linear Integration

Variable	Description
`LINEAR_DISABLE`	Set to `true` to disable Linear integration
`LINEAR_CLIENT_ID`	OAuth app client ID (create at Linear > Settings > API > Applications)
`LINEAR_CLIENT_SECRET`	OAuth app client secret (shown once on creation)
`LINEAR_REDIRECT_URI`	OAuth callback URL (e.g., `http://localhost:3013/api/trackers/linear/callback`)
`LINEAR_SIGNING_SECRET`	Webhook signing secret from Linear app settings
`LINEAR_ALLOWED_STATES`	CSV of `WorkflowState.type` values that trigger task creation. Default: `unstarted,started,completed,canceled` (i.e. skip Backlog & Triage). Set to empty to lock down everything but the label override. See Linear integration → State gate.
`LINEAR_SWARM_READY_LABEL`	Label name (case-insensitive) that bypasses the state gate. Default: `swarm-ready`.

Setup Steps

Create an OAuth app at Linear > Settings > API > Applications
Set Actor to "Application"
Set Callback URL to your /api/trackers/linear/callback endpoint
Enable "Agent session events" in webhook settings
Set Webhook URL to your /api/trackers/linear/webhook endpoint
Copy Client ID, Client Secret, and Webhook Signing Secret
Start the server, then visit /api/trackers/linear/authorize to complete OAuth

With portless: set LINEAR_REDIRECT_URI=https://api.swarm.localhost:1355/api/trackers/linear/callback

Jira Integration

Variable	Description
`JIRA_DISABLE`	Set to `true` to disable Jira integration (or set `JIRA_ENABLED=false`)
`JIRA_CLIENT_ID`	OAuth 2.0 (3LO) app client ID from Atlassian (developer.atlassian.com > My Apps > Settings). Its presence also gates whether the Jira integration initializes at all
`JIRA_CLIENT_SECRET`	OAuth client secret paired with `JIRA_CLIENT_ID`
`JIRA_REDIRECT_URI`	OAuth callback URL override — must match exactly what's registered in the Atlassian app. Defaults to `<PUBLIC_MCP_BASE_URL or MCP_BASE_URL>/api/trackers/jira/callback`
`JIRA_WEBHOOK_TOKEN`	High-entropy token embedded in the registered webhook URL path — Atlassian's 3LO webhooks aren't HMAC-signed, so this is the sole inbound auth mechanism. Generate with `openssl rand -hex 32`. Webhook register/receive endpoints return 503 until it's set

Setup Steps

Create an OAuth 2.0 (3LO) app at developer.atlassian.com > My Apps
Add scopes: read:jira-work, write:jira-work, manage:jira-webhook, offline_access, read:me
Set the callback URL to your /api/trackers/jira/callback endpoint
Copy the Client ID and Client Secret
Generate a webhook token (openssl rand -hex 32) and set JIRA_WEBHOOK_TOKEN
Start the server, then visit /api/trackers/jira/authorize to complete OAuth
Register the dynamic webhook via POST /api/trackers/jira/webhook-register (admin, requires the swarm API key)

See the Jira Integration guide for the full walkthrough, webhook lifecycle, and known limitations.

Composio Integration

Environment variables for the Composio Tool Router integration, used by agent-swarm x composio and the swarm_x MCP tool to call third-party APIs through Composio.

Variable	Description
`COMPOSIO_API_KEY`	Project API key, sent as `x-api-key` on Composio requests
`COMPOSIO_ORG_API_KEY`	Optional organization key, sent as `x-org-api-key` when `--org` is passed
`COMPOSIO_BASE_URL`	Optional API base URL override (default: `https://backend.composio.dev/api/v3.1`)

Portless (Local Development)

Portless replaces port-based URLs with friendly domain names for local development.

Variable	With Portless	Description
`MCP_BASE_URL`	`https://api.swarm.localhost:1355`	API server URL
`APP_URL`	`https://ui.swarm.localhost:1355`	Dashboard URL

Install: bun add -g portless. Enable HTTPS: portless trust && portless proxy start --https.

UI Development Server

Variable	Default	Description
`VITE_PROXY_TARGET`	`http://localhost:3013`	Overrides the API origin the `ui/` Vite dev server (`bun run dev`, port 5274) proxies `/api`, `/health`, and `/status` requests to. Set when the API is running on a non-default port or host during local dashboard development.
`VITE_API_URL`	unset	Fixes a dedicated dashboard build to one API origin. Requires `VITE_API_KEY`. The connection switcher becomes a static label.
`VITE_API_KEY`	unset	Fixes the API credential for `VITE_API_URL`. Connection settings become read-only.
`VITE_USER_ID`	unset	Fixes the dashboard identity to an existing user. Requires `VITE_API_URL` and `VITE_API_KEY`.
`VITE_DEMO_MODE`	`false`	Shows a diagonal live demo ribbon when set to `true` or `1`.
`VITE_PLAUSIBLE_ANALYTICS`	unset	Build-time flag. Set to `1` to inject the Plausible analytics snippet into the dashboard's `index.html` during `bun run build`. Only our hosted dashboard sets it; self-hosted and local builds ship with no analytics script.
`VITE_PLAUSIBLE_SCRIPT_ID`	hosted dashboard's id	Plausible site script id (the `pa-<id>.js` part of the snippet) used when `VITE_PLAUSIBLE_ANALYTICS` is on. Set it on a second deployment, such as the public demo, so it reports to its own Plausible site.

Vite includes every VITE_* value in public browser assets. Use a restricted credential and a demo-safe API deployment for fixed public dashboards.

Cloud Personalization & Adaptive Home

Identity envs that brand the swarm and gate cloud-only UX. All are read on every GET /status call (cheap — env reads + one SQL aggregate, no upstream calls). See the Personalization & Status guide for the full story.

Variable	Default	Description
`SWARM_CLOUD`	`false`	When `true`, marks the deployment as cloud-hosted. Surfaces Docs/Support/Billing items in the user-menu, suppresses the self-host marketing footer, and is sent as `metadata.is_cloud` (always present) on every telemetry event
`SWARM_ORG_NAME`	`Swarm`	Sidebar header name. Also sent as `metadata.organization_name` on every telemetry event when set
`SWARM_ORG_ID`	none	Stable org/tenant identifier exposed on `/status` as `identity.org_id` and sent as `metadata.organization_id` on every telemetry event when set. Set by the orchestrator on cloud deployments
`SWARM_ORG_LOGO_URL`	bundled `/logo.png`	Sidebar logo URL (any HTTPS URL). Falls back to the bundled logo if it fails to load
`SWARM_BRAND_COLOR`	none	Tints the org name in the sidebar header (any CSS color, e.g. `#a855f7`)
`SWARM_MARKETING_URL`	none	Self-host marketing footer link target. Suppressed when `SWARM_CLOUD=true` or `SWARM_HIDE_CLOUD_PROMO=true`
`SWARM_HIDE_CLOUD_PROMO`	`false`	Force-hide the marketing footer regardless of `SWARM_CLOUD`
`SWARM_VERIFY_TTL_MS`	`3600000` (1h)	How long a successful "Test connection" click keeps the harness milestone in `verified` state. In-memory; lost on API restart

Agent Filesystem (agent-fs)

Variable	Description
`AGENT_FS_API_URL`	Agent-fs API URL. When unset, the server uses `local-fs`; when set as env or global swarm config, it enables the persistent shared filesystem provider
`AGENT_FS_LIVE_URL`	Agent-fs live host used to build shareable file links (`<AGENT_FS_LIVE_URL>/file/~/<org_id>/<drive_id>/<file_path>`). Falls back to the public `https://live.agent-fs.dev` host when unset; self-hosted agent-fs operators should override it
`API_AGENT_FS_API_KEY`	API-owned bootstrap/service API key for agent-fs. Used only by the API server to seed the swarm org/drive and invite/register agents
`AGENT_FS_API_KEY`	Per-agent API key for agent-fs CLI/MCP access. Generated by the API server and stored as an agent-scoped secret; workers should not share the API bootstrap key
`AGENT_FS_SHARED_ORG_ID`	Shared org ID for the swarm's agent-fs organization. Auto-created by the lead on first boot
`AGENT_FS_DEFAULT_ORG_ID`	Default agent-fs org ID used to auto-resolve `agent-fs` attachment rows on `store-progress` when `orgId` is missing. Scope precedence: agent > global
`AGENT_FS_DEFAULT_DRIVE_ID`	Default agent-fs drive ID used to auto-resolve `agent-fs` attachment rows on `store-progress` when `driveId` is missing. Scope precedence: agent > global

The no-config default is local-fs; set AGENT_FS_API_URL globally to keep shared agent-fs behavior. The API boot seeder registers a service identity with agent-fs on first boot, stores API_AGENT_FS_API_KEY as an encrypted global swarm config secret, creates the shared org/drive, and persists AGENT_FS_DEFAULT_*. Each runner then asks the API to create its own encrypted agent-scoped AGENT_FS_API_KEY. The two AGENT_FS_DEFAULT_* keys let the server fill in attachment IDs server-side so the renderer can emit full live-host URLs — per-row IDs always win, and missing config + missing row IDs still falls back to the agent-fs:<path> form.

Pages

Environment variables for the hosted Pages feature (DB-backed, agent-authored web pages). See MCP Tools Reference for the Pages tools.

Variable Description

PAGE_SESSION_SECRET HMAC-SHA256 secret for signing the page_session cookie. Reserved-like: not read from swarm_config, and never falls back to the swarm API key (that key's documented default is public). When unset, resolved via PAGE_SESSION_SECRET_FILE, then <dirname(DATABASE_PATH)>/.page-session-secret on disk, then auto-generated and persisted there on first use — mirrors SECRETS_ENCRYPTION_KEY's resolution order (see Encryption Key).

PAGE_SESSION_SECRET_FILE Alternative to PAGE_SESSION_SECRET: absolute path to a file whose contents are the secret. Useful with Docker secrets or k8s Secret volume mounts.

Variable	Description
`PAGE_SESSION_SECRET`	HMAC-SHA256 secret for signing the `page_session` cookie. Reserved-like: not read from `swarm_config`, and never falls back to the swarm API key (that key's documented default is public). When unset, resolved via `PAGE_SESSION_SECRET_FILE`, then `<dirname(DATABASE_PATH)>/.page-session-secret` on disk, then auto-generated and persisted there on first use — mirrors `SECRETS_ENCRYPTION_KEY`'s resolution order (see Encryption Key).
`PAGE_SESSION_SECRET_FILE`	Alternative to `PAGE_SESSION_SECRET`: absolute path to a file whose contents are the secret. Useful with Docker secrets or k8s `Secret` volume mounts.

x402 Payments

Environment variables for the x402 payment module, enabling agents to make USDC micropayments on x402-gated APIs.

Common

Variable	Default	Description
`X402_SIGNER_TYPE`	Auto-detected	Signer backend: `"openfort"` or `"viem"`. Auto-detects based on which credentials are set
`X402_MAX_AUTO_APPROVE`	`1.00`	Maximum USD amount to auto-approve per request
`X402_DAILY_LIMIT`	`10.00`	Daily spending limit in USD
`X402_NETWORK`	`eip155:84532`	CAIP-2 network ID. `eip155:84532` = Base Sepolia (testnet), `eip155:8453` = Base mainnet

Openfort Signer

Variable	Required	Description
`OPENFORT_API_KEY`	Yes	Openfort API key (`sk_test_` or `sk_live_` prefixed)
`OPENFORT_WALLET_SECRET`	Yes	P-256 ECDSA key for wallet authentication (base64 encoded)
`OPENFORT_WALLET_ADDRESS`	No	Reuse existing wallet address instead of creating a new one

Viem Signer

Variable	Required	Description
`EVM_PRIVATE_KEY`	Yes	Wallet private key (`0x`-prefixed hex). Use a burner wallet with minimal funds

Multi-Credential Support

To distribute load across multiple Claude subscriptions, provide multiple credentials as comma-separated values:

# Multiple OAuth tokens — one is randomly selected per session
CLAUDE_CODE_OAUTH_TOKEN=token1,token2,token3

# Also works with API keys
ANTHROPIC_API_KEY=sk-key1,sk-key2

When a session is spawned, the runner splits the credential value by commas and randomly selects one. Each session gets a single credential, distributing load across subscriptions. A log line indicates which credential index was selected (never the credential itself). Single values (no commas) work unchanged — fully backward compatible.

Telemetry

Variable	Default	Description
`ANONYMIZED_TELEMETRY`	`true` (enabled)	Set to `false` to disable anonymized telemetry. See Telemetry for details
`DESPLEGA_TELEMETRY_ENV`	`production`	Explicit telemetry environment tag. Set to `development` or `test` for intentional non-production telemetry.
`INSTALL_METHOD`	unset	Written automatically by the onboard wizard (`onboard_interactive` / `onboard_noninteractive`); not meant to be hand-set. Unset installs are attributed as `manual` (or `e2b` inside an E2B sandbox).
`INSTALL_PRESET`	unset	Written automatically by the onboard wizard with the chosen preset (e.g. `solo`), when applicable.

OpenTelemetry

OpenTelemetry traces and OTLP metrics are disabled unless OTEL_EXPORTER_OTLP_ENDPOINT is set. See Observability with OpenTelemetry for SigNoz setup, emitted spans, metric counters, and query examples.

Variable	Default	Description
`OTEL_EXPORTER_OTLP_ENDPOINT`	none	Base OTLP HTTP endpoint shared by traces and metrics. For SigNoz Cloud, use your region's ingest URL (e.g. `https://ingest.eu2.signoz.cloud`) and let the SDK append `/v1/traces` and `/v1/metrics`.
`OTEL_EXPORTER_OTLP_HEADERS`	none	OTLP exporter headers, for example `signoz-ingestion-key=<key>`. Treated as sensitive by the secret scrubber
`OTEL_EXPORTER_OTLP_PROTOCOL`	SDK default	Export protocol. Use `http/protobuf` for SigNoz Cloud
`OTEL_SERVICE_NAME`	`agent-swarm-api` or `agent-swarm-worker` outside local compose	OpenTelemetry `service.name`. Set to `agent-swarm` everywhere to keep one service and split by `agentswarm.service.role`
`OTEL_RESOURCE_ATTRIBUTES`	derived from `NODE_ENV`	Comma-separated resource attributes such as `deployment.environment=local,env=local,service.namespace=agent-swarm`
`OTEL_TRACE_POLL`	OFF	When set to `1`/`true`, emits trace spans for the worker poll loop (`worker.poll`) and the `/api/poll` HTTP endpoint. Skip by default to reduce span volume.
`OTEL_EXPORT_API_LOGS`	OFF	When set to `1`/`true` on the API, also exports its console output as OTLP log records to the same endpoint as traces, scrubbed of secrets. Read at startup.

Business-Use Instrumentation

Optional integration with @desplega.ai/business-use for tracking system invariants across the distributed API + worker architecture.

Variable	Description
`BUSINESS_USE_API_KEY`	API key from `uvx business-use-core@latest init`
`BUSINESS_USE_URL`	BU backend URL (default: `http://localhost:13370`)

SDK enters no-op mode if the API key is missing — safe to omit in environments without a BU backend.

Secrets Encryption

swarm_config rows with isSecret=1 are encrypted at rest using AES-256-GCM (v1.67.0+). The server resolves the encryption key on boot in this order:

SECRETS_ENCRYPTION_KEY env var (base64-encoded 32 bytes)
SECRETS_ENCRYPTION_KEY_FILE pointing at a file containing the base64 key
<data-dir>/.encryption-key file on disk
Auto-generated on first boot (only when the DB has no existing encrypted rows)

Generate a key with:

openssl rand -base64 32 > ./encryption_key
chmod 600 ./encryption_key

Back up and preserve the encryption key alongside your SQLite database. Losing the key means losing all encrypted secrets (API tokens, OAuth creds, etc.) with no recovery path. Do not switch between key sources unless the underlying base64 value is identical.

Reserved keys: API_KEY and SECRETS_ENCRYPTION_KEY are rejected by the swarm_config API (case-insensitive) and must remain environment-only.

Upgrading from plaintext: Legacy secrets are auto-migrated on first boot. If SECRETS_ENCRYPTION_KEY was not set beforehand, a one-time plaintext backup is created at <db-path>.backup.secrets-YYYY-MM-DD.env. Delete this file after verifying your key is backed up.

Priority

When both CLI flags and environment variables are set:

CLI flags take precedence over environment variables
Inline text (SYSTEM_PROMPT) takes precedence over file (SYSTEM_PROMPT_FILE)

Harness Configuration — Configure Claude Code or pi-mono provider settings
Deployment Guide — Production deployment with Docker Compose
CLI Reference — Terminal commands that complement environment variable configuration
MCP Tools Reference — Tools available to agents at runtime

Credentialed CORS wildcard patterns

CORS_ALLOWED_ORIGINS accepts exact origins and patterns such as https://*.agent-swarm.dev. A single leading *. matches one or more complete subdomain labels, including app.agent-swarm.dev and a.b.agent-swarm.dev, but never the apex agent-swarm.dev; list the apex separately if needed. Wildcard host comparison is case-insensitive. Schemes and explicit ports must match exactly; https://*.agent-swarm.dev:8443 only allows that port. Exact entries retain their existing case-sensitive comparison. Patterns reject evil-agent-swarm.dev, app.agent-swarm.dev.evil.com, and an http origin against an https pattern. Bare *, https://*, and wildcards in other positions are ignored, never treated as allow-all.

Breaking change: secure CORS defaults

Unset and blank values now use this built-in allowlist:

CORS_ALLOWED_ORIGINS=https://*.agent-swarm.dev,https://*.agent-swarm.cloud,http://localhost:5274,http://127.0.0.1:5274,http://[::1]:5274,https://ui.swarm.localhost:1355

A custom value replaces these defaults, including localhost. For an affected self-hosted SPA, set CORS_ALLOWED_ORIGINS=https://dashboard.example.com on the API (substitute its actual origin). Include every trusted origin you need, comma-separated. The hosted patterns exclude apex domains.

For arbitrary-origin bearer-token clients, set CORS_ALLOW_ANY_ORIGIN=true and use credentials: "omit" in browser requests. This permits non-credentialed CORS only. Cookie-authenticated responses, including page JSON and /@swarm/api/*, always require an allowlisted origin for Access-Control-Allow-Credentials; the flag cannot override that check. Only CORS_ALLOWED_ORIGINS takes effect after Configuration reload. The bypass is deployment-only: set it in the API environment and restart. Config writes through HTTP, MCP, or database helpers reject the reserved key; legacy stored values are ignored at startup and reload and can be deleted. The API warns once per process at startup or first use when the deployment opt-out is enabled. Denied-origin logs name the origin and CORS_ALLOWED_ORIGINS so a missing SPA origin is diagnosable. CORS controls browser response access; it does not replace authentication or CSRF protection.

On this page