clawmates/README.md

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.

---

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.

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 for all knobs and the broker master-key backup step.

Local development:

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

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.