# SwarmWright

> Self-hosted multi-agent AI orchestration platform. Topology-enforced agent graphs, human-in-the-loop approvals, and full audit trails. One Docker command to get started. Free and open source (CC BY-NC 4.0).

SwarmWright lets you build and run structured teams of AI agents. Every connection between agents is declared upfront and enforced at runtime — agents cannot call anything not explicitly authorized. All decisions are logged with a plain-language reason. Humans can be wired into workflows as blocking approval gates or non-blocking notification nodes.

## Key facts

- Runs as a single Docker container — no external infrastructure required
- Supports Anthropic (Claude), OpenAI (GPT-4), and Deepseek models
- Individual agents can specify their own model and provider in their constitution frontmatter
- All data stored locally — credentials encrypted, never sent to third parties
- Visual drag-and-drop canvas where the diagram is the configuration (no separate spec file)
- Python skills run in a sandboxed subprocess — misbehaving code cannot crash the host
- Full run history with step-by-step traces and topology violation detection
- Open source: https://github.com/ralphbarendse/swarmwright
- Managed hosting available at https://console.swarmwright.com — a dedicated isolated instance with its own subdomain and per-instance encryption key (Hobby $4.99/mo, Pro $12.99/mo — 50% off, Enterprise custom; all plans multi-user, bring your own API key)

## Core concepts

- **Swarm**: a coherent set of agents handling one class of work, with a declared topology
- **Agent**: an LLM-powered component with a plain-language constitution and a layer role
- **Layer**: one of four roles — Policy (strategy), Orchestrator (coordination), Executioner (task execution), Perceptionist (read-only data grounding)
- **Topology**: the declared graph in `hierarchy.json`, enforced at runtime with no exceptions
- **Constitution**: a Markdown file defining an agent's identity, values, role, and knowledge references
- **Skill**: a sandboxed Python script callable by Executioner agents
- **Caller**: a blocking human-in-the-loop node — pauses the run until a human approves or rejects
- **Informer**: a non-blocking notification node — sends a message and continues immediately
- **Workspace**: a department-level container for swarms and shared resources
- **Trigger**: a deterministic script (heartbeat, webhook listener, manual invocation, or file watcher) that produces events entering a swarm

## Quick start

```
docker run -d \
  --network=host \
  --name swarmwright \
  -v ./data:/data \
  -e LLM_PROVIDER=anthropic \
  -e LLM_MODEL=claude-opus-4-7 \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  ralphbarendse/swarmwright:latest
```

GUI available at `http://localhost:5001`. No broker, no cluster, no build step.

## Supported LLM providers

| Provider | Env var | Default model |
|---|---|---|
| anthropic | ANTHROPIC_API_KEY | claude-opus-4-6 |
| openai | OPENAI_API_KEY | gpt-4o |
| deepseek | DEEPSEEK_API_KEY | deepseek-chat |

Switch provider via `LLM_PROVIDER` env var or the Settings UI. Individual agents can override with `provider:` and `model:` in their constitution frontmatter.

## Agent constitution format

```markdown
---
name: Finance Orchestrator
layer: orchestrator
model: claude-opus-4-6
provider: anthropic
knowledge:
  - approval-thresholds
  - workspace/finance-procedures
---

You coordinate invoice intake for the Finance workspace...
```

## Resource scopes

Knowledge documents and skills exist at one of four scopes, resolved most-local-first:
`swarm → workspace → company → built-in`

## API

Base path: `POST /api/v1`. Key endpoints:
- `POST /swarms/<id>/events` — fire an event into a swarm
- `GET /runs/<id>` — get a run with full step trace
- `POST /inbox/<id>/decide` — approve or reject a human-in-the-loop request
- `POST /settings/llm/test` — test LLM connectivity

## Links

- Homepage: https://www.swarmwright.com/
- Documentation: https://www.swarmwright.com/docs.html
- Pricing: https://www.swarmwright.com/#pricing
- Managed hosting (cloud console): https://console.swarmwright.com
- GitHub: https://github.com/ralphbarendse/swarmwright
- Docker Hub: https://hub.docker.com/r/ralphbarendse/swarmwright