Architecture plan: Clawdapus v2 — Go CLI for containerized agent governance#2
Architecture plan: Clawdapus v2 — Go CLI for containerized agent governance#2
Conversation
There was a problem hiding this comment.
Pull request overview
This PR introduces the foundational design documentation for “Clawdapus v2” as a Go-based CLI for building and governing containerized AI agents, with MANIFESTO.md designated as the source of truth and an architecture plan detailing the proposed build/runtime workflow.
Changes:
- Added
MANIFESTO.md(v0.8) describing the core concepts (Claw anatomy, principles, Clawfile, claw-pod.yml, cllama, drift, master Claw). - Added an architecture plan documenting key decisions (Go, hybrid build/runtime split, compose strategy) and a phased implementation roadmap.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
docs/plans/2026-02-18-clawdapus-architecture.md |
Architecture plan covering build/runtime split, compose approach, repo/package structure, directive/schema sketches, and phased implementation plan. |
MANIFESTO.md |
Vision/standard document defining Claw concepts, configuration formats (Clawfile + claw-pod.yml), governance model (cllama + drift), and initial implementation notes. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| A Clawfile compiles down to a standard Dockerfile. `claw build` is a preprocessor — it reads the Clawfile, translates extended directives into standard Dockerfile primitives, and calls `docker build` on the result. The output is a standard OCI container image. No custom build engine. | ||
|
|
||
| Extended directives compile to LABELs (metadata the runtime interprets), ENV vars (configuration the container reads), RUN commands (filesystem setup), and conventional file paths (cron entries, package manager wrappers, skill mount points). CLLAMA becomes a set of labels declaring the default judgment stack. AGENT becomes a label declaring the expected bind mount path. INVOKE becomes cron entries written into the image. TRACK becomes wrapper scripts around package managers. SURFACE becomes topology metadata labels. |
There was a problem hiding this comment.
The compilation description says “AGENT becomes a label declaring the expected bind mount path”, but the architecture plan’s directive table defines AGENT as a contract filename convention (claw.agent.file=...). Please align these docs by specifying whether the label records a filename, a container path, a host path, or some combination, to avoid ambiguity in the build/runtime contract.
| Extended directives compile to LABELs (metadata the runtime interprets), ENV vars (configuration the container reads), RUN commands (filesystem setup), and conventional file paths (cron entries, package manager wrappers, skill mount points). CLLAMA becomes a set of labels declaring the default judgment stack. AGENT becomes a label declaring the expected bind mount path. INVOKE becomes cron entries written into the image. TRACK becomes wrapper scripts around package managers. SURFACE becomes topology metadata labels. | |
| Extended directives compile to LABELs (metadata the runtime interprets), ENV vars (configuration the container reads), RUN commands (filesystem setup), and conventional file paths (cron entries, package manager wrappers, skill mount points). CLLAMA becomes a set of labels declaring the default judgment stack. AGENT becomes a label declaring the expected in-container behavioral contract filename (for example, the AGENTS.md or CLAUDE.md file that will be provided via a bind mount from the host). INVOKE becomes cron entries written into the image. TRACK becomes wrapper scripts around package managers. SURFACE becomes topology metadata labels. |
|
|
||
| ### Extension, Not Replacement | ||
|
|
||
| Just as the Clawfile extends the Dockerfile, `claw-pod.yml` extends docker-compose. Any valid compose file is a valid claw-pod.yml. Extended keys live under an `x-claw` namespace, which Docker already ignores. Existing tooling works unchanged. |
There was a problem hiding this comment.
“x-claw … which Docker already ignores” is potentially misleading: it’s the Docker Compose spec/CLI that ignores x- extension fields; the Docker Engine doesn’t read compose YAML. Consider rewording to “Docker Compose ignores x- extension fields” to keep the compatibility claim technically precise.
| Just as the Clawfile extends the Dockerfile, `claw-pod.yml` extends docker-compose. Any valid compose file is a valid claw-pod.yml. Extended keys live under an `x-claw` namespace, which Docker already ignores. Existing tooling works unchanged. | |
| Just as the Clawfile extends the Dockerfile, `claw-pod.yml` extends docker-compose. Any valid compose file is a valid claw-pod.yml. Extended keys live under an `x-claw` namespace, which Docker Compose already ignores. Existing tooling works unchanged. |
| ``` | ||
| $ claw ps | ||
|
|
||
| TENTACLE STATUS CLLAMA DRIFT |
There was a problem hiding this comment.
The claw ps example output uses the column header TENTACLE, but the rest of the docs consistently call these units “Claws”/containers (and the command is claw ps). Either define “tentacle” earlier or rename the column to something consistent (e.g., CLAW, SERVICE, or CONTAINER) to reduce terminology drift.
| TENTACLE STATUS CLLAMA DRIFT | |
| CLAW STATUS CLLAMA DRIFT |
MANIFESTO.md
Outdated
| Clawdapus uses a hybrid approach: | ||
|
|
||
| - **Build phase** — `claw build` transpiles the Clawfile into a standard Dockerfile and calls `docker build`. Output is an inspectable build artifact, not something you edit directly — like a compiled binary. | ||
| - **Runtime phase** — `clawdapus` drives container lifecycle, injects environment, mediates surfaces, runs cllama. Always go through `claw` commands at runtime. |
There was a problem hiding this comment.
In Implementation Notes, runtime is described as “clawdapus drives container lifecycle … Always go through claw commands at runtime.” Elsewhere the plan positions claw as the single Go CLI binary. Please clarify naming/packaging (is there a separate clawdapus daemon/binary, or is this the same claw CLI?) to avoid confusion for implementers and users.
| - **Runtime phase** — `clawdapus` drives container lifecycle, injects environment, mediates surfaces, runs cllama. Always go through `claw` commands at runtime. | |
| - **Runtime phase** — the `claw` CLI drives container lifecycle, injects environment, mediates surfaces, runs cllama (the internal runtime engine is codenamed “clawdapus” but ships as part of the single `claw` binary; there is no separate daemon/binary). Always go through `claw` commands at runtime. |
| `claw-pod.yml` is a valid `docker-compose.yml`. The `x-claw` extension namespace is already ignored by Docker natively. Clawdapus: | ||
| 1. Parses `claw-pod.yml` using a Go YAML library | ||
| 2. Processes `x-claw` blocks (surfaces, cllama config, count scaling, skill maps) | ||
| 3. Emits a clean compose file without `x-claw` keys | ||
| 4. Shells out to `docker compose` with the generated file |
There was a problem hiding this comment.
The statement that the x-claw extension namespace is “ignored by Docker natively” is inaccurate/misleading. It’s Docker Compose (per the Compose spec’s extension fields) that ignores x- keys; the Docker Engine doesn’t parse compose files. Recommend rewording to avoid implying the engine understands docker-compose.yml/extensions.
|
|
||
| ### 4. Docker SDK Strategy | ||
|
|
||
| - **Docker Go SDK** for runtime operations: start/stop containers, inspect state, stream logs, handle events |
There was a problem hiding this comment.
This “Docker Go SDK for runtime operations: start/stop…” bullet conflicts with the earlier statement that runtime “Shells out to docker compose for container lifecycle”. Please clarify the split of responsibilities (e.g., compose for lifecycle + SDK for inspect/events/logs only) so the plan doesn’t prescribe two different sources of truth for start/stop.
| - **Docker Go SDK** for runtime operations: start/stop containers, inspect state, stream logs, handle events | |
| - **Docker Go SDK** for runtime observability and introspection: inspect state, stream logs, subscribe to events (no container start/stop here — `docker compose` remains the lifecycle controller) |
| ## CLI Commands (Phase 1 scope) | ||
|
|
||
| ``` | ||
| claw build [path] # Clawfile → Dockerfile → docker build | ||
| claw up [pod] # claw-pod.yml → compose.yml → docker compose up | ||
| claw down [pod] # Stop and remove pod containers | ||
| claw ps [pod] # Status of all Claws in pod (with drift, cllama health) | ||
| claw logs <claw> # Stream logs from a running Claw | ||
| claw skillmap <claw> # Show assembled capability inventory | ||
| claw audit <claw> [--last Xh] # Show cllama intervention history and drift events | ||
| claw recipe <claw> [--since Xd] # Show suggested recipe from mutation log | ||
| claw snapshot <claw> --as <ref> # Snapshot running Claw as new image | ||
| ``` |
There was a problem hiding this comment.
This section is labeled “CLI Commands (Phase 1 scope)” but includes commands that are explicitly deferred to later phases (e.g., claw skillmap is Phase 3, claw audit aligns with Phase 5, and claw recipe/claw snapshot align with Phase 6). Suggest either renaming this section to “Planned CLI surface” or trimming it to Phase 1 commands to keep scope statements consistent.
- Move openclaw/ and scripts/ to archive/openclaw-runtime/ - Architecture plan v2: incorporates Grok + Codex review feedback - Add hard invariants section (fail-closed defaults) - Single lifecycle authority: compose only, SDK read-only - Promote cllama to Phase 2 as bidirectional LLM proxy (sidecar) - Decouple persona from image build (runtime mount via oras) - Add Claw identity and scaling semantics - Clarify CONFIGURE as entrypoint wrapper, not build-time RUN - Add build-time vs deploy-time overridability table - Add claw doctor, claw inspect, claw bake commands - Reduce open questions from 5 to 4 - New CLAUDE.md for v2 project structure - Add .DS_Store to gitignore
Architecture plan v3 reflects 3-agent deliberation consensus: - Invariants now promote SHOULD→MUST per-phase as enforcement ships - Phase 2 split into 2A (pod runtime) and 2B (cllama sidecar), parallel - Each phase lists which invariants it promotes - cllama dual modes: proxy (default, built first) and adapter (documented gap) ADR-001: cllama transport — sidecar HTTP proxy as primary mode ADR-002: runtime authority — compose-only lifecycle, SDK read-only
Manifesto v0.9: - Add terminology section (Clawdapus = platform, Claw = instance) - Update cllama to bidirectional LLM proxy model throughout - Key isolation is now default (sidecar holds real keys, runner never sees them) - Condense claw types into table, reduce repetitive runner descriptions - Replace implementation notes section with links to actual docs/ADRs README: - Add ADRs to document table - Add full CLI command list (doctor, inspect, bake, recipe)
- CLAW_TYPE selects a runtime driver, not just a label - Drivers implement abstract enforcement ops (set, unset, mount_ro, env, etc.) - OpenClaw driver uses openclaw config set (JSON5-aware, never raw jq) - Config injection is primary enforcement; cllama is optional enhancement - cllama deferred to Phase 4 (was Phase 2B) - Network restriction enforced at pod/compose level, not driver level - Fail-closed: preflight + post-apply verification before compose up - Common runner control contract for easy third-party integration
- Volume surfaces (shared folders) added to Phase 2 alongside pod runtime - Phase 3 renamed to Service Surfaces — scoped to service/MCP/queue surfaces only - Post-apply verification corrected to fail-closed (not warn) - MANIFESTO.md and README.md: cllama framed as optional enhancement layer
- Add surface taxonomy: pod-level (volume, host, service, egress) vs driver-level (channel, webhook) - Pod-level surfaces enforced by Clawdapus during compose generation - Driver-level surfaces mediated by claw-type driver (runner-specific config injection) - Channel binding example: channel://discord in claw-pod.yml translated by OpenClaw driver to openclaw config set calls - Driver capability map includes supported surface schemes - Phase 3 updated to include channel bindings alongside service surfaces - Fix stale PR #2 link in README (PR merged to master)
#1 (High) Parse ports: alongside expose: for service surface port hints - Add Ports []string to Service struct (pod/types.go) - parsePorts() extracts container-side port from string/int/map compose forms: "8080:80" → "80", "127.0.0.1:8080:80/tcp" → "80", map target: field - mergedPorts() deduplicates expose + ports before enriching ResolvedSurface.Ports - Tests: 9 new tests covering all port string forms, numeric entries, map form, dedup #2 (Medium) claw.skill.emit extraction failure is now warn+fallback - extractServiceSkillFromImage error logs warning and returns nil, nil - Pod startup continues with generated fallback skill instead of hard error - Invalid path (bad filename) remains a hard error — that's operator misconfiguration - Test: TestResolveSkillEmitFallsBackOnExtractionError #3 (High) Document CONFIGURE account binding pattern for HANDLE - Add HANDLE discord + CONFIGURE account/binding directives to examples/openclaw/Clawfile - Comment explains: HANDLE enables transport only; CONFIGURE injects account token (from env var) and routes the agent to that account
Use `<@id>` in CLAWDAPUS.md peer handles so agents can copy-paste a working mention rather than a bare ID or @username that Discord doesn't resolve. Also bumps cllama submodule to include runtime provider-add and the provider token-pool state machine (merged via PR #2 in cllama). docs(agents): add hermes-base and claw-wall multi-arch build notes
Summary
This PR adds the foundational documents for Clawdapus v2 — a complete rethink of the project as infrastructure-layer governance for AI agent containers.
MANIFESTO.md— Full vision document (v0.8), sourced from the original gist, with an added Implementation Notes section capturing early architectural decisions.docs/plans/2026-02-18-clawdapus-architecture.md— Detailed architecture plan ready for review.Key decisions captured in the plan
claw buildtranspiles Clawfile → Dockerfile → callsdocker build;claw upparses claw-pod.yml → emits clean compose.yml → callsdocker composex-clawextension namespace — already ignored natively by Docker, zero breaking changes to standard toolingWhat we'd like feedback on
internal/feel right for this kind of CLI tool?What this is not
This PR contains no code. It is a design review checkpoint before implementation begins.