# Clawmates

**Deploy agents at any scale — a single claw, a team, a company, or a whole org — and run a task 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.
- **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).
- **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 (Claude, Gemini, Groq, GLM, Kimi).
- **Self-hostable.** A single-node Docker Compose deployment runs the whole platform with the same
  network-segmented security model as the Kubernetes path.

---

## Architecture

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

**Backend — Rust workspace (`crates/`):**

| Crate | Role |
|---|---|
| `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, evolution |
| `cm-runtime` | The §15-safe per-tenant agent runtime |
| `cm-api` | REST/SSE API + streaming gateway + recursive tier execution + the MCP "door" |
| `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-auth`, `cm-billing`, `cm-files`, `cm-scheduler`, `cm-config`, `cm-domain`, `cm-telemetry` | Supporting services |
| `clawmates-server` | The single server binary (API + gateway + runtime + scheduler) |

**Frontend (`frontend/`):** Next.js 16, React 19, Tailwind v4 — a two-tier rail (structure + context),
the recursive zoom canvas, and the deploy wizards. 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.

---

## 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

By default it runs a local model endpoint (`openai_compat`, 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.

**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
```

---

## 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.
- ✅ §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.

**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).

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