Harness Configuration

Agent Swarm uses a harness abstraction to decouple task execution from the underlying AI provider. Each worker runs one harness — the harness spawns sessions, manages credentials, and normalizes events so the rest of the system doesn't care which provider is underneath.

Supported Providers

How It Works

The HARNESS_PROVIDER environment variable selects which provider adapter is used. The runner creates the adapter at startup:

HARNESS_PROVIDER=claude          →  ClaudeAdapter         →  spawns `claude` CLI process
HARNESS_PROVIDER=codex           →  CodexAdapter          →  spawns `codex` CLI process
HARNESS_PROVIDER=opencode        →  OpencodeAdapter       →  spawns `opencode` CLI process
HARNESS_PROVIDER=pi              →  PiMonoAdapter         →  creates in-process pi-mono session
HARNESS_PROVIDER=devin           →  DevinAdapter          →  POSTs /sessions, polls events
                                                            (session executes in Devin cloud)
HARNESS_PROVIDER=claude-managed  →  ClaudeManagedAdapter  →  opens SSE stream against
                                                            Anthropic's managed sandbox
                                                            (session executes server-side)
HARNESS_PROVIDER=acp             →  ACPAdapter            →  spawns `ACP_TARGET_COMMAND`,
                                                            speaks ndjson ACP over stdio

Both adapters implement the same ProviderAdapter interface, producing normalized ProviderEvent streams (session init, tool calls, cost data, context usage, etc.) that the runner consumes identically.

For local coding harnesses, Agent Swarm now wires in the context-mode MCP server by default for Claude Code, Codex, and opencode. That gives those providers the same ctx_* compressed-search / fetch-and-index tools out of the box. Hook guidance now nudges agents toward ctx_execute / ctx_batch_execute after every 3 qualifying external-MCP calls by default (override with CONTEXT_MODE_EXTERNAL_MCP_NUDGE_EVERY). Set CONTEXT_MODE_DISABLED=true to opt a worker out.

When the runner refreshes an already-cloned repo for a new task, dirty working trees are auto-stashed instead of forcing a skipped pull. Any resulting swarm-autostash refs are appended to the composed prompt so the agent can restore them intentionally with git stash apply <ref> or git stash pop <ref> when that work matters to the current task.

Claude Code (Default)

Claude Code is the default and recommended harness. It spawns the claude CLI as a subprocess with --output-format stream-json for structured event streaming.

Authentication Methods

Claude Code supports two authentication methods, checked in priority order:

OAuth is preferred because it uses your Claude Code subscription (Pro/Max/Team) with its included usage, rather than consuming pay-per-token API credits.

Getting an OAuth Token

# Interactive — opens browser for OAuth flow
claude setup-token

# The output contains a token like: sk-ant-oat01-...
# Copy this value into your .env file

Or use the onboard wizard which runs this automatically:

bunx @desplega.ai/agent-swarm onboard

Environment Variables

* One of CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY is required.

Model Selection

The Claude adapter passes the model string directly to the claude CLI via --model. Common values:

Models can be set per-task via the API or per-agent via the agent profile. The opus shortname resolves to claude-opus-5; fable and mythos resolve to their 5.1 model IDs. These shortnames also propagate through MCP task-creation surfaces (send-task, task-action, and schedules). See the Anthropic models overview for all available model IDs.

If you want provider-agnostic intent instead of a concrete model string, use modelTier on tasks, schedules, or workflow agent-task nodes. The tier values are smol, regular, smart, and ultra; the claiming worker resolves them to concrete models for its own harness/provider, and local env overrides (MODEL_TIER_MAP, MODEL_TIER_<TIER>) can adjust the mapping without changing the task payload.

Reasoning / Effort

Set a per-agent reasoning/effort level with PATCH /api/agents/{id}/runtime (reasoning_effort: off | low | medium | high | xhigh), persisted as the REASONING_EFFORT_OVERRIDE swarm config key. Claude translates this into the CLAUDE_CODE_EFFORT_LEVEL env var — no CLI flag is used (--effort is buggy in -p mode). off on a legacy model that still exposes a numeric thinking budget instead sets MAX_THINKING_TOKENS=0.

