Config Schema

Complete reference for the ~/.swarm/settings.json configuration file.

Top-Level Structure

{
  "version": 2,
  "<project_path>": { ... }
}

Field	Type	Required	Description
`version`	`u64`	Yes	Schema version (must be `1` or `2`)
`<project_path>`	`ProjectConfig`	Yes	Project config keyed by absolute, canonicalized path

Multiple projects can be configured in the same file. Each is keyed by its absolute path.

ProjectConfig

Field	Type	Required	Default	Description
`agents`	`AgentConfig[]`	Yes	—	At least one agent definition
`supervisor`	`SupervisorConfig`	No	`null`	Supervisor configuration
`defaults`	`DefaultsConfig`	No	`null`	Project-wide defaults
`providers`	`Map<String, ProviderConfig>`	No	Implicit `"default"`	Named provider definitions
`permissions`	`PermissionsConfig`	No	`null`	Project-level permission rules
`hooks`	`HooksConfig`	No	`null`	Hook event handlers
`mcpServers`	`Map<String, McpServerConfig>`	No	`null`	MCP server connections
`wasm_tools`	`WasmToolConfig[]`	No	`null`	WASM sandboxed tools
`sub_agent_defaults`	`SubAgentLimits`	No	`null`	Default sub-agent spawning limits

AgentConfig

Field	Type	Required	Default	Description
`name`	`String`	Yes	—	Unique name (`[a-z][a-z0-9-]*`)
`prompt`	`String`	Yes	—	System prompt text or `@path/to/file`
`model`	`String`	No	`defaults.model` / `"sonnet"`	Model identifier
`provider`	`String`	No	`defaults.provider` / `"default"`	Provider name reference
`permissions`	`PermissionsConfig`	No	`null`	Agent-level permission overrides
`delegate_mode`	`bool`	No	`false`	Legacy delegate mode flag
`mode`	`String`	No	See cascade	Agent execution mode

SupervisorConfig

Field	Type	Required	Default	Description
`prompt`	`String`	No	Built-in merge prompt	Custom supervisor prompt or `@path`
`model`	`String`	No	`defaults.model`	Model identifier

DefaultsConfig

Field	Type	Required	Default	Description
`model`	`String`	No	`"sonnet"`	Default model
`provider`	`String`	No	`"default"`	Default provider reference
`session_timeout`	`u64`	No	`null`	Session timeout (seconds)
`commit_interval`	`u64`	No	`300`	Auto-commit interval (seconds)
`max_consecutive_errors`	`u32`	No	`5`	Consecutive error limit
`max_total_errors`	`u32`	No	`20`	Total error limit
`mode`	`String`	No	`null`	Default agent mode
`liveness`	`LivenessConfig`	No	See below	Liveness monitoring

ProviderConfig

Field	Type	Required	Default	Description
`type`	`String`	Yes	—	Provider type (`"anthropic"`)
`api_key_env`	`String`	No	`"ANTHROPIC_API_KEY"`	API key env var name
`base_url`	`String`	No	`null`	Custom API base URL
`max_retries`	`u32`	No	`null`	Max retries for transient errors
`timeout`	`u64`	No	`null`	Request timeout (seconds)

PermissionsConfig

Field	Type	Required	Default	Description
`allow`	`String[]`	No	`[]`	Allow rules (e.g., `"Bash(npm run *)"`)
`ask`	`String[]`	No	`[]`	Ask rules
`deny`	`String[]`	No	`[]`	Deny rules
`default_mode`	`String`	No	`null`	Default permission mode

LivenessConfig

Field	Type	Required	Default	Description
`enabled`	`bool`	No	`true`	Enable liveness monitoring
`idle_nudge_after_secs`	`u64`	No	`120`	Seconds before first nudge
`idle_nudge_interval_secs`	`u64`	No	`300`	Seconds between nudges
`max_nudges`	`u32`	No	`3`	Max nudges per idle episode
`idle_warn_after_secs`	`u64`	No	`600`	Seconds before warning hook
`stall_timeout_secs`	`u64`	No	`900`	Seconds before stall detection
`auto_interrupt_stalled`	`bool`	No	`false`	Auto-interrupt on stall

McpServerConfig

Field	Type	Required	Default	Description
`transport`	`McpTransport`	Yes	—	Transport configuration
`env`	`Map<String, String>`	No	`{}`	Environment variables

McpTransport (tagged union)

Stdio:

Field	Type	Required	Description
`type`	`"stdio"`	Yes	Transport discriminator
`command`	`String`	Yes	Command to execute
`args`	`String[]`	No	Command arguments

HTTP:

Field	Type	Required	Description
`type`	`"http"`	Yes	Transport discriminator
`url`	`String`	Yes	Server URL
`headers`	`Map<String, String>`	No	HTTP headers

SSE:

Field	Type	Required	Description
`type`	`"sse"`	Yes	Transport discriminator
`url`	`String`	Yes	SSE endpoint URL
`headers`	`Map<String, String>`	No	HTTP headers

WasmToolConfig

Field	Type	Required	Default	Description
`name`	`String`	Yes	—	Tool name (`[a-z][a-z0-9_-]*`)
`path`	`String`	Yes	—	Path to `.wasm` component file
`capabilities`	`String[]`	No	`[]`	Granted capabilities
`limits`	`WasmLimitsConfig`	No	`null`	Resource limit overrides
`secrets`	`String[]`	No	`[]`	Secret names the tool may query
`workspace_prefixes`	`String[]`	No	`[]`	Readable workspace paths
`endpoint_allowlist`	`String[]`	No	`[]`	Allowed HTTP endpoints
`tool_aliases`	`Map<String, String>`	No	`{}`	Tool name aliases

WasmLimitsConfig

Field	Type	Required	Default	Description
`max_memory_bytes`	`usize`	No	Runtime default	Max memory allocation
`fuel_limit`	`u64`	No	Runtime default	Computation fuel limit
`execution_timeout_secs`	`u64`	No	Runtime default	Execution timeout
`max_log_entries`	`usize`	No	Runtime default	Max log entries
`max_http_requests`	`usize`	No	Runtime default	Max HTTP requests
`max_tool_invocations`	`usize`	No	Runtime default	Max tool invocations
`max_file_read_bytes`	`usize`	No	Runtime default	Max file read size

Valid Capabilities

Logging — Write log entries
WorkspaceRead — Read files from workspace
HttpRequest — Make HTTP requests
ToolInvoke — Invoke other tools
SecretCheck — Check secret existence

Complete Example

{
  "version": 2,
  "/home/user/my-project": {
    "providers": {
      "default": {
        "type": "anthropic",
        "api_key_env": "ANTHROPIC_API_KEY"
      }
    },
    "defaults": {
      "model": "sonnet",
      "commit_interval": 300,
      "max_consecutive_errors": 5,
      "liveness": {
        "enabled": true,
        "idle_nudge_after_secs": 120
      }
    },
    "agents": [
      {
        "name": "backend",
        "prompt": "@prompts/backend.md",
        "model": "sonnet"
      },
      {
        "name": "frontend",
        "prompt": "You are a frontend engineer.",
        "permissions": {
          "allow": ["Bash(npm *)"],
          "deny": ["Bash(rm *)"]
        }
      }
    ],
    "permissions": {
      "allow": ["Read(*)", "Glob(*)"],
      "default_mode": "default"
    },
    "mcpServers": {
      "filesystem": {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
        }
      }
    }
  }
}

Configuration — How config loading and resolution works
Writing Agents — Practical configuration guide