clawmates/README.md

# Clawmates

**Deploy agents at any scale — a single claw, a team, a company, or a whole org — and run a mission across
the organizational *topology* that fits it.**

Clawmates is a multi-agent platform where every unit of work is a **topology**: a graph of role-slots
bound to real AI agents ("claws"). The same model nests recursively — a team is a topology of claws, a
company is a topology of teams, an org is a topology of companies — so you compose and run agentic
systems from one agent up to an entire organization. A safety invariant runs through all of it:
**authority is topology-invariant** — no choice of structure can let an agent exceed its sandbox (spec
§15).

Live at **[clawmates.work](https://clawmates.work)**.

---

## Features

- **The deploy ladder — single → team → company → org.** Pick a scale; each rung instantiates a baseline
  topology and binds it to real, individually-chattable claws. Higher rungs *compose* the rung below:
  a company is staffed with teams, an org with companies.
- **Missions.** The primary user-facing unit: a scoped multi-team workload with team templates, live
  progress, bulk operations, and a canvas view. Missions are hard-required to include a team template
  and can span research + development teams.
- **Recursive execution.** Running a parent runs each child's whole sub-topology, all the way down to
  the leaf claws — on a **durable, crash-resumable** runner (checkpointed per step, with cancellation).
- **INFRA tier via Herdr.** Every fleet node runs a persistent `clawmates-node` daemon (herdr) reachable
  from the platform: mission wizard picks a target runtime, `fleet_herdr` dispatches on launch, and
  a Live Pane surfaces each node's herdr TUI via xterm.js.
- **12 organizational topologies.** Hierarchical, pipeline, swarm, mesh, debate, hub-spoke, star-MoE,
  market, ring, flat, holacratic, blackboard — over five execution patterns.
- **Multi-topology comparison + evolution.** Run one task across many topologies and get a quality/cost
  **Pareto front**; a MAP-Elites search evolves better (kind × team-size) configurations using the
  comparison harness as fitness.
- **Recursive zoom canvas.** One view for every tier: click a node to drill down (org→company→team→claw),
  breadcrumb to zoom back up.
- **§15 safety by construction.** Agents run tool-free in network-isolated sandboxes; every
  sandbox-leaving action is a gated, human-approvable "door" tool. A secret broker holds credentials that
  never reach agent code, and an allow-listed Docker socket caps blast radius.
- **Heterogeneous models.** Bind any node to a different backend; supported providers include Claude
  (default for refine), GLM, Kimi, Groq. Configured per-node in the wizard.
- **Level-Up.** Per-claw and per-team improvement proposals with an inbox + review drawer.
- **Beszel + Tailscale integration.** First-class routes to the fleet's monitoring hub and mesh.
- **Self-hostable.** A single-node Docker Compose deployment runs the whole platform with the same
  network-segmented security model as the Kubernetes path; a separate rolling-deploy path serves
  clawmates.work from gw-04 against the fleet registry.

---

## Architecture

A Rust workspace (the platform) + a Next.js app (the web UI).

### Backend — Rust workspace (`crates/`)

| Crate | Role |
|---|---|
| `cm-domain` | Shared types: ids, roles, workspaces, users |
| `cm-topology` | Topology data model: 12-kind taxonomy, graph, classifier, per-kind builders + heuristics |
| `cm-orchestrator` | Execution engine: async control-flow over a generic `TurnExecutor`; planners, comparison harness, MAP-Elites evolution |
| `cm-runtime` | The §15-safe per-tenant agent runtime |
| `cm-brain` | Shared LLM planning + reasoning primitives used by orchestrator and refine |
| `cm-api` | REST/SSE API + streaming gateway + recursive tier execution + the MCP "door" + missions + fleet_herdr |
| `cm-db` | Postgres persistence (sqlx, offline-checked) |
| `cm-llm` | Provider abstraction over the model backends |
| `cm-secrets` / `clawmates-broker` | The secret broker — credentials never leave it |
| `cm-sandbox` / `cm-safety` | Sandbox provisioning + the §15 approval/gating model |
| `cm-tools` | Tool contract + registry surfaced through the door |
| `cm-testkit` | Shared test utilities (scripted providers, fixture builders) |
| `cm-auth`, `cm-billing`, `cm-files`, `cm-scheduler`, `cm-config`, `cm-telemetry` | Supporting services |

### Binaries (`crates/bins/`)

| Bin | Role |
|---|---|
| `clawmates-server` | The single server binary (API + gateway + runtime + scheduler) |
| `clawmates-broker` | Out-of-process secret broker over a private unix socket |
| `clawmates-node` | The **herdr** daemon: runs on every fleet node, dispatches missions to that node, exposes a TUI streamed into the Live Pane |

### Frontend (`frontend/`)

Next.js 16, React 19, Tailwind v4. Two-tier rail (structure + context), the recursive zoom canvas, and
the deploy wizards. Missions surface (canvas + list + wizard + live pane + team tab + live events),
Herdr sessions UI, Level-Up inbox + review drawer. Talks to the backend through a same-origin `/api`
proxy that swaps the session for a bearer token and streams SSE.

### Data plane

Postgres, with the server self-migrating on boot. Migration series `0001–0057+`; slice-9 cleanup
(`0053`) retired the legacy research/loops path after missions replaced it.

---

## Quickstart

The fastest path is the single-node Docker Compose deployment.

```bash
cd deploy/compose
cp .env.example .env
# Edit .env: set POSTGRES_PASSWORD and CLAWMATES_BOOTSTRAP_OWNER_PASSWORD.

docker compose build      # or load a signed release bundle (deploy/airgapped/install.sh)
docker compose up -d
```

The server self-migrates and, if `CLAWMATES_BOOTSTRAP_OWNER_PASSWORD` is set, provisions the first
Owner + workspace on first boot. Then:

- **App** → http://localhost:3000 (sign in with the bootstrap owner)
- **API health** → http://localhost:8080/healthz

Backends: `openai_compat` by default (point `[llm].base_url` at vLLM/Ollama/llama.cpp); set
`provider = "anthropic"` + `ANTHROPIC_API_KEY` to use Claude. Auth is `local` by default or `clerk` at
runtime. See [`deploy/compose/README.md`](deploy/compose/README.md) for all knobs and the broker
master-key backup step.

**Broker master key.** The broker's master key lives in the `broker_key` named volume and is
generated on first boot. **Back this up** before running the stack for anything real — losing it
un-decrypts every stored secret.

**Local development:**

```bash
# Backend (needs a Postgres; sqlx is offline-checked against .sqlx/)
cargo build
cargo test
cargo clippy --all-targets

# Regenerate the sqlx cache after changing any query:
#   DATABASE_URL=… cargo sqlx prepare --workspace

# Frontend
cd frontend
npm install
npm run dev        # also: npm run lint / npm run typecheck / npm run build
```

Run the reproducible topology benchmark (offline-deterministic; real models with `ANTHROPIC_API_KEY`):

```bash
cargo run -p cm-orchestrator --example topology_bench --features provider
```

---

## Production deployment (clawmates.work on gw-04)

The public site runs a different path than the airgapped compose. Gitea Actions builds and pushes
`broker`, `server`, and `frontend` images to the fleet registry at
`100.94.185.103:5000/clawmates/<svc>:latest`. gw-04 runs a systemd-timer-driven rolling deploy:

- **Deploy script:** [`deploy/gw-04/clawmates-deploy.sh`](deploy/gw-04/clawmates-deploy.sh) — polls the
  registry, drift-checks each service's running image ID against `:latest`, and calls
  `docker compose up -d <svc>` on drift. Portable across `docker compose` v2 and legacy `docker-compose` v1.
- **Timer + unit:** installed alongside the script under `/etc/systemd/system/`.
- **Logs:** `/var/log/clawmates-deploy.log`.
- **Compose file:** references registry-prefixed images directly — no retag bridging.

**gw-04-specific gotchas (bit us on 2026-07-09 and 2026-07-12):**

- `clawmates-runtime` on gw-04 is **not compose-managed** — it's a standalone `docker run` invocation.
  Provider env (`ANTHROPIC_API_KEY`, `ZEROCLAW_providers__*`) must be set on that container.
- The server container runs as **UID 65532** (distroless nonroot). Any bind-mount host path must be
  `chown 65532:65532` before boot or the server can't write.
- Per-team ZeroClaw containers inherit `ZEROCLAW_providers__*` from the server; those envs must live
  on the compose `server` block, not just on shared runtime.

---

## CI budgets

- **Hard limit:** 1500 lines per source file. CI fails.
- **Soft limit:** 1100 lines. CI warns — split before it hurts.
- Enforced by [`ci/check-loc.sh`](ci/check-loc.sh).

Common split pattern: extract sub-components (`MissionLivePane`, `AutoProvisionCard`) into their own
file when the parent creeps past the soft limit.

---

## Roadmap

**Shipped**
- ✅ Pure-Rust topology engine — model → classify → build (all 12 kinds) → execute → compare (Pareto) →
  workflow → LLM-judge → evolve.
- ✅ Topologies UI: catalog browser, builder/visualizer, multi-topology comparison with a Pareto scatter.
- ✅ Durable topology runs — crash-resumable, checkpointed per step, cancellable, with live SSE.
- ✅ **The full deploy ladder** — single → team → company → org, with recursive execution down to the
  leaf claws and a recursive zoom canvas + two-tier navigation.
- ✅ **Missions (slices 1–9)** — multi-team model, hard-required team templates, canvas + wizard + list,
  auto-refresh + Team tab + Live events tab, add/edit/delete toolbar, bulk delete, security-scan +
  benchmark trigger buttons, per-mission repo checkout on launch, LevelUpInbox mounted.
- ✅ **Herdr (phases 0–3)** — `clawmates-node` daemon (systemd/launchd persistence), `fleet_herdr`
  dispatch module + node daemon ops, missions `runtime_kind` + `target_node` schema, wizard runtime
  picker with `on_launch` auto-dispatch, Live Pane (xterm.js → node's herdr TUI), INFRA-tier Herdr
  sessions surface.
- ✅ **Refine on Opus 4.8** — before/after diff view, accept/cancel/restore controls.
- ✅ **Level-Up** — per-claw/per-team improvement proposals, inbox + review drawer.
- ✅ §15 safety: tool-free sandboxes, the gated MCP "door" (with real email/Slack delivery), the secret
  broker, allow-listed Docker socket.
- ✅ Self-host: single-node Docker Compose with full network segmentation.
- ✅ Prod path on gw-04: registry-driven rolling deploy via systemd timer.

**Next**
- Team / company templates as first-class saved catalogs (compose orgs from reusable building blocks).
- Per-leaf nested checkpoint resume (today the recursive runner resumes at parent-node granularity).
- Persona injection into runtime turns (beyond role-driven prompting).
- Richer per-tier dashboards (company coordination, org portfolio/governance metrics).
- Group lifecycle management (delete/edit a deployed team/company/org; deprovision its agents) —
  bulk delete shipped for missions, extending to teams/companies/orgs next.

**Research**
- The accompanying paper, *Large Dynamic Agentic Topologies* (`papers/dynamic-agentic-topologies.md`):
  the topology-invariant authority result, the comparison/Pareto methodology, and benchmark results.

---

## Safety

The network segmentation **is** the security model. Agent sandboxes run with no network at all; only the
browser container has egress. The secret broker is reachable only over a private socket and credentials
never enter agent code. The server reaches Docker through an allow-listed socket proxy that can manage
sandbox containers and nothing else. Every sandbox-leaving action is gated behind a human approval. No
topology — and no switch between topologies — can bypass any of this.