Infrastructure-layer governance for AI agent containers.
Documentation | Quickstart | Manifesto
Swarm is for agents that work for you. Clawdapus is for bots that work as you.
Every agent framework answers the same question: how do I make agents collaborate? Swarm, CrewAI, LangGraph — all application-layer orchestration, all built on a shared assumption: the agent is a trusted process.
That assumption holds for autonomous assistants. It breaks the moment you deploy bots that operate publicly — posting to feeds, replying on Discord, executing trades, and burning provider tokens — as a persistent presence with a persistent identity.
Clawdapus treats the agent as an untrusted workload. It is the layer below the framework, where deployment meets governance, identity projection, and strict cost containment.
You need: Docker Desktop, an OpenRouter API key, and a Discord bot token + guild ID (see Discord setup guide).
# Install
curl -sSL https://raw.githubusercontent.com/mostlydev/clawdapus/master/install.sh | sh
# Clone the quickstart example
git clone https://github.com/mostlydev/clawdapus.git
cd clawdapus/examples/quickstart
# Configure
cp .env.example .env
# Edit .env — add OPENROUTER_API_KEY, DISCORD_BOT_TOKEN, DISCORD_BOT_ID, DISCORD_GUILD_ID
# Build and launch
source .env
claw build -t quickstart-assistant:latest ./agents/assistant
claw up -f claw-pod.yml -d
# Verify
claw ps -f claw-pod.yml # assistant + cllama both running
claw health -f claw-pod.yml # both healthy
# Run any docker compose command against the pod
claw compose exec assistant bash
claw compose restart cllama-passthrough
claw compose topThe cllama governance proxy dashboard runs on port 8181 — every LLM call in real time: which agent, which model, token counts, cost.
The Clawdapus Dash fleet dashboard runs on port 8082 — live service health, topology wiring, and per-service drill-down.
On the first run, claw build auto-builds the local openclaw:latest base image if it is missing.
Message @quickstart-bot in your Discord server. The bot responds through the proxy — it has no direct API access. The dashboard updates live.
claw up resolves ${...} placeholders inside x-claw metadata from your shell environment and the pod-local .env file before it generates runtime config. You do not need to duplicate handle IDs, guild IDs, or channel IDs into service environment: just to make driver config generation work.
Supported x-claw placeholder forms match shell-style parameter expansion:
${VAR}required${VAR:-default}default when unset or empty${VAR-default}default when unset${VAR:?message}fail when unset or empty${VAR?message}fail when unset${VAR:+value}substitutevaluewhen set and non-empty${VAR+value}substitutevaluewhen set
Built-in x-claw variables:
REPO_ROOTdefaults to the pod directory passed toclaw up
This placeholder expansion is specific to x-claw metadata. Standard Compose fields still use normal Docker Compose .env interpolation rules.
For multi-agent pods, declare shared chat topology once under x-claw.handles-defaults and keep each service's x-claw.handles block focused on service-specific identity such as bot ID and username.
See examples/quickstart/ for the full walkthrough, Telegram/Slack alternatives, and migration from existing OpenClaw.
Or scaffold from scratch:
claw init my-pod
cd my-pod
cp .env.example .env
source .env
claw build -t my-pod-assistant:latest ./agents/assistant
claw up -d
# add another agent later
claw agent add researcherclaw agent add preserves the project's existing layout by default:
- Canonical project: adds
agents/<name>/Clawfile+agents/<name>/AGENTS.md - Flat project: adds
Clawfile.<name>+AGENTS-<name>.md
Use --layout canonical or --layout flat to override auto-detection.
curl -sSL https://raw.githubusercontent.com/mostlydev/clawdapus/master/install.sh | sh
claw doctorOr build from source:
go build -o bin/claw ./cmd/clawClawdapus moves fast — update frequently.
claw updateclaw checks for updates once an hour and prints a notice when a newer release is available.
Give your coding agent full operational knowledge of Clawdapus — the claw CLI, Clawfile syntax, claw-pod.yml structure, cllama proxy wiring, driver semantics, and troubleshooting patterns.
SKILL_URL="https://raw.githubusercontent.com/mostlydev/clawdapus/master/skills/clawdapus/SKILL.md"
# Claude Code
mkdir -p ~/.claude/skills/clawdapus
curl -sSL "$SKILL_URL" -o ~/.claude/skills/clawdapus/SKILL.md
# Codex CLI
curl -sSL "$SKILL_URL" >> ~/.codex/AGENTS.md
# Gemini CLI
curl -sSL "$SKILL_URL" >> ~/.gemini/GEMINI.md
# OpenCode
curl -sSL "$SKILL_URL" >> AGENTS.md
# Cursor / Windsurf / other .cursorrules-based agents
curl -sSL "$SKILL_URL" >> .cursorrulesThe Image (Clawfile) — an extended Dockerfile.
FROM openclaw:latest
CLAW_TYPE openclaw
AGENT AGENTS.md # behavioral contract — bind-mounted read-only
MODEL primary openrouter/anthropic/claude-sonnet-4
MODEL fallback anthropic/claude-haiku-3-5
CLLAMA passthrough # governance proxy — credential starvation + cost tracking
HANDLE discord # platform identity — mention patterns, peer discovery
INVOKE 15 8 * * 1-5 pre-market # scheduled invocation — cron, managed by operator
SURFACE service://trading-api # declared capabilities — auto-discovered, skill-mapped
SURFACE volume://shared-research read-write
SKILL policy/risk-limits.md # operator policy — mounted read-only into runnerThe Deployment (claw-pod.yml) — an extended docker-compose.
x-claw:
pod: trading-desk
master: octopus
cllama-defaults:
proxy: [passthrough]
env:
OPENROUTER_API_KEY: "${OPENROUTER_API_KEY}"
ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}"
surfaces-defaults:
- "service://trading-api"
- "volume://shared-research read-write"
feeds-defaults: [market-context] # resolved from trading-api's claw.describe
services:
tiverton:
image: trading-desk-tiverton:latest
build:
context: ./agents/tiverton
x-claw:
agent: ./agents/tiverton/AGENTS.md
handles:
discord:
id: "${TIVERTON_DISCORD_ID}"
username: "tiverton"
invoke:
- schedule: "15 8 * * 1-5"
name: "Pre-market synthesis"
message: "Run pre-market synthesis and post the floor briefing."
to: trading-floorServices inherit cllama-defaults, surfaces-defaults, and feeds-defaults from the pod. Override any field to replace; use ... spread to extend:
x-claw:
skills:
- ... # inherit pod defaults
- ./policy/escalation.md # add coordinator-only skillclaw build transpiles the Clawfile to a standard Dockerfile. claw up parses the pod YAML, runs driver enforcement, generates per-agent configs, wires the cllama proxy, and calls docker compose. The output is standard OCI images and a standard compose file. Eject from Clawdapus anytime — you still have working Docker artifacts.
Clawdapus extends two formats you already know:
| Clawdapus | Docker equivalent | Purpose |
|---|---|---|
claw init |
docker init + project templating |
Scaffold canonical-by-default project layout |
claw agent add |
(none) | Add agents while preserving existing layout (`--layout auto |
Clawfile |
Dockerfile |
Build an immutable agent image |
claw-pod.yml |
docker-compose.yml |
Run a governed agent fleet |
claw build |
docker build |
Transpile + build OCI image (--context for separate build context) |
claw up |
docker compose up |
Enforce + deploy |
Any valid Dockerfile is a valid Clawfile. Any valid docker-compose.yml is a valid claw-pod.yml. Extended directives live in namespaces Docker already ignores. Eject from Clawdapus anytime — you still have a working OCI image and a working compose file.
The Clawfile extends the Dockerfile with directives that the claw build preprocessor translates into standard Dockerfile primitives (LABEL, ENV, RUN). The output is a plain OCI image.
| Directive | Purpose |
|---|---|
CLAW_TYPE |
Selects the runtime driver (openclaw, hermes, nanobot, picoclaw, nanoclaw, microclaw, nullclaw) |
AGENT |
Names the behavioral contract file |
PERSONA |
Imports a persona workspace — local path or OCI artifact ref |
MODEL |
Binds named model slots to providers |
CLLAMA |
Declares governance proxy type(s) |
HANDLE |
Declares platform identity (discord, telegram, slack, and others per driver) |
INVOKE |
Scheduled invocations via cron |
SURFACE |
Declared in pod YAML — volumes, services, channels |
SKILL |
Operator policy files mounted read-only |
INCLUDE |
Pod-level contract composition — enforce, guide, or reference mode |
CONFIGURE |
Runner-specific config mutations at init |
TRACK |
Wraps package managers to log mutations |
PRIVILEGE |
Drops container privileges |
Pick a driver based on what you need. All drivers support MODEL, AGENT, CLLAMA, and CONFIGURE.
openclaw |
hermes |
nanoclaw |
nanobot |
picoclaw |
nullclaw |
microclaw |
|
|---|---|---|---|---|---|---|---|
| Runtime | OpenClaw | Hermes | Claude Agent SDK | Nanobot | PicoClaw | NullClaw | MicroClaw |
claw init scaffold |
✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| HANDLE: Discord | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ |
| HANDLE: Telegram | — | ✅ | — | ✅ | ✅ | ✅ | ✅ |
| HANDLE: Slack | — | ✅ | — | ✅ | ✅ | ✅ | ✅ |
| HANDLE: long-tail ¹ | — | — | — | — | ✅ | — | — |
| INVOKE (cron) | ✅ | ✅ | — | ✅ | ✅ | ✅ | — |
| Structured health | ✅ | ✅ | — | — | ✅ | ✅ | — |
| Read-only rootfs | ✅ | ✅ | — | ✅ | ✅ | ✅ | — |
| Non-root container | — | — | — | — | ✅ | — | — |
¹ PicoClaw long-tail: WhatsApp, Feishu, LINE, QQ, DingTalk, OneBot, WeCom, WeCom App, Pico, MaixCam.
claw init scaffolds generic (alpine:3.20, no driver enforcement) for custom runtimes.
The OpenClaw driver now maps the supported channel://discord routing controls directly into generated config and rejects the unsupported ones early.
channel://discord map-form setting |
openclaw |
|---|---|
DM policy (pairing, allowlist, open, disabled) |
✅ |
DM allowFrom |
✅ |
Guild requireMention |
✅ |
Guild users[] allowlist |
✅ |
Surface allow_from_handles: true → expands into each guild users[] |
✅ |
Surface allow_from_services: [svc...] → derives Discord IDs from service bot tokens and expands each guild users[] |
✅ |
Guild policy |
— ² |
² The current OpenClaw runtime rejects guild-level policy; Clawdapus now fails during config generation instead of writing a config the container will reject at boot.
Use these when you want high-level HANDLE defaults, but need runtime-specific policy details.
# Base identity on a platform:
HANDLE discord
# "Can talk on" -> pin to one guild/server
CONFIGURE nullclaw config set channels.discord.accounts.main.guild_id "123456789012345678"
# "Can talk to" -> require mention in group chats
CONFIGURE nullclaw config set channels.discord.accounts.main.require_mention true
# Telegram allowlist for DMs
CONFIGURE nullclaw config set channels.telegram.accounts.main.allow_from ["111111111","222222222"]
# Slack transport mode selection
CONFIGURE nullclaw config set channels.slack.accounts.main.mode "socket"Notes:
CONFIGUREis driver-side DSL here (nullclaw config set <path> <value>), applied to generatedconfig.json.- Values are parsed as JSON when possible: booleans/numbers/arrays/objects should be unquoted; strings should be quoted.
CONFIGUREruns after defaults, so it overrides whatHANDLEgenerated.
block-beta
columns 1
contract["Behavioral Contract\nread-only bind mount\nAGENTS.md — purpose, on the host\nSurvives full container compromise"]
runner["Runner\nOpenClaw · NanoClaw · Claude Code · custom"]
persona["Persona\nMemory · history · style · knowledge"]
proxy["cllama — governance proxy\nIntercepts prompts outbound + responses inbound\nRunner never knows it's there"]
style contract fill:#1a1a2e,stroke:#22d3ee,color:#eee
style runner fill:#1a1a2e,stroke:#f0a500,color:#eee
style persona fill:#1a1a2e,stroke:#a78bfa,color:#eee
style proxy fill:#1a1a2e,stroke:#34d399,color:#eee
The contract lives on the host. Even a root-compromised runner cannot rewrite its own mission. Swap runners without touching identity. Add or remove the governance proxy without rebuilding anything.
When a reasoning model tries to govern itself, the guardrails are part of the same cognitive process they're trying to constrain. cllama is a separate process sitting between the runner and the LLM provider. The runner thinks it's talking directly to the model. It never sees the proxy.
- Credential starvation: The proxy holds the real API keys. Agents get unique bearer tokens. No credentials, no bypass.
- Identity resolution: Single proxy serves an entire pod. Bearer tokens resolve which agent is calling.
- Cost accounting: Extracts token usage from every response, multiplies by pricing table, tracks per agent/provider/model.
- Audit logging: Structured JSON on stdout — timestamp, agent, model, latency, tokens, cost, intervention reason.
- Operator dashboard: Real-time web UI at host port 8181 by default (container
:8081) — agent activity, provider status, cost breakdown.
The reference implementation is cllama — a zero-dependency Go binary that implements the transport layer (identity, routing, cost tracking). Future proxy types (cllama-policy) will add bidirectional interception: evaluating outbound prompts and amending inbound responses against the agent's behavioral contract.
See the cllama specification for the full standard.
# Available in every pod service automatically:
CLAW_HANDLE_CRYPTO_CRUSHER_DISCORD_ID=123456789
CLAW_HANDLE_CRYPTO_CRUSHER_DISCORD_GUILDS=111222333HANDLE discord in a Clawfile declares the agent's platform identity. Clawdapus broadcasts every agent's handles as env vars into every service in the pod — including non-claw services. A trading API that needs to mention a bot in a webhook message knows its Discord ID without hardcoding anything.
The driver also wires each agent's openclaw config automatically: allowBots: true (enables bot-to-bot messaging), mentionPatterns derived from the handle username and ID (so agents can route incoming messages correctly), and a guild users[] allowlist that includes every peer bot in the pod.
When many services share the same Discord guild/channel topology, put that shared topology in pod-level x-claw.handles-defaults and let per-service handles.discord override only the identity fields that differ.
claw up is a compiler. It reads the pod file, inspects images, and emits deterministic runtime artifacts. These principles govern the compilation pipeline:
-
Compile-time, not runtime. All wiring — feeds, skills, identity, surfaces — is resolved during
claw up. No runtime self-registration. The generated compose file is the single source of truth for what's deployed. -
Provider-owns, consumer-subscribes. Services declare what they offer (feeds, endpoints, auth). Agents subscribe by name. The consumer should never need to know a service's URL path or TTL — that's the provider's concern.
-
Pod-level defaults, service-level overrides. Anything shared across most services — proxy config, surfaces, feeds, skills — is declared once at pod level. Services inherit by default and override or extend as needed.
-
One canonical descriptor. A service's capabilities, feeds, and endpoints are declared once (via
claw.describein the image) and projected into whatever artifacts need them — CLAWDAPUS.md, feed manifests, effective agent contracts. -
Services self-describe. Images can carry a structured descriptor (
LABEL claw.describe=...) that advertises feeds provided, auth requirements, and a skill file.claw upextracts and compiles these into the pod. Framework-specific adapters (e.g., RailsTrail for Rails apps) can generate descriptors from code introspection.
Every Claw receives a generated CLAWDAPUS.md — the single context document listing surfaces, mount paths, peer handles, feeds, and available skills. Service descriptions from claw.describe labels or claw.skill.emit are inlined directly into CLAWDAPUS.md surface sections, so workflow-critical API docs are always in prompt context without extra pod YAML. Add a service, the skill map updates. No code changes.
$ claw skillmap crypto-crusher-0
FROM market-scanner (service://market-scanner):
get_price Current and historical token price data
get_whale_activity Large wallet movements in last N hours
[discovered via OpenAPI → skills/surface-market-scanner.md]
FROM shared-cache (volume://shared-cache):
read-write at /mnt/shared-cache| Example | What it shows |
|---|---|
examples/quickstart/ |
Start here — single governed agent with Discord, cllama proxy, and dashboard |
examples/openclaw/ |
Single OpenClaw agent with Discord handle, skill emit, and service surface |
examples/nanobot/ |
Minimal Nanobot driver project with generated config + Discord handle wiring |
examples/picoclaw/ |
Minimal PicoClaw driver project with model-list config + Discord handle wiring |
examples/multi-claw/ |
Two agents sharing a volume surface with different access modes |
examples/trading-desk/ |
Three agents coordinating via Discord with a mock trading API, scheduled invocations, desk-wide risk feeds, and cllama governance proxy |
examples/rollcall/ |
All 7 drivers sharing one Discord identity — driver parity fixture and end-to-end cllama validation |
Clawdapus is designed for autonomous fleet governance. The operator writes the Clawfile and sets the budgets, but day-to-day oversight can be delegated to a Master Claw — an AI governor.
The Governance Proxy is its Sensory Organ:
The cllama proxy is the programmatic choke point. It sits on the network, enforces the hard rules (rate limits, budgets, PII blocking), and emits structured telemetry logs (drift, cost, interventions). It doesn't "think" about management; it is a passive sensor and firewall.
The Master Claw is the Brain: The Master Claw is an actual LLM-powered agent running in the pod, tasked with reading proxy telemetry. If a proxy reports an agent drifting, burning budget, or failing policy checks, the Master Claw makes an executive decision to dynamically shift budgets, promote recipes, or quarantine the drifting agent.
In enterprise deployments, this naturally forms a Hub-and-Spoke Governance Model. Multiple pods across different zones have their own cllama proxies acting as local firewalls, while a single Master Claw ingests telemetry from them all to autonomously manage the entire neural fleet.
$ claw ps
TENTACLE STATUS CLLAMA DRIFT
crypto-crusher-0 running healthy 0.02
crypto-crusher-1 running healthy 0.04
crypto-crusher-2 running WARNING 0.31
$ claw audit crypto-crusher-2 --last 24h
14:32 tweet-cycle OUTPUT MODIFIED by cllama:policy (financial advice detected)
18:01 engagement-sweep OUTPUT DROPPED by cllama:purpose (off-strategy)Drift is independently scored — not self-reported. The structured logs from cllama provide the raw telemetry today; the claw audit command and drift scoring are Phase 5.
$ claw recipe crypto-crusher-0 --since 7d
pip: tiktoken==0.7.0, trafilatura>=0.9
apt: jq
files: scripts/scraper.py
Apply? claw bake crypto-crusher --from-recipe latestBots install things. That's how real work gets done. Tracked mutation is evolution. Untracked is drift. Ad hoc capability-building becomes permanent infrastructure through a human gate.
- Purpose is sacred — contract is bind-mounted read-only; survives full container compromise
- The workspace is alive — bots install and adapt; mutations are tracked and promotable
- Configuration is code — every deviation from defaults is diffable
- Drift is an open metric — independent audit via the governance proxy, not self-report
- Surfaces are declared — topology for operators; capability discovery for bots. The proxy enforces cognitive boundaries.
- Claws are users — standard credentials; the proxy governs intent, the service's own auth governs execution
- Compute is a privilege — operator assigns models and schedules; proxy enforces budgets and rate limits; bot doesn't choose
- Think twice, act once — a reasoning model cannot be its own judge
- Memory survives the container (and the runner) — session history is captured at the proxy boundary and persisted outside the runtime directory. Bots don't start amnesia-fresh after every restart. Infrastructure owns the record; the runner owns the scratch space. Two surfaces, two owners, never merged. Because the architecture is the agent, you can swap the runtime (
CLAW_TYPE) without losing the mind; knowledge seamlessly crosses driver boundaries.
v0.3.2 released — download
| Phase | Status |
|---|---|
| Phase 1 — Clawfile parser + build | Done |
| Phase 2 — Driver framework + pod runtime + OpenClaw + volume surfaces | Done |
| Phase 3 — Surface manifests, service skills, CLAWDAPUS.md | Done |
| Phase 3.5 — HANDLE directive + social topology (Discord, Telegram, Slack) | Done |
| Phase 3.6 — INVOKE scheduling + Discord config wiring | Done |
| Phase 3.7 — Social topology: mentionPatterns, allowBots, peer handle users | Done |
| Phase 3.8 — Channel surface bindings | Done |
| Phase 4 — Shared governance proxy integration + credential starvation | Done |
| Phase 4.5 — Interactive claw init & claw agent add (canonical layout) | Done |
| Phase 4.7 — Nanobot + PicoClaw + NullClaw + MicroClaw drivers | Done |
| Phase 4.8 — Hermes driver + shared helper extraction | Done |
| Phase 4.9 — Peer handles, mention safety, healthcheck passthrough | Done |
| Phase 4.6 — Unified worker architecture (config, provision, diagnostic) | Design |
| Phase 5 — Fleet governance: Master Claw, telemetry, context feeds | Design (ADRs 012–015) |
| Phase 6 — Recipe promotion + worker mode | Planned |
MANIFESTO.md— vision, principles, full architecturedocs/plans/2026-02-18-clawdapus-architecture.md— implementation plandocs/CLLAMA_SPEC.md— Standardized Sidecar interface for policy and compute meteringdocs/decisions/001-cllama-transport.md— ADR: cllama as sidecar HTTP proxydocs/decisions/002-runtime-authority.md— ADR: compose-only lifecycle authoritydocs/decisions/003-topology-simplification.md— ADR: Topology simplification and the HANDLE directivedocs/decisions/004-service-surface-skills.md— ADR: Service surface skills strategydocs/decisions/006-invoke-scheduling.md— ADR: INVOKE scheduling mechanismdocs/decisions/007-llm-isolation-credential-starvation.md— ADR: LLM Isolation via Credential Starvationdocs/decisions/008-cllama-sidecar-standard.md— ADR: cllama as a Standardized Sidecar Interfacedocs/decisions/009-contract-composition-and-policy.md— ADR: Contract Composition and Policy Inclusiondocs/decisions/010-cli-surface-simplification.md— ADR: CLI Surface Simplification (claw compose *→claw *)docs/decisions/011-canonical-project-layout.md— ADR: Canonical-By-Default Scaffold Layoutdocs/decisions/012-master-claw-fleet-governance.md— ADR: Master Claw and Fleet Governancedocs/decisions/013-context-feeds.md— ADR: Context Feeds — Live Data Injection for Clawsdocs/decisions/014-telemetry-normalization-and-audit.md— ADR: Telemetry Normalization andclaw auditdocs/decisions/015-claw-api-authentication-and-scoping.md— ADR:claw-apiAuthentication and Authorization Scopingdocs/decisions/016-canonical-social-identity-and-conformance-spikes.md— ADR: Canonical Social Identity and Conformance Spikesdocs/decisions/017-pod-defaults-and-service-self-description.md— ADR: Pod-Level Defaults and Service Self-Description (claw.describe, provider-owned feeds)docs/decisions/018-session-history-and-memory-retention.md— ADR: Session History and Persistent Memory Surfaces (two surfaces, two owners, phase model)docs/UPDATING.md— checklist of everything to update when implementation changesTESTING.md— unit, E2E, and spike test runbook
Start with MANIFESTO.md before contributing.
