Environment Variables

Reference for all environment variables used by swarm — both user-provided and runtime-injected.

User-Provided Variables

These variables must be set in your environment before running swarm:

VariableRequiredDescription
ANTHROPIC_API_KEYYes (default)API key for the Anthropic provider. The env var name can be overridden per-provider via api_key_env in config.
BRAVE_SEARCH_API_KEYNoAPI key for the Brave Search tool (used by web_search)
HOMEYesUser home directory. Used to locate ~/.swarm/settings.json and global skills at ~/.claude/skills/.

Runtime-Injected Variables

These variables are set by swarm and injected into each agent's backend session environment:

VariableValueDescription
SWARM_AGENT_IDAgent name (e.g., "backend")Identifies the current agent within the swarm session
SWARM_SESSION_IDSession ID (e.g., "20250115-a3f2")Unique identifier for the current session
SWARM_DB_PATHPath (e.g., .swarm/messages.db)Absolute path to the SQLite mailbox database
SWARM_AGENTSComma-separated names (e.g., "backend,frontend,reviewer")List of all agent names in the session

These variables allow agent tools and hooks to interact with the swarm infrastructure programmatically.

Logging

VariableDefaultDescription
RUST_LOGinfoControls log verbosity via the tracing crate. Set to debug for detailed output, warn for quieter operation. Supports per-module filtering (e.g., swarm=debug,rusqlite=warn).

Provider-Specific Variables

The API key environment variable name is configurable per provider:

{
  "providers": {
    "default": {
      "type": "anthropic",
      "api_key_env": "ANTHROPIC_API_KEY"
    },
    "custom": {
      "type": "anthropic",
      "api_key_env": "CUSTOM_ANTHROPIC_KEY"
    }
  }
}

MCP Server Variables

MCP servers configured with the env field receive those environment variables when launched:

{
  "mcpServers": {
    "myserver": {
      "transport": { "type": "stdio", "command": "my-mcp-server" },
      "env": {
        "MY_SERVER_TOKEN": "secret123"
      }
    }
  }
}