Omar SobhandClaude Opus 4.8
540c74f42e
Re-skins the whole app to the dark design comps and wires the new surfaces to
the backend (the /api proxy + auth + schemas are unchanged).
Design system:
- globals.css: remapped @theme tokens to the comp palette (#08080a base, coral
#ff6f61, status cyan/green/amber/purple/teal); token names preserved
- MeshMark: triangle + 3-node brand glyph; cm-flow/cm-blink/cm-halo keyframes
- marketing flipped light → dark
Backend (migration 0012):
- agents.model_binding (persisted on team deploy) + GET /api/claws/{id}/runtime-config
- routine_runs table + scheduler journaling + GET /api/routines/runs
- GET /api/claws/{id}/compartments (anatomy aggregate)
- GET /api/structure/stats (workspace counts)
Frontend:
- Landing: full dark marketing page (hero constellation, deploy ladder,
12-topology taxonomy, recursive execution, compare/Pareto, safety, self-host)
- Auth: dark split-panel AuthShell + comp LoginForm + Clerk SignIn themed dark
- Dashboard shell: TopBar (breadcrumb + live stats + deploy + user) + StatusBar
(runner/sandbox/doors); rail slimmed to 60px + 252px context column
- ConstellationCanvas (radial recursive) replaces the graph view in StructureCanvas;
selecting a claw opens ComputerPanel (apps/now-running/dock); RoutinesPanel
- Claw anatomy view (/claws/[id]/anatomy) from compartments + runtime-config
Co-Authored-By: Claude Opus 4.8 <[email protected]>
149 lines
7.0 KiB
Markdown
149 lines
7.0 KiB
Markdown
# 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.
|