{"id":44388315,"url":"https://github.com/mostlydev/clawdapus","last_synced_at":"2026-04-29T05:01:27.992Z","repository":{"id":337917061,"uuid":"1152447790","full_name":"mostlydev/clawdapus","owner":"mostlydev","description":"Docker on Rails for Claws","archived":false,"fork":false,"pushed_at":"2026-04-03T21:44:37.000Z","size":42180,"stargazers_count":2,"open_issues_count":9,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-03T22:34:02.351Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mostlydev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-07T22:17:19.000Z","updated_at":"2026-04-03T21:44:42.000Z","dependencies_parsed_at":"2026-04-02T03:00:36.408Z","dependency_job_id":null,"html_url":"https://github.com/mostlydev/clawdapus","commit_stats":null,"previous_names":["mostlydev/clawdapus"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/mostlydev/clawdapus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mostlydev%2Fclawdapus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mostlydev%2Fclawdapus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mostlydev%2Fclawdapus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mostlydev%2Fclawdapus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mostlydev","download_url":"https://codeload.github.com/mostlydev/clawdapus/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mostlydev%2Fclawdapus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31526666,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-12T01:49:24.010Z","updated_at":"2026-04-27T02:02:28.499Z","avatar_url":"https://github.com/mostlydev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ![Clawdapus Logo](docs/art/clawdapus.png)\n\n**Infrastructure-layer governance for AI agent containers.**\n\n[Documentation](https://clawdapus.dev/) | [Quickstart](https://clawdapus.dev/guide/quickstart) | [Manifesto](https://clawdapus.dev/manifesto)\n\n\u003e Swarm is for agents that work *for* you. Clawdapus is for bots that work *as* you.\n\nEvery 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.**\n\nThat 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.**\n\nClawdapus treats the agent as an untrusted workload. It is the layer below the framework, where deployment meets governance, identity projection, and strict cost containment.\n\n---\n\n## Quickstart (5 minutes)\n\n**You need:** Docker Desktop, an [OpenRouter](https://openrouter.ai/) API key, and a Discord bot token + guild ID (see [Discord setup guide](./examples/quickstart/README.md#discord-bot-setup)).\n\n```bash\n# Install\ncurl -sSL https://raw.githubusercontent.com/mostlydev/clawdapus/master/install.sh | sh\n\n# Clone the quickstart example\ngit clone https://github.com/mostlydev/clawdapus.git\ncd clawdapus/examples/quickstart\n\n# Configure\ncp .env.example .env\n# Edit .env — add OPENROUTER_API_KEY, DISCORD_BOT_TOKEN, DISCORD_BOT_ID, DISCORD_GUILD_ID\n\n# Run the operator loop\nsource .env\n\n# 1. pull pinned runtime infra, registry-backed pod services, and runner bases\nclaw pull\n\n# 2. build this pod's local build: services\nclaw build\n\n# 3. compile the pod and launch it\nclaw up -d\n\n# Verify\nclaw ps        # assistant + cllama both running\nclaw health    # both healthy\n\n# Run any docker compose command against the pod\nclaw compose exec assistant bash\nclaw compose restart cllama\nclaw compose top\n\n# 4. tear the pod down when you're done\nclaw down\n```\n\nThe cllama governance proxy dashboard runs on port **8181** — every LLM call in real time: which agent, which model, token counts, cost.\n\nThe Clawdapus Dash fleet dashboard runs on port **8082** — live service health, topology wiring, per-service drill-down, and agent context inspection. The Agents view shows each claw's compiled `AGENTS.md`/`CLAWDAPUS.md`, redacted runtime manifests, and the latest live context snapshot captured by cllama.\n\nThe operator surface is four verbs:\n- `claw pull` fetches pinned runtime infra, registry-backed pod services, and refreshes built-in local runner bases\n- `claw build` builds pod services that declare `build:`\n- `claw up` compiles the pod and launches it, staying strict by default\n- `claw down` tears the pod back down\n\nRunner refresh happens through `claw pull`: for a pod it refreshes the runner bases used by `build:` services, and for a single Clawfile you can run `claw pull ./agents/assistant/Clawfile`. Use `claw pull --no-runners` when you want the fast pinned-infra path only.\n\nIf `claw up` finds something missing, it tells you exactly which command to run next. `claw up --fix -d` can pull/build missing infra and service images, but runner refresh still happens through `claw pull`.\n\nMessage `@quickstart-bot` in your Discord server. The bot responds through the proxy — it has no direct API access. The dashboard updates live.\n\n`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.\n\nSupported x-claw placeholder forms match shell-style parameter expansion:\n- `${VAR}` required\n- `${VAR:-default}` default when unset or empty\n- `${VAR-default}` default when unset\n- `${VAR:?message}` fail when unset or empty\n- `${VAR?message}` fail when unset\n- `${VAR:+value}` substitute `value` when set and non-empty\n- `${VAR+value}` substitute `value` when set\n\nBuilt-in x-claw variables:\n- `REPO_ROOT` defaults to the pod directory passed to `claw up`\n\nThis placeholder expansion is specific to `x-claw` metadata. Standard Compose fields still use normal Docker Compose `.env` interpolation rules.\n\nFor 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.\n\nSee [`examples/quickstart/`](./examples/quickstart/) for the full walkthrough, Telegram/Slack alternatives, and migration from existing OpenClaw.\n\nOr scaffold from scratch:\n\n```bash\nclaw init my-pod\ncd my-pod\ncp .env.example .env\nsource .env\nclaw pull\nclaw build\nclaw up -d\n\n# add another agent later\nclaw agent add researcher\n```\n\nGenerated projects use the same operator loop: `claw pull`, `claw build`, `claw up`, then `claw down` when you're finished.\n\n`claw agent add` preserves the project's existing layout by default:\n- Canonical project: adds `agents/\u003cname\u003e/Clawfile` + `agents/\u003cname\u003e/AGENTS.md`\n- Flat project: adds `Clawfile.\u003cname\u003e` + `AGENTS-\u003cname\u003e.md`\n\nUse `--layout canonical` or `--layout flat` to override auto-detection.\n\n---\n\n## Install\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/mostlydev/clawdapus/master/install.sh | sh\nclaw doctor\n```\n\nOr build from source:\n\n```bash\ngo build -o bin/claw ./cmd/claw\n```\n\n## Update\n\nClawdapus moves fast — update frequently.\n\n```bash\nclaw update\n```\n\n`claw` checks for updates once an hour and prints a notice when a newer release is available.\n\n### Install AI Skill\n\nGive 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.\n\n```bash\n# Recommended: installs to ~/.claude/skills/ and ~/.agents/skills/\n# Auto-updates whenever you update the claw binary.\nclaw skill install\n```\n\nOr install manually:\n\n```bash\nSKILL_URL=\"https://raw.githubusercontent.com/mostlydev/clawdapus/master/skills/clawdapus/SKILL.md\"\n\n# Claude Code / OpenCode\nmkdir -p ~/.claude/skills/clawdapus-cli\ncurl -sSL \"$SKILL_URL\" -o ~/.claude/skills/clawdapus-cli/SKILL.md\n\n# Codex CLI / Gemini CLI / OpenCode (shared .agents/skills/ convention)\nmkdir -p .agents/skills/clawdapus-cli\ncurl -sSL \"$SKILL_URL\" -o .agents/skills/clawdapus-cli/SKILL.md\n\n# Cursor / Windsurf / other .cursorrules-based agents\ncurl -sSL \"$SKILL_URL\" \u003e\u003e .cursorrules\n```\n\n---\n\n# Architecture\n\n## What It Looks Like\n\n**The Image (`Clawfile`)** — an extended Dockerfile.\n\n```dockerfile\nFROM openclaw:latest\n\nCLAW_TYPE openclaw\nAGENT AGENTS.md                   # behavioral contract — bind-mounted read-only\n\nMODEL primary openrouter/anthropic/claude-sonnet-4\nMODEL fallback anthropic/claude-haiku-3-5\n\nCLLAMA passthrough                # governance proxy — credential starvation + cost tracking\n\nHANDLE discord                    # platform identity — mention patterns, peer discovery\nINVOKE 15 8 * * 1-5  pre-market   # scheduled invocation — cron, managed by operator\n\nSURFACE service://trading-api     # declared capabilities — auto-discovered, skill-mapped\nSURFACE volume://shared-research read-write\n\nSKILL policy/risk-limits.md       # operator policy — mounted read-only into runner\n```\n\n**The Deployment (`claw-pod.yml`)** — an extended docker-compose.\n\n```yaml\nx-claw:\n  pod: trading-desk\n  master: octopus\n  cllama-defaults:\n    proxy: [passthrough]\n    env:\n      OPENROUTER_API_KEY: \"${OPENROUTER_API_KEY}\"\n      ANTHROPIC_API_KEY: \"${ANTHROPIC_API_KEY}\"\n  surfaces-defaults:\n    - \"service://trading-api\"\n    - \"volume://shared-research read-write\"\n  feeds-defaults: [market-context]    # resolved from trading-api's claw.describe\nservices:\n  tiverton:\n    image: trading-desk-tiverton:latest\n    build:\n      context: ./agents/tiverton\n    x-claw:\n      agent: ./agents/tiverton/AGENTS.md\n      handles:\n        discord:\n          id: \"${TIVERTON_DISCORD_ID}\"\n          username: \"tiverton\"\n      invoke:\n        - schedule: \"15 8 * * 1-5\"\n          name: \"Pre-market synthesis\"\n          message: \"Run pre-market synthesis and post the floor briefing.\"\n          to: trading-floor\n```\n\nServices inherit `cllama-defaults`, `surfaces-defaults`, and `feeds-defaults` from the pod. Override any field to replace; use `...` spread to extend:\n\n```yaml\n    x-claw:\n      skills:\n        - ...                          # inherit pod defaults\n        - ./policy/escalation.md       # add coordinator-only skill\n```\n\n`claw 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.\n\n---\n\n## How It Works\n\nClawdapus extends two formats you already know:\n\n| Clawdapus | Docker equivalent | Purpose |\n|-----------|------------------|---------|\n| `claw init` | `docker init` + project templating | Scaffold canonical-by-default project layout |\n| `claw agent add` | _(none)_ | Add agents while preserving existing layout (`--layout auto|canonical|flat`) |\n| `Clawfile` | `Dockerfile` | Build an immutable agent image |\n| `claw-pod.yml` | `docker-compose.yml` | Run a governed agent fleet |\n| `claw pull` | `docker compose pull` + `docker build --pull --no-cache` | Fetch pinned infra, pod registry images, and built-in local runner base aliases |\n| `claw build` | `docker build` | Transpile + build OCI image, or build every `build:` service in the pod |\n| `claw up` | `docker compose up` | Enforce + deploy; authoritative on what is stale |\n\nAny 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.\n\n---\n\n## Clawfile Directives\n\nThe 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.\n\n| Directive | Purpose |\n|---|---|\n| `CLAW_TYPE` | Selects the runtime driver (openclaw, hermes, nanobot, picoclaw, nanoclaw, microclaw, nullclaw) |\n| `AGENT` | Names the behavioral contract file |\n| `PERSONA` | Imports a persona workspace — local path or OCI artifact ref |\n| `MODEL` | Binds named model slots to providers |\n| `CLLAMA` | Declares governance proxy type(s) |\n| `HANDLE` | Declares platform identity (discord, telegram, slack, and others per driver) |\n| `INVOKE` | Scheduled invocations via cron |\n| `SURFACE` | Declared in pod YAML — volumes, services, channels |\n| `SKILL` | Operator policy files mounted read-only |\n| `INCLUDE` | Pod-level contract composition — `enforce`, `guide`, or `reference` mode |\n| `CONFIGURE` | Runner-specific config mutations at init |\n| `TRACK` | Wraps package managers to log mutations |\n| `PRIVILEGE` | Drops container privileges |\n\n---\n\n## Claw Type Support\n\nPick a driver based on what you need. All drivers support `MODEL`, `AGENT`, `CLLAMA`, and `CONFIGURE`.\n\n| | `openclaw` | `hermes` | `nanoclaw` | `nanobot` | `picoclaw` | `nullclaw` | `microclaw` |\n|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|\n| **Runtime** | [OpenClaw](https://openclaw.ai) | [Hermes](https://github.com/NousResearch/hermes-agent) | [Claude Agent SDK](https://github.com/anthropics/claude-code) | [Nanobot](https://github.com/HKUDS/nanobot) | [PicoClaw](https://github.com/sipeed/picoclaw) | [NullClaw](https://github.com/nullclaw/nullclaw) | [MicroClaw](https://github.com/microclaw/microclaw) |\n| `claw init` scaffold | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| HANDLE: Discord | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ |\n| HANDLE: Telegram | — | ✅ | — | ✅ | ✅ | ✅ | ✅ |\n| HANDLE: Slack | — | ✅ | — | ✅ | ✅ | ✅ | ✅ |\n| HANDLE: long-tail ¹ | — | — | — | — | ✅ | — | — |\n| INVOKE (cron) | ✅ | ✅ | — | ✅ | ✅ | ✅ | — |\n| Structured health | ✅ | ✅ | — | — | ✅ | ✅ | — |\n| Read-only rootfs | ✅ | ✅ | — | ✅ | ✅ | ✅ | — |\n| Non-root container | — | — | — | — | ✅ | — | — |\n\n¹ PicoClaw long-tail: WhatsApp, Feishu, LINE, QQ, DingTalk, OneBot, WeCom, WeCom App, Pico, MaixCam.\n`claw init` scaffolds `generic` (alpine:3.20, no driver enforcement) for custom runtimes.\n\n### OpenClaw Discord Routing Compatibility\n\nThe OpenClaw driver now maps the supported `channel://discord` routing controls directly into generated config and rejects the unsupported ones early.\n\n| `channel://discord` map-form setting | `openclaw` |\n|---|:---:|\n| DM `policy` (`pairing`, `allowlist`, `open`, `disabled`) | ✅ |\n| DM `allowFrom` | ✅ |\n| Guild `requireMention` | ✅ |\n| Guild `users[]` allowlist | ✅ |\n| Surface `allow_from_handles: true` → expands into each guild `users[]` | ✅ |\n| Surface `allow_from_services: [svc...]` → derives Discord IDs from service bot tokens and expands each guild `users[]` | ✅ |\n| Guild `policy` | — ² |\n\n² 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.\n\n---\n\n## Nullclaw `CONFIGURE` Examples\n\nUse these when you want high-level `HANDLE` defaults, but need runtime-specific policy details.\n\n```dockerfile\n# Base identity on a platform:\nHANDLE discord\n\n# \"Can talk on\" -\u003e pin to one guild/server\nCONFIGURE nullclaw config set channels.discord.accounts.main.guild_id \"123456789012345678\"\n\n# \"Can talk to\" -\u003e require mention in group chats\nCONFIGURE nullclaw config set channels.discord.accounts.main.require_mention true\n\n# Telegram allowlist for DMs\nCONFIGURE nullclaw config set channels.telegram.accounts.main.allow_from [\"111111111\",\"222222222\"]\n\n# Slack transport mode selection\nCONFIGURE nullclaw config set channels.slack.accounts.main.mode \"socket\"\n```\n\nNotes:\n- `CONFIGURE` is driver-side DSL here (`nullclaw config set \u003cpath\u003e \u003cvalue\u003e`), applied to generated `config.json`.\n- Values are parsed as JSON when possible: booleans/numbers/arrays/objects should be unquoted; strings should be quoted.\n- `CONFIGURE` runs after defaults, so it overrides what `HANDLE` generated.\n\n---\n\n## The Anatomy of a Claw\n\n```mermaid\nblock-beta\n  columns 1\n  contract[\"Behavioral Contract\\nread-only bind mount\\nAGENTS.md — purpose, on the host\\nSurvives full container compromise\"]\n  runner[\"Runner\\nOpenClaw · NanoClaw · Claude Code · custom\"]\n  persona[\"Persona\\nMemory · history · style · knowledge\"]\n  proxy[\"cllama — governance proxy\\nIntercepts prompts outbound + responses inbound\\nRunner never knows it's there\"]\n\n  style contract fill:#1a1a2e,stroke:#22d3ee,color:#eee\n  style runner fill:#1a1a2e,stroke:#f0a500,color:#eee\n  style persona fill:#1a1a2e,stroke:#a78bfa,color:#eee\n  style proxy fill:#1a1a2e,stroke:#34d399,color:#eee\n```\n\nThe 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.\n\n---\n\n## cllama: The Governance Proxy\n\nWhen 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.\n\n- **Credential starvation:** The proxy holds the real API keys. Agents get unique bearer tokens. No credentials, no bypass.\n- **Identity resolution:** Single proxy serves an entire pod. Bearer tokens resolve which agent is calling.\n- **Cost accounting:** Extracts token usage from every response, multiplies by pricing table, tracks per agent/provider/model.\n- **Audit logging:** Structured JSON on stdout — timestamp, agent, model, latency, tokens, cost, intervention reason.\n- **Managed tool mediation:** Services declare callable tools via `claw.describe` (MCP-shaped schemas). `claw up` compiles per-agent `tools.json`. cllama injects tools into LLM requests, intercepts `tool_call` responses, executes them against the service, and loops until terminal text — transparent to the runner. Both OpenAI-compatible and Anthropic formats are supported.\n- **Ambient memory plane:** Services declare `recall`, `retain`, and `forget` endpoints via `claw.describe`. `claw up` compiles per-agent `memory.json`. cllama calls `/recall` before each inference turn and `/retain` after each successful response (async, non-blocking). Memory intelligence stays in swappable external services — the proxy owns orchestration only.\n- **Operator dashboard:** Real-time web UI at host port 8181 by default (container `:8081`) — agent activity, provider status, cost breakdown.\n\nThe reference implementation is [`cllama`](https://github.com/mostlydev/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.\n\nSee the [cllama specification](./docs/CLLAMA_SPEC.md) for the full standard.\n\n---\n\n## Managed Tools (ADR-020)\n\nServices declare callable tools in their `claw.describe` descriptor. `claw up` compiles per-agent `tools.json` from the declared and policy-filtered tool catalog.\n\n```yaml\nservices:\n  analyst:\n    x-claw:\n      cllama: passthrough\n      surfaces:\n        - service://trading-api\n      tools:\n        - service: trading-api\n          allow:\n            - get_market_context   # read-only\n            - execute_trade        # side-effecting\n\n  trading-api:\n    image: trading-api:latest\n    # declares tools[] in claw.describe label\n```\n\n`tools:` follows the same pod-defaults model as `feeds:` and `surfaces:`. No tools are injected unless explicitly declared — deny by default.\n\ncllama injects the compiled tool schemas into each upstream LLM request, intercepts `tool_call` responses, executes them against the service, and loops until the LLM returns terminal text. The runner receives only the final text — managed tool rounds are transparent.\n\nNon-cllama services that declare `x-claw.tools` or `x-claw.memory` are a hard error at `claw up` time.\n\n---\n\n## Memory Plane (ADR-021)\n\nServices declare memory endpoints in their `claw.describe` descriptor. `claw up` compiles per-agent `memory.json`.\n\n```yaml\nservices:\n  analyst:\n    x-claw:\n      cllama: passthrough\n      memory:\n        service: mem-svc\n        timeout-ms: 300\n\n  mem-svc:\n    image: reference-memory:latest\n    # declares memory.recall/retain/forget in claw.describe\n```\n\ncllama calls `/recall` before each upstream inference request and `/retain` asynchronously after each successful response. Retain failures never fail the user-visible response.\n\nOperator commands:\n\n```bash\n# Replay the durable session ledger into a memory service\nclaw memory backfill mem-svc\n\n# Replay only entries after a given time\nclaw memory backfill mem-svc --after 2026-03-01T00:00:00Z\n\n# Tombstone a retained entry (does not mutate session history)\nclaw memory forget mem-svc --entry-id hist1_abc123 --reason \"operator request\"\n```\n\nA runnable reference adapter lives at [`examples/reference-memory/`](./examples/reference-memory/) — file-backed, idempotent on `entry.id`, tombstone-aware.\n\n---\n\n## Social Topology\n\n```bash\n# Available in every pod service automatically:\nCLAW_HANDLE_CRYPTO_CRUSHER_DISCORD_ID=123456789\nCLAW_HANDLE_CRYPTO_CRUSHER_DISCORD_GUILDS=111222333\n```\n\n`HANDLE 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.\n\nThe driver also wires each agent's openclaw config automatically: `allowBots: true` (enables bot-to-bot messaging), Discord `mentionPatterns` derived from the native handle ID so agents only trigger on explicit Discord mentions, and a guild `users[]` allowlist that includes every peer bot in the pod.\n\nWhen 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.\n\n---\n\n## Compilation Principles\n\n`claw up` is a compiler. It reads the pod file, inspects images, and emits deterministic runtime artifacts. These principles govern the compilation pipeline:\n\n1. **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.\n\n2. **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.\n\n3. **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.\n\n4. **One canonical descriptor.** A service's capabilities, feeds, and endpoints are declared once (via `claw.describe` in the image) and projected into whatever artifacts need them — CLAWDAPUS.md, feed manifests, effective agent contracts.\n\n5. **Services self-describe.** Images can carry a structured descriptor (`LABEL claw.describe=...`) that advertises feeds provided, auth requirements, and a skill file. `claw up` extracts and compiles these into the pod. Framework-specific adapters (e.g., RailsTrail for Rails apps) can generate descriptors from code introspection.\n\n---\n\n## Surfaces, Skills, and CLAWDAPUS.md\n\nEvery 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.\n\n```bash\n$ claw skillmap crypto-crusher-0\n\n  FROM market-scanner (service://market-scanner):\n    get_price            Current and historical token price data\n    get_whale_activity   Large wallet movements in last N hours\n    [discovered via OpenAPI → skills/surface-market-scanner.md]\n\n  FROM shared-cache (volume://shared-cache):\n    read-write at /mnt/shared-cache\n```\n\n---\n\n## Examples\n\n| Example | What it shows |\n|---------|---------------|\n| [`examples/quickstart/`](./examples/quickstart/) | **Start here** — single governed agent with Discord, cllama proxy, and dashboard |\n| [`examples/openclaw/`](./examples/openclaw/) | Single OpenClaw agent with Discord handle, skill emit, and service surface |\n| [`examples/nanobot/`](./examples/nanobot/) | Minimal Nanobot driver project with generated config + Discord handle wiring |\n| [`examples/picoclaw/`](./examples/picoclaw/) | Minimal PicoClaw driver project with model-list config + Discord handle wiring |\n| [`examples/multi-claw/`](./examples/multi-claw/) | Two agents sharing a volume surface with different access modes |\n| [`examples/trading-desk/`](./examples/trading-desk/) | Three agents coordinating via Discord with a mock trading API, scheduled invocations, desk-wide risk feeds, and cllama governance proxy |\n| [`examples/rollcall/`](./examples/rollcall/) | All 7 drivers sharing one Discord identity — driver parity fixture and end-to-end cllama validation |\n| [`examples/reference-memory/`](./examples/reference-memory/) | Runnable reference memory adapter — file-backed, idempotent retain, tombstone-aware forget, used by rollcall and capability-wave spike |\n\n---\n\n## The Master Claw (The Top Octopus)\n\nClawdapus 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.\n\n**The Governance Proxy is its Sensory Organ:**\nThe `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.\n\n**The Master Claw is the Brain:**\nThe 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.\n\nIn 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.\n\n---\n\n## Fleet Visibility (Design — Phase 5)\n\n```bash\n$ claw ps\n\nTENTACLE          STATUS    CLLAMA    DRIFT\ncrypto-crusher-0  running   healthy   0.02\ncrypto-crusher-1  running   healthy   0.04\ncrypto-crusher-2  running   WARNING   0.31\n\n$ claw audit crypto-crusher-2 --last 24h\n\n14:32  tweet-cycle       OUTPUT MODIFIED by cllama:policy  (financial advice detected)\n18:01  engagement-sweep  OUTPUT DROPPED by cllama:purpose  (off-strategy)\n```\n\nDrift 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.\n\n---\n\n## Recipe Promotion (Planned — Phase 6)\n\n```bash\n$ claw recipe crypto-crusher-0 --since 7d\n\n  pip: tiktoken==0.7.0, trafilatura\u003e=0.9\n  apt: jq\n  files: scripts/scraper.py\n\nApply?  claw bake crypto-crusher --from-recipe latest\n```\n\nBots 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.\n\n---\n\n## Core Principles\n\n1. **Purpose is sacred** — contract is bind-mounted read-only; survives full container compromise\n2. **The workspace is alive** — bots install and adapt; mutations are tracked and promotable\n3. **Configuration is code** — every deviation from defaults is diffable\n4. **Drift is an open metric** — independent audit via the governance proxy, not self-report\n5. **Surfaces are declared** — topology for operators; capability discovery for bots. The proxy enforces cognitive boundaries.\n6. **Claws are users** — standard credentials; the proxy governs intent, the service's own auth governs execution\n7. **Compute is a privilege** — operator assigns models and schedules; proxy enforces budgets and rate limits; bot doesn't choose\n8. **Think twice, act once** — a reasoning model cannot be its own judge\n9. **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. Retention is only half of memory. The **ambient memory plane** is live: pluggable memory services declared via `claw.describe`, compiled by `claw up`, and orchestrated by cllama — recalling derived context before each inference turn and retaining after each response. The agent does not manage its own long-term memory. Infrastructure does.\n\n---\n\n## Status\n\n**v0.3.2 released** — [download](https://github.com/mostlydev/clawdapus/releases/tag/v0.3.2)\n\n| Phase | Status |\n|-------|--------|\n| Phase 1 — Clawfile parser + build | Done |\n| Phase 2 — Driver framework + pod runtime + OpenClaw + volume surfaces | Done |\n| Phase 3 — Surface manifests, service skills, CLAWDAPUS.md | Done |\n| Phase 3.5 — HANDLE directive + social topology (Discord, Telegram, Slack) | Done |\n| Phase 3.6 — INVOKE scheduling + Discord config wiring | Done |\n| Phase 3.7 — Social topology: mentionPatterns, allowBots, peer handle users | Done |\n| Phase 3.8 — Channel surface bindings | Done |\n| Phase 4 — Shared governance proxy integration + credential starvation | Done |\n| Phase 4.5 — Interactive claw init \u0026 claw agent add (canonical layout) | Done |\n| Phase 4.7 — Nanobot + PicoClaw + NullClaw + MicroClaw drivers | Done |\n| Phase 4.8 — Hermes driver + shared helper extraction | Done |\n| Phase 4.9 — Peer handles, mention safety, healthcheck passthrough | Done |\n| Phase 4.10 — Capability evolution wave: compiled tools + memory plane | Done (ADRs 020–021) |\n| Phase 4.6 — Unified worker architecture (config, provision, diagnostic) | Design |\n| Phase 5 — Fleet governance: Master Claw, telemetry, context feeds | Design (ADRs 012–015) |\n| Phase 6 — Recipe promotion + worker mode | Planned |\n\n---\n\n## Documentation\n\n- [`MANIFESTO.md`](./MANIFESTO.md) — vision, principles, full architecture\n- [`docs/plans/2026-02-18-clawdapus-architecture.md`](./docs/plans/2026-02-18-clawdapus-architecture.md) — implementation plan\n- [`docs/CLLAMA_SPEC.md`](./docs/CLLAMA_SPEC.md) — Standardized Sidecar interface for policy and compute metering\n- [`docs/decisions/001-cllama-transport.md`](./docs/decisions/001-cllama-transport.md) — ADR: cllama as sidecar HTTP proxy\n- [`docs/decisions/002-runtime-authority.md`](./docs/decisions/002-runtime-authority.md) — ADR: compose-only lifecycle authority\n- [`docs/decisions/003-topology-simplification.md`](./docs/decisions/003-topology-simplification.md) — ADR: Topology simplification and the HANDLE directive\n- [`docs/decisions/004-service-surface-skills.md`](./docs/decisions/004-service-surface-skills.md) — ADR: Service surface skills strategy\n- [`docs/decisions/006-invoke-scheduling.md`](./docs/decisions/006-invoke-scheduling.md) — ADR: INVOKE scheduling mechanism\n- [`docs/decisions/007-llm-isolation-credential-starvation.md`](./docs/decisions/007-llm-isolation-credential-starvation.md) — ADR: LLM Isolation via Credential Starvation\n- [`docs/decisions/008-cllama-sidecar-standard.md`](./docs/decisions/008-cllama-sidecar-standard.md) — ADR: cllama as a Standardized Sidecar Interface\n- [`docs/decisions/009-contract-composition-and-policy.md`](./docs/decisions/009-contract-composition-and-policy.md) — ADR: Contract Composition and Policy Inclusion\n- [`docs/decisions/010-cli-surface-simplification.md`](./docs/decisions/010-cli-surface-simplification.md) — ADR: CLI Surface Simplification (`claw compose *` → `claw *`)\n- [`docs/decisions/011-canonical-project-layout.md`](./docs/decisions/011-canonical-project-layout.md) — ADR: Canonical-By-Default Scaffold Layout\n- [`docs/decisions/012-master-claw-fleet-governance.md`](./docs/decisions/012-master-claw-fleet-governance.md) — ADR: Master Claw and Fleet Governance\n- [`docs/decisions/013-context-feeds.md`](./docs/decisions/013-context-feeds.md) — ADR: Context Feeds — Live Data Injection for Claws\n- [`docs/decisions/014-telemetry-normalization-and-audit.md`](./docs/decisions/014-telemetry-normalization-and-audit.md) — ADR: Telemetry Normalization and `claw audit`\n- [`docs/decisions/015-claw-api-authentication-and-scoping.md`](./docs/decisions/015-claw-api-authentication-and-scoping.md) — ADR: `claw-api` Authentication and Authorization Scoping\n- [`docs/decisions/016-canonical-social-identity-and-conformance-spikes.md`](./docs/decisions/016-canonical-social-identity-and-conformance-spikes.md) — ADR: Canonical Social Identity and Conformance Spikes\n- [`docs/decisions/017-pod-defaults-and-service-self-description.md`](./docs/decisions/017-pod-defaults-and-service-self-description.md) — ADR: Pod-Level Defaults and Service Self-Description (`claw.describe`, provider-owned feeds)\n- [`docs/decisions/018-session-history-and-memory-retention.md`](./docs/decisions/018-session-history-and-memory-retention.md) — ADR: Session History and Persistent Memory Surfaces (two surfaces, two owners, phase model)\n- [`docs/decisions/020-cllama-compiled-tool-mediation.md`](./docs/decisions/020-cllama-compiled-tool-mediation.md) — ADR: Compiled Tool Plane with Native and Mediated Execution Modes\n- [`docs/decisions/021-memory-plane-and-pluggable-recall.md`](./docs/decisions/021-memory-plane-and-pluggable-recall.md) — ADR: Memory Plane as a Compiled Capability\n- [`docs/UPDATING.md`](./docs/UPDATING.md) — checklist of everything to update when implementation changes\n- [`TESTING.md`](./TESTING.md) — unit, E2E, and spike test runbook\n\n## Contributing\n\nStart with [`MANIFESTO.md`](./MANIFESTO.md) before contributing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmostlydev%2Fclawdapus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmostlydev%2Fclawdapus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmostlydev%2Fclawdapus/lists"}