Environment Variables

Complete reference for all environment variables used by Agent Swarm.

Server Variables

Variable	Default	Description
`PORT`	`3013`	Port for MCP HTTP server
`API_KEY`	—	API key for server authentication (required)
`MCP_BASE_URL`	`https://agent-swarm-mcp.desplega.sh`	Base URL for MCP server
`SWARM_URL`	`localhost`	Base domain for service discovery
`APP_URL`	—	Dashboard URL for Slack message links
`ENV`	—	Environment mode (`development` adds prefix to Slack agent names)
`DATABASE_PATH`	`./agent-swarm-db.sqlite`	SQLite database file path
`SCHEDULER_INTERVAL_MS`	`10000`	Polling interval for scheduled tasks (ms)
`OPENAI_API_KEY`	—	OpenAI key for memory embeddings
`CAPABILITIES`	All enabled	Comma-separated feature flags
`HEARTBEAT_INTERVAL_MS`	`90000`	Heartbeat sweep interval (ms)
`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_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

Docker Worker Variables

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
`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
`SESSION_ID`	No	Auto-generated	Log folder name
`YOLO`	No	`false`	Continue on errors
`SYSTEM_PROMPT`	No	—	Custom system prompt text
`SYSTEM_PROMPT_FILE`	No	—	Path to system prompt file
`STARTUP_SCRIPT_STRICT`	No	`true`	Exit on startup script failure
`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

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_BOT_TOKEN`	Bot User OAuth Token (`xoxb-...`)
`SLACK_APP_TOKEN`	App-Level Token for Socket Mode (`xapp-...`)
`SLACK_SIGNING_SECRET`	Signing Secret (optional for Socket Mode)
`SLACK_DISABLE`	Set to `true` to disable Slack
`SLACK_ALLOWED_EMAIL_DOMAINS`	Comma-separated email domains
`SLACK_ALLOWED_USER_IDS`	Comma-separated user IDs to always allow

GitHub Integration

Variable	Description
`GITHUB_WEBHOOK_SECRET`	Webhook secret for GitHub App
`GITHUB_BOT_NAME`	Bot name for @mentions (default: `agent-swarm-bot`)
`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

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

Sentry Integration

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

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.

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)

Environment Variables

On this page