Precedence: if an operator's additionalArgs includes --effort, the CLI flag wins over CLAUDE_CODE_EFFORT_LEVEL — the standard "additionalArgs is an escape hatch" behavior, not special-cased for effort. Not every model supports every level (e.g. some Opus variants don't support off); the dashboard's effort selector greys out unsupported levels per selected model, and the API 400s an unsupported (model, level) combo.

Codex

Codex runs through the codex CLI and supports both direct OpenAI API keys and ChatGPT OAuth.

Each task runs inside a throwaway codex-session-runner subprocess. The worker sends the session config over stdin and receives line-delimited events/results over stdout, so @openai/codex-sdk state dies with the task instead of accumulating in the long-lived runner process.

Authentication Methods

Codex checks credentials in this order:

For ChatGPT OAuth setup, see Provider Auth: Codex OAuth.

Environment Variables

Swarm Config Keys (Codex)

The following keys are stored in the swarm config store (via PUT /api/config or the set-config MCP tool) rather than as environment variables:

Model Selection

The default model baked into the worker image is gpt-5.4. You can override it with MODEL_OVERRIDE if needed.

Reasoning / Effort

Set the per-agent reasoning/effort level (off | low | medium | high | xhigh) via PATCH /api/agents/{id}/runtime — Codex translates it into the model_reasoning_effort config field, with off mapping to 'none'. show_raw_agent_reasoning stays pinned false regardless of the effort level: setting high costs reasoning tokens (visible in reasoning_output_tokens cost telemetry) but produces no visible reasoning trace in the dashboard.

*-codex (non-max) models reject xhigh; *-codex-max models accept it. The API 400s an unsupported (model, level) combo before it's persisted.

Codex Specifics

• Cross-keyType failover: when Codex workers have both OPENAI_API_KEY slots and codex_oauth_* slots available, the runner now fails over across key types instead of retrying a known-exhausted pool. A successful task also clears stale rate-limit state for the credential that proved healthy.
• Per-task subprocess isolation: each task gets a fresh codex-session-runner process, which keeps the worker's baseline memory flat and avoids long-lived SDK heap growth on hot workers.
• Small spawn argv: large system prompts are staged to a temp file and passed via --append-system-prompt-file, avoiding Linux MAX_ARG_STRLEN / E2BIG failures on prompt-heavy repos.
• Actionable failure reporting: subprocess startup / parse failures are emitted back to the parent as structured errors, and non-TTY runs no longer leak cursor escape sequences into the JSON pipe.

Opencode

opencode is a terminal-based AI coding agent that ships its own session loop and MCP client. The swarm spawns the opencode CLI as a subprocess and attaches the agent-swarm plugin for heartbeat, cancellation, identity sync, and compaction hooks.

When to Use opencode

• You want access to OpenRouter's full model catalog (100+ models) without writing provider glue.
• You prefer a lightweight, quickly-iterating open-source CLI over the heavier Claude Code toolchain.
• You need cost-effective throughput — the default openrouter/qwen/qwen3-coder-flash model is fast and inexpensive.

Authentication Methods

opencode checks credentials in this priority order:

At least one credential source is required. The Docker entrypoint validates this on startup.

Environment Variables

* At least one credential source is required (OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, or ~/.local/share/opencode/auth.json).

Model Selection

The default model is openrouter/qwen/qwen3-coder-flash. Set MODEL_OVERRIDE to use a different model:

Reasoning / Effort

