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=pi      →  PiMonoAdapter  →  creates in-process pi-mono session

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.

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. See the Anthropic models overview for all available model IDs.

Codex

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

Authentication Methods

Codex checks credentials in this order:

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

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.

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.

Environment Variables

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

Model Selection

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

pi-mono Specifics

• 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.
• 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 Docker entrypoint syncs skills to both ~/.claude/skills/ and ~/.pi/agent/skills/ so skills work regardless of 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. Consider pi-mono when you need access to non-Claude models through OpenRouter or want a library-based open-source runner.

Multi-Credential Pools

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.

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_...

pi-mono Worker

# .env.docker
HARNESS_PROVIDER=pi
OPENROUTER_API_KEY=sk-or-...         # Or ANTHROPIC_API_KEY
MODEL_OVERRIDE=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

Claude Code: "No Claude credentials found"

The adapter checks for CLAUDE_CODE_OAUTH_TOKEN first, then ANTHROPIC_API_KEY. Ensure at least one is set in your .env.docker file.

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.

pi-mono: credential validation error

The Docker entrypoint requires at least one pi-mono credential (ANTHROPIC_API_KEY, OPENROUTER_API_KEY, or ~/.pi/agent/auth.json). Set the appropriate key in your .env.docker file.

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.

Related

• 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