Configuration

The Configuration page (Settings → Configuration, at /settings/configuration in the dashboard) surfaces the environment variables that shape how your swarm behaves — steering, memory retrieval, heartbeat and crash recovery, harness selection, integration toggles, security, workflow limits, and branding — as editable settings, so you can tune a running deployment without shelling into the host to edit .env files.

How values resolve

Every setting on this page corresponds to an environment variable the API server reads. Saving a value from the dashboard stores it as a global swarm config entry (the same swarm_config store used by the get-config / set-config MCP tools), and the server applies it via an automatic config reload shortly after the save.

Precedence rules:

• At boot, real environment variables win: a variable set in the server's environment takes precedence over a stored value until the next reload.
• After a save or reload, stored values win: the server re-injects global config over the process environment.
• Settings marked with a Restart required badge are only read at server startup — saving them stores the value, but it takes effect on the next restart.

Each row shows a source chip when the underlying environment variable is set on the server, so you can tell whether the effective value comes from the environment, the stored config, or both.

Groups

Claude transport default

The Harness & tools group includes CLAUDE_TRANSPORT, with cli as the default and sdk as the optional value. Agents can inherit this default or assign a transport beneath the harness selector on their details page. An agent override takes precedence over the global default. A repository override takes precedence when the session supplies its repository. Transport changes apply to future sessions and do not require a worker restart. The worker resolves this key for each session instead of retaining a scoped value in its deployment environment. SDK selection is incompatible with an effective Claude Bridge or legacy bridge binary.

Harness provider and model selection are deliberately absent from this page — they are configured per agent. A global value would silently become the default for every agent in the swarm, so those knobs live on each agent's own configuration instead. OPENROUTER_BASE_URL is a deployment-wide routing endpoint rather than a model choice, which is why it does belong here.

Settings with deeper behavior link out to the relevant guide (for example the task steering and harness providers guides) directly from the row.

Editing

Controls match the value type:

• Toggles (feature flags) persist immediately when switched.
• Selects (enumerated values such as SLACK_THREAD_STEERING_MODE) persist on change.
• Text and number inputs show a Save button once the value differs from what is stored.

Every row shows its default, and rows with a stored value offer a Reset action that deletes the stored entry and returns the setting to its default (or to the environment value, if one is set). The Reload config button in the header forces an immediate config reload — useful after changing environment variables outside the dashboard.

Task tool preloading (proposal)

TASK_TOOL_PRELOAD_ENABLED defaults to false. With it enabled, each new agent MCP session reads TASK_TOOL_MANIFESTS, selects tools using the authenticated agent's current task, and marks their MCP metadata with anthropic/alwaysLoad: true. Claude Code supports this annotation; no reduction in tool searches is claimed for other harnesses. Existing sessions retain their original selection.

Both settings can be stored in global or agent-scoped configuration. Agent-scoped values override global values; resolved configuration takes precedence over environment defaults. The dashboard edits global values. For a small pilot, use agent-scoped configuration instead.

{
  "taskTypes": {
    "review": ["get-tasks", "script-run", "get-repos"]
  },
  "schedules": {
    "12345678-1234-4234-8234-123456789abc": ["script-run", "kv-get"]
  }
}

Keys match exactly. A schedule entry replaces the task-type selection, including an empty array to opt out. Each entry accepts at most 16 registered swarm tool names. Unsupported shapes or unknown names are rejected on config writes. Invalid environment values fall back to ordinary discovery with a server warning. Missing task context, an unowned task, or no match adds no tools. Slack tools preload only when the task has Slack context. Capability filters, scripts-only mode, and tool-call permissions still apply; preloading never grants access or removes searchable tools.

Each selected tool adds its description and input schema to the initial model context. A long schema can cost more than the search it replaces. Compare input/cache tokens, cost, and tool-search steps on the same recurring targets before enabling this broadly. Turn the flag off to restore ordinary discovery for new sessions. This proposal does not enable either setting.

Seeded automation auto-enable

SEED_AUTOMATIONS_ENABLED defaults to true and controls whether a freshly seeded workflow or schedule that needs no integration and no required param/placeholder — and whose own template doesn't recommend staying off — arrives already enabled at boot, instead of disabled-but-inventoried. An item that needs a credential or a param this install doesn't have is unaffected either way.

This includes daily-swarm-update-check, a zero-config schedule that calls the public GitHub releases API on a daily cron and posts to the configured admin channel when a newer desplega-ai/agent-swarm release is available — the only outbound network call and notification this switch turns on by default. Turn the switch off, or disable that schedule individually from its details page, to stop it.

The API server reads this value at boot when seeding runs (restartRequired): flip it, then restart to change what a future seed pass creates. It does not retroactively enable or disable automations already created on this install.

Access control

Reading configuration requires dashboard access (API key). Writes go through the config API's RBAC gate (config.write.any): operator and user tokens can save, and agent principals are restricted to lead agents.

Adding a new setting

If you are contributing a new operator-facing environment variable to Agent Swarm, register it in the configuration catalog at apps/ui/src/lib/configuration-catalog.ts (group, value kind, default, description, and docs link) so it appears on this page. Reserved bootstrap keys (API_KEY, SECRETS_ENCRYPTION_KEY) and credentials must never be added to the catalog.

CORS_ALLOW_ANY_ORIGIN is deployment-only and is not available in Configuration. Set it in the API deployment environment and restart the API for arbitrary-origin bearer-token clients using credentials: "omit". It never grants credentialed CORS to an unlisted origin: cookie-authenticated responses, including page JSON and /@swarm/api/*, still require CORS_ALLOWED_ORIGINS (or the built-in defaults). HTTP, MCP, and database config writes reject this reserved key; legacy stored rows are ignored during startup and reload and can be deleted. Prefer configuring trusted origins with CORS_ALLOWED_ORIGINS.