Set the per-agent reasoning/effort level (off | low | medium | high | xhigh) via PATCH /api/agents/{id}/runtime. opencode has no single reasoning knob — the swarm translates the level into provider-keyed options in the per-task opencode.json: anthropic/* models get thinking.budgetTokens (an internal numeric translation, not a user-facing knob), openrouter/* models get reasoning.effort, and OpenAI-compatible models get reasoningEffort. off omits reasoning keys entirely — opencode has no explicit off switch.

opencode Specifics

• Agent-swarm plugin: the plugin/opencode-plugins/agent-swarm.ts plugin is automatically injected at session creation. It handles heartbeat, task cancellation, identity sync, system-prompt transformation, compaction, and idle hooks — no manual configuration needed.
• Per-task isolation: each session gets its own agent file (.opencode/agents/swarm-<taskId>.md), config file (/tmp/opencode-<taskId>.json), and data directory (/tmp/opencode-data-<taskId>) to prevent cross-task state bleed.
• MCP tool discovery: the swarm MCP endpoint is wired in automatically via the per-task config; installed MCP servers are also discovered and merged in.

pi-mono

pi-mono is an open-source coding agent that runs as a library (no external CLI process). It supports multiple LLM backends through a provider/model system. See the coding agent README for detailed configuration and usage.

Authentication

pi-mono supports several authentication methods depending on which model provider you use:

At least one of these must be available. The Docker entrypoint validates this on startup. When MODEL_OVERRIDE starts with a provider prefix, only the matching key is required; when it's unset, any one of ANTHROPIC_API_KEY / OPENROUTER_API_KEY / OPENAI_API_KEY suffices.

Environment Variables

* At least one credential source is required (API key or ~/.pi/agent/auth.json).

OPENROUTER_BASE_URL is shared across the swarm's OpenRouter consumers. Set it on API and worker processes when a deployment must route harnesses, credential checks, internal summaries, and raw-LLM or validation workflow nodes through the same gateway. Unset or blank values keep the direct https://openrouter.ai/api/v1 default.

Model Selection

pi-mono resolves models using a provider/model-id format. Set the model via MODEL_OVERRIDE in your environment:

The prefix before the first / selects the provider and the matching credential — the rest is passed through as the model ID (so OpenRouter IDs that themselves contain / work fine).

Reasoning / Effort

Set the per-agent reasoning/effort level (off | low | medium | high | xhigh) via PATCH /api/agents/{id}/runtime — pi-mono translates it directly into the thinkingLevel session option, a top-level sibling of model on CreateAgentSessionOptions. pi's native vocabulary already includes off, so no special-casing is needed there.

pi-mono Specifics

• Runtime-scoped credentials: pi 0.81 uses a per-session ModelRuntime. The adapter injects the resolved task credential into that runtime instead of mutating process-wide provider state, and refreshed OAuth credentials are persisted through pi's provider-owned auth store.
• AGENTS.md symlink: pi-mono reads AGENTS.md for project instructions (equivalent to Claude's CLAUDE.md). The adapter automatically creates a symlink AGENTS.md → CLAUDE.md during sessions so your existing project instructions work with both providers.
• Lazy provider import: the worker only imports @earendil-works/pi-coding-agent when HARNESS_PROVIDER=pi, so non-pi workers are no longer exposed to pi-mono's module-level side effects at boot.
• MCP tool discovery: pi-mono discovers swarm MCP tools at session creation via HTTP and registers them as custom tools. This is handled automatically — no .mcp.json needed for the swarm connection (though installed MCP servers are also discovered).
• Skills sync: The worker mirrors skills into ~/.claude/skills/, ~/.pi/agent/skills/, ~/.codex/skills/, ~/.opencode/skills/, and ~/.agents/skills/ so local harnesses share the same skill inventory.
• Per-task hot-reload: between tasks the worker polls a cheap GET /api/agents/:id/skills/signature (hash) endpoint and only re-syncs the filesystem when the installed-skill set actually changes. Newly installed / uninstalled skills appear on the next task without restarting the worker, while unchanged sessions skip the work. Foreign skills (~/.claude/skills/<name>/SKILL.md files not owned by the swarm) are preserved across re-syncs. See src/utils/skills-refresh.ts.

Claude Managed Agents

claude-managed runs sessions in Anthropic's managed cloud sandbox. The worker becomes a thin SSE relay that maps Anthropic's client.beta.sessions.events.stream output to the swarm's ProviderEvent union — no LLM process, no local CLI, no skill filesystem syncing on the worker.

One-Time Setup

bun run src/cli.tsx claude-managed-setup

This bootstrap CLI (run from your laptop, not inside a worker container):

1. Creates an Anthropic-side Environment (sandbox configuration).
2. Uploads each plugin/commands/*.md skill via client.beta.skills.create.
3. Creates an Anthropic-side Agent with those skills attached.
4. Persists the resulting MANAGED_AGENT_ID + MANAGED_ENVIRONMENT_ID to swarm_config (encrypted at rest); deployed workers restore them at boot.

Re-run with --force to recreate the agent + environment from scratch (rare — only needed if Anthropic rotates IDs upstream or you intentionally reset).

Environment Variables

Model Selection

Default: claude-sonnet-5. Override per-worker via MANAGED_AGENT_MODEL, or per-task via the standard task.model field. Cost computation lives in src/providers/claude-managed-models.ts — token rates per Anthropic pricing plus Anthropic's $0.08/session-hour runtime fee.

claude-managed Specifics

• No skill filesystem on the worker. Skills are uploaded to Anthropic via beta.skills.create during setup and referenced by ID on the Agent.
• System prompt rides in the user message with a cache_control: { type: "ephemeral" } breakpoint between the static prefix and the per-task body, so the static prefix is cache-hit across tasks for the same agent.
• Repo provisioning uses resources: [{ type: "github_repository", url, authorization_token, checkout: { type: "branch", name: "main" } }] on sessions.create when the task carries vcsRepo. Anthropic clones into /workspace/<repo-name> server-side before the agent runs.

For full provider design rationale (why we don't agents.create at runtime, the SDK shape deviations, the prompt-cache breakpoint decision), see Adding a Harness Provider §12.

Agent Client Protocol (ACP)

acp drives any agent that speaks the Agent Client Protocol — an open, editor-agnostic JSON-RPC protocol for driving coding agents over stdio. If your agent already has an ACP server mode (or you build one), you can run it as a swarm worker with no adapter code of your own. See the protocol's own Get started → Agents guide for what it takes for an agent to speak ACP.

Scope today is deliberately minimal: one target (custom, driven entirely by env vars below), no named target profiles, no Docker image wiring beyond the generic worker image, no live steering (see the steering table in Adding a Harness Provider — ACP exposes a single in-flight session/prompt and the only interrupt is a full session/cancel).

How it works

The ACPAdapter spawns ACP_TARGET_COMMAND as a subprocess and speaks ndjson ACP over its stdio using @agentclientprotocol/sdk's ClientSideConnection. On session start it calls initialize then newSession, passing the swarm MCP server ({apiUrl}/mcp, over HTTP with the standard Authorization / X-Agent-ID / X-Source-Task-Id headers) plus every other MCP server installed on the agent, translated into ACP's McpServer shape. Session notifications (session/update) are translated into the swarm's normalized ProviderEvent stream the same way every other provider's events are.

Because the target process owns its own model credentials, acp reports ready: true with no required env vars from the swarm's credential-wait gate, and its cost rows settle at costSource: "unpriced" — the swarm has no visibility into what the target agent is billed for a turn.

Environment Variables

ACP_TARGET itself is reserved for future named target profiles; it must be unset or "custom" today — any other value fails session creation with Unsupported ACP target.

Example targets

Any ACP-speaking agent works. A few starting points:

HARNESS_PROVIDER=acp
ACP_TARGET_COMMAND=opencode
ACP_TARGET_ARGS=["acp"]

HARNESS_PROVIDER=acp
ACP_TARGET_COMMAND=npx
ACP_TARGET_ARGS=["-y", "@zed-industries/claude-code-acp"]

HARNESS_PROVIDER=acp
ACP_TARGET_COMMAND=gemini
ACP_TARGET_ARGS=["--experimental-acp"]

HARNESS_PROVIDER=acp
ACP_TARGET_COMMAND=/usr/local/bin/my-acp-agent
ACP_TARGET_ARGS=["--stdio"]

Tool availability

An ACP agent's own tools (file edit, shell, etc.) are whatever the target process implements — the swarm doesn't grant or restrict them; that's between you and the target agent's build. What the swarm adapter does provide is the swarm MCP server (store-progress, send-task, memory-search, and the rest) plus every MCP server already installed on the calling agent, both passed into newSession's mcpServers array. Whether the target agent actually calls them depends on the target honoring ACP's mcpServers field the same way opencode's and Zed's ACP servers do — check your target's docs if tool calls aren't appearing. There's no fallback path today if a target ignores mcpServers: unlike claude/pi/codex, which fail open and keep the harness usable without MCP, an ACP target that doesn't wire the passed servers into its own tool loop simply won't call swarm tools at all.

ACP Specifics

• The target receives the worker's swarm API key. newSession's swarm MCP server entry carries the worker's bearer as an Authorization header (see How it works above) — the same credential every other spawned harness process receives (claude, codex, and the rest all pass their swarm bearer to the spawned CLI/subprocess the same way). ACP_TARGET_COMMAND is operator-configured and runs in the worker container as the worker; point it only at a binary you trust with that credential.
• No swarm-side credential gate. The acp adapter has no readyCheck — the worker reports ready: true immediately. If ACP_TARGET_COMMAND is unset or unresolvable, the failure surfaces at session-spawn time (task fails with ACP target failed during startup: ...), not at boot.
• No live steering. deliverSteering is not implemented; mid-run messages promote to follow-up tasks the same way an unsupported provider always handles them.
• No skill filesystem sync. The generic worker image still seeds ~/.claude/skills, ~/.opencode/skills, etc. at boot, so a target that reads one of those directories natively (like opencode) still sees skills; a fully custom target sees whatever ACP_SYSTEM_PROMPT_PATH writes and nothing more.

For full adapter internals (the SwarmAcpClient/ACPSession classes, MCP server translation, event mapping), see src/providers/acp-adapter.ts and Adding a Harness Provider.

Choosing a Provider

Recommendation: Use Claude Code with OAuth for most setups. Use Codex when you specifically want the OpenAI/Codex toolchain or ChatGPT OAuth-backed workers. Use opencode when you want a lightweight open-source runner with access to the full OpenRouter model catalog at low cost. Consider pi-mono when you need a library-based open-source runner. Choose claude-managed when you want managed sandboxing (faster cold-start, vault-based credential isolation) and don't need a local runtime. Choose acp when you already have (or are building) an ACP-speaking agent and want to run it as a swarm worker without writing a new adapter.

Multi-Credential Pools

Claude Code

Both CLAUDE_CODE_OAUTH_TOKEN and ANTHROPIC_API_KEY support comma-separated values for load balancing across multiple subscriptions:

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

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

Each session randomly selects one credential from the pool. A log line indicates the selected index (never the credential itself). Single values work unchanged.

This is useful when running multiple concurrent workers that would otherwise hit rate limits on a single subscription.

Codex OAuth Pool

Codex workers support a database-backed multi-credential pool stored as codex_oauth_0, codex_oauth_1, ... in the swarm config store. Unlike the Claude comma-separated approach, Codex slots are provisioned via codex-login and persisted centrally so all workers can access them.

Key properties:

• Rate-limit-aware selection: the runner queries /api/keys/available?keyType=CODEX_OAUTH before each task spawn and picks from non-rate-limited slots only. When a task hits a rate limit, the slot is marked unavailable: workspace-credits-exhausted errors use a 2-hour cooldown (tunable via CODEX_CREDITS_EXHAUSTED_COOLDOWN_MS); other unparseable rate-limit errors fall back to ~5 minutes. See Provider Auth: Codex OAuth — Workspace credits exhausted.
• Locked refresh + keep-warm: task-time revalidation and POST /api/oauth/keep-warm/codex share the same refresh-lock path, so rarely-used slots can still refresh on a roughly weekly cadence without racing the runner.
• Token-refresh write-back: refreshed OAuth tokens are written back to the same codex_oauth_<slot> key the task started with. Other slots are never touched.
• Fail-fast auth errors: a rejected slot refresh now stops the task with the upstream auth failure instead of silently falling back to a stale pool auth file.
• Backwards compatible: single-credential deploys work unchanged. The boot entrypoint seeds codex_oauth_0 from the legacy codex_oauth key on first run.
• Global scope: no per-agent or per-task affinity — any worker can pick any slot.

Provision additional slots:

# Run once per ChatGPT account; each call appends a new slot
bun run src/cli.tsx codex-login --api-url http://localhost:3013 --api-key YOUR_API_KEY

For the full provisioning guide, rate-limit detection details, and verification commands, see Provider Auth: Codex OAuth.

Docker Configuration Examples

Claude Code Worker

# .env.docker
HARNESS_PROVIDER=claude              # Optional — claude is the default
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat-...
API_KEY=your-api-key
MCP_BASE_URL=http://host.docker.internal:3013
AGENT_ID=your-worker-uuid
GITHUB_TOKEN=ghp_...

opencode Worker

# .env.docker
HARNESS_PROVIDER=opencode
OPENROUTER_API_KEY=sk-or-...         # Or ANTHROPIC_API_KEY / OPENAI_API_KEY
MODEL_OVERRIDE=openrouter/qwen/qwen3-coder-flash  # Default; see https://openrouter.ai/models
API_KEY=your-api-key
MCP_BASE_URL=http://host.docker.internal:3013
AGENT_ID=your-worker-uuid
GITHUB_TOKEN=ghp_...

pi-mono Worker

# .env.docker
HARNESS_PROVIDER=pi
OPENROUTER_API_KEY=sk-or-...         # Or ANTHROPIC_API_KEY
MODEL_OVERRIDE=openrouter/moonshotai/kimi-k2.5  # See https://openrouter.ai/models
API_KEY=your-api-key
MCP_BASE_URL=http://host.docker.internal:3013
AGENT_ID=your-worker-uuid
GITHUB_TOKEN=ghp_...
# Do NOT include CLAUDE_CODE_OAUTH_TOKEN — it will override the pi provider

Mixed Swarm

You can run different providers for different agents in the same swarm. For example, a Claude Code lead with pi-mono workers:

# .env.docker-lead
HARNESS_PROVIDER=claude
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat-...
AGENT_ROLE=lead

# .env.docker-worker
HARNESS_PROVIDER=pi
OPENROUTER_API_KEY=sk-or-...

Troubleshooting

Worker is parked in waiting_for_credentials

The container booted but no harness credentials are present. This is expected — the worker waits at runtime instead of crash-looping. Set the missing key via PUT /api/config (scope=agent or scope=global) and the worker picks it up within ≤30s. See Worker Credential Recovery for the full lifecycle, the credentialMissing payload, and the configuration knobs (BOOT_INITIAL_BACKOFF_MS, BOOT_MAX_BACKOFF_MS, BOOT_MAX_WAIT_SECONDS).

Claude Code: "Claude CLI not found"

The claude binary must be in $PATH inside the Docker container. The worker Docker image includes it by default. If using a custom image, set CLAUDE_BINARY=/path/to/claude.

Wrong provider selected

Check the startup logs — the entrypoint prints Harness Provider: <value>. If it says claude when you expected pi, ensure HARNESS_PROVIDER=pi is in your env file and not being overridden.

ACP: "ACP target failed during startup"

ACP_TARGET_COMMAND didn't resolve, or the target process exited/errored during initialize/newSession. Confirm the binary is on $PATH inside the worker image (or use an absolute path), and that any args in ACP_TARGET_ARGS are valid for that target — try running the exact ACP_TARGET_COMMAND + ACP_TARGET_ARGS combination by hand first.

ACP: agent never calls swarm MCP tools

The target agent has to honor ACP's newSession.mcpServers field itself; the swarm adapter passes the swarm MCP server and every other installed MCP server into that field, but whether the target connects to them is up to its own implementation. There's no swarm-side fallback here — check the target agent's ACP docs for its MCP support status.

Related

• Model Gateways — Route supported harnesses through OpenRouter or an OpenRouter-compatible proxy, with current Ramp Router gaps
• Environment Variables — Full reference for all configuration variables including auth credentials
• Deployment Guide — Deploy agents to production with Docker Compose
• Getting Started — Initial setup including credential configuration
• Architecture Overview — How harnesses fit into the overall system
• Harness Providers — Engineering reference for the ProviderAdapter contract, including the reasoning/effort capability lookup and per-harness translation