# Deep-Dive DD-16 — ZeroClaw: The Rust Microkernel Harness **Course**: Master Course · **Deep-Dive**: DD-16 · **Duration**: 60 min · **Level**: Senior Engineer and above **Prerequisites**: Modules 0–12, DD-01–15 (especially DD-07 OpenClaw, DD-17 PicoClaw) > *32,000+ stars. Apache-2.0. Rust single-binary. Trait-driven microkernel with 6-layer safety. 25+ LLM providers. The thin-by-philosophy, medium-by-implementation answer to OpenClaw.* --- ## Learning Objectives After this deep-dive, you will be able to: 1. Explain ZeroClaw's trait-driven kernel architecture (ADR-002) and why it is the cleanest separation of concerns in the roster — adding a provider, channel, or tool is a trait impl wired through a factory, not a core patch. 2. Recite the 6-layer safety model in order — channel access control, autonomy level, workspace boundary, shell policy, OS sandbox, tool receipts — and explain how the layers compose as a cascade rather than a toggle. 3. Analyze the thickness paradox: ZeroClaw is uncompromisingly thin by philosophy (~700–800k LOC, single binary, no telemetry) but medium-thick by implementation, with an active RFC #5574 microkernel refactor closing the gap. 4. Evaluate the tool-receipt system (HMAC-SHA256 over successful tool calls) as a defense against the fabricated-tool-claim attack from Module 11, and name its limitation: ephemeral keys, not yet a durable audit log. 5. Score ZeroClaw against the 12-module rubric (34/60), explain where it wins (Module 6 Permission/Safety: 5/5, the deepest in the thin-harness category) and where it loses (Module 3 Context: 2/5). --- ## The Thesis ZeroClaw (github.com/zeroclaw-labs/zeroclaw) is a Rust-native AI agent runtime — the Rust answer to the Claw family. It is explicitly positioned as the lightweight, provider-agnostic, self-hostable alternative to OpenClaw. Single binary, no telemetry, no SaaS, no license server. The defining architectural decision: **trait-driven extensibility** (ADR-002). The kernel depends only on the `zeroclaw-api` traits — `ModelProvider`, `Channel`, `Tool`, `Memory`, `Observer`, `RuntimeAdapter`, `Peripheral` — never on concrete implementations. Adding a provider, channel, or tool is a trait impl wired through a factory, not a core patch. This is the cleanest separation of concerns in the roster. The deep-dive's load-bearing claim: **ZeroClaw's 6-layer safety model is the reference architecture for thin-harness security, and its tool-receipt system is the only harness that directly addresses the fabricated-tool-claim attack (Module 11) at the protocol layer.** The trait-driven kernel is what makes the 25+ provider slots possible without core bloat. The honest tension: thin by philosophy, medium-thick by implementation, with an active refactor closing the gap. --- ## Architecture — Layered Rust Workspace ZeroClaw is a Cargo workspace, not a monolithic crate. Three layers: - **Core**: `zeroclaw-runtime` (agent loop, security-policy enforcement, SOP engine, cron scheduler, SubAgent lifecycle), `zeroclaw-config` (TOML schema + encrypted secrets + autonomy levels), `zeroclaw-api` (the kernel ABI — public traits). - **Edge**: `zeroclaw-providers` (25+ LLM clients with routing/retry), `zeroclaw-channels` (30+ messaging integrations), `zeroclaw-gateway` (REST/WebSocket/dashboard/webhook), `zeroclaw-tools` (browser, HTTP, hardware probes). - **Support**: `zeroclaw-memory`, `zeroclaw-plugins` (WASM), `zeroclaw-hardware` (GPIO/I2C/SPI/USB), `zeroclaw-log`. The agent loop: `Channel → Runtime.deliver_message → Provider.chat (stream) → Security.validate(tool_call) → Tool.invoke → result back to Provider → reply to Channel`. Security runs between the model emitting a tool call and the tool executing — a block surfaces as a `ToolResult::Err` the model can react to. **Active refactor**: RFC #5574 ("microkernel roadmap") is shrinking `zeroclaw-runtime` so the kernel is just loop + policy, with everything else behind feature flags. The foundation reportedly builds with `--no-default-features`. --- ## The 6-Layer Safety Model ZeroClaw's most engineered aspect — and the deepest safety surface in the thin-harness category: 1. **Channel pairing / access control** — `allowed_users`, `allowed_chats`, webhook IP allowlists, enforced at the channel adapter before the runtime sees the event. 2. **Autonomy level** — `readonly` / `supervised` (default) / `full`. Tools are risk-classified: low runs, medium asks operator, high blocks. 3. **Workspace boundary + path rules** — `workspace_only` confines reads/writes; `forbidden_paths` always blocks `/etc`, `/sys`, `~/.ssh`. 4. **Shell command policy** — `allowed_commands` (strict allowlist), `forbidden_commands`, pattern-matcher runs *before* the shell. 5. **OS-level sandbox** — auto-detected: Landlock/Bubblewrap/Firejail/Docker on Linux, Seatbelt on macOS, AppContainer on Windows. 6. **Tool receipts** — HMAC-SHA256 over successful tool calls + results, fed back into conversation to detect fabricated tool claims. Extra gates: OTP gating per action, emergency stop (`zeroclaw estop`), prompt-injection guard, outbound leak detector with high-entropy-token heuristic, device pairing guard. Approval routing can redirect to a separate "approver channel" with fail-closed semantics. This is Module 6's risk-tiering principle taken to its logical conclusion: not one gate, a cascade. Each layer is independently defeatable, but the default ships all six on. --- ## Provider Agnosticism — 25+ Slots The README's "20+ providers" is understated. Verified provider files: `anthropic`, `openai`, `openai_codex`, `ollama`, `bedrock`, `gemini`, `gemini_cli`, `azure_openai`, `copilot`, `telnyx`, `kilocli`, `glm`, plus a `compatible.rs` OpenAI-compatible shim reused by 20+ vendors (Groq, Mistral, xAI, Venice, OpenRouter, Morph, GitHub Models, and more). Auth handling is per-vendor with dedicated OAuth modules. A `reliable.rs` wrapper provides retry/backoff/API-key rotation. A `router.rs` enables per-call model routing (reasoning on one model, cheap chat on another). The trait-driven kernel is what makes this possible: each provider is a `ModelProvider` trait impl, wired through the factory. No core bloat, no provider-specific code in the kernel. --- ## The Minimal-Prompt Philosophy From `philosophy/minimal.md`: *"There are no hidden system prompts injecting personality. The model sees what you configure."* Tool descriptions are Fluent-localized (projectfluent.org) and deliberately terse. This is a sharp contrast to opinionated harnesses that ship multi-thousand-token hidden prompts. The system-prompt footprint is intentionally minimal and operator-owned. This places responsibility for prompt behavior on the operator, where ZeroClaw's philosophy says it belongs. The tradeoff: power and transparency in exchange for more operator burden — there is no hidden prompt doing the work for you. --- ## Memory Architecture Multi-surface, with a critical design rule: **prompt context, tool output, files, and logs are NOT durable memory by default.** A turn only becomes memory if the agent calls `memory_store` explicitly. Long-term memory backends: SQLite (default), PostgreSQL (multi-instance), Qdrant/Lucid (vector), per-agent Markdown files. There's a separate **knowledge graph** tool for relationship memory (capture is explicit, not automatic). Memory consolidation via summaries and fact extraction. This is the opposite of Hermes's model-initiated-free-writes design (DD-08) — ZeroClaw trades compounding capability for a smaller poisoning surface. Explicit-only memory is a security choice: the agent cannot write to durable memory without an explicit tool call, which means an indirect injection cannot silently persist itself. --- ## The Thickness Reality **Stated intent: thin harness. Reality: medium-thick.** The philosophy is uncompromisingly thin — single binary, no telemetry, no SaaS, no hidden prompts. But the as-built artifact is ~700-800k Rust LOC across 1,015 files, ~26 MiB binary. The config schema alone is 1.3 MB of Rust. The hardware/GPIO/SPI/USB support is thickness most thin harnesses don't carry. RFC #5574 is actively closing the gap by factoring functionality behind feature flags. **Honest framing: thin by design and default-surface, currently medium-sized in implementation, with an in-flight refactor to re-thin.** --- ## Key Design Decisions 1. **Trait-driven kernel (ADR-002).** The kernel depends only on `zeroclaw-api` traits — never on concrete implementations. Adding a provider, channel, or tool is a trait impl wired through a factory, not a core patch. This is the cleanest separation of concerns in the roster and the property that makes the 25+ provider slots possible without core bloat. 2. **6-layer safety as a stack, not a toggle.** The layers compose: channel access control, autonomy level, workspace boundary, shell policy, OS sandbox, tool receipts. Each layer is independently defeatable but the default ships all six on. This is Module 6's risk-tiering principle taken to its logical conclusion — not one gate, a cascade. 3. **Minimal-prompt philosophy.** No hidden system prompts. The model sees what the operator configures. This is a sharp, deliberate contrast to opinionated harnesses that ship multi-thousand-token hidden prompts — and it places the responsibility for prompt behavior on the operator, where ZeroClaw's philosophy says it belongs. 4. **Explicit-only memory.** Prompt context, tool output, files, and logs are NOT durable memory by default. A turn becomes memory only if the agent calls `memory_store` explicitly. This is the opposite of Hermes's model-initiated-free-writes design (DD-08) — ZeroClaw trades compounding capability for a smaller poisoning surface. --- ## Phase 4 — Security Audit **Credential flow**: encrypted secrets in `zeroclaw-config`, decrypted at runtime, never logged. The outbound leak detector with high-entropy-token heuristic is a credential-exfiltration defense — it catches secrets on the way out, which most harnesses never check. **Tool receipts**: HMAC-SHA256 over successful tool calls + results, fed back into conversation. This directly addresses the fabricated-tool-claim attack (Module 11) — the model cannot credibly claim a tool returned data it did not, because the receipt is in-context evidence. Caveat noted in the verdict: receipts use ephemeral keys, so they are not yet a chained/durable audit log. **Shell policy**: strict allowlist (`allowed_commands`) runs *before* the shell, not after. This is the correct layer for shell injection defense — block at the policy gate, not detect at the audit log. --- ## Score: 34/60 | Module | Score | Key decision | | --- | --- | --- | | 1 Loop | 3 | standard Rust loop; no GC overhead | | 2 Tools | 4 | browser, HTTP, hardware probes; trait-extended | | 3 Context | 2 | basic history trimming only; no context-budget system | | 4 Memory | 3 | explicit-only writes; SQLite/Postgres/Qdrant backends | | 5 Sandbox | 4 | auto-detected OS sandbox (Landlock/Seatbelt/AppContainer/Docker) | | 6 Permission/Safety | 5 | 6-layer model (deepest in thin-harness category) | | 7 Errors | 4 | Rust `Result`; tool receipts as structured results | | 8 State | 3 | standard session state | | 9 Verification | 2 | limited | | 10 Subagents | 3 | SubAgent lifecycle in runtime | | 11 Observability | 3 | `zeroclaw-log`; tool receipts as audit signal | | 12 Prompt | 4 | minimal-prompt philosophy; operator-owned | | **TOTAL** | **34/60** | | ZeroClaw scores highest on Module 6 (Permission/Safety): 5/5. The 6-layer safety model is the deepest in the thin-harness category. It scores well on Module 5 (Sandboxing): 4/5 for auto-detecting OS-level sandboxes. It loses on Module 3 (Context Management): 2/5 — no sophisticated context-budget system, just basic history trimming. ### Architect's Verdict > *ZeroClaw optimizes for engineering discipline: trait-driven extensibility, no hidden prompts, 6-layer safety, and a philosophy of operator ownership. It is thin by intent but medium-thick by implementation (~700k LOC), with an active microkernel refactor closing the gap. Build on ZeroClaw when Rust-native safety, provider agnosticism, and self-hosting are requirements; the trait-driven kernel makes it the most extensible thin harness for custom tool/channel development.* ### 3 things ZeroClaw does better 1. **Trait-driven kernel**: the cleanest separation of concerns. Adding anything is a trait impl, not a core patch. 2. **6-layer safety**: deepest safety surface in the thin-harness category. Auto-detects OS sandbox, shell allowlisting, tool receipts. 3. **Provider agnosticism**: 25+ provider slots with routing, retry, key rotation, and per-vendor OAuth. No other harness matches this breadth. ### 3 things to fix 1. **Close the microkernel gap**: ~700k LOC contradicts the thin philosophy. RFC #5574 is the right direction; finish it. 2. **Durable audit log**: tool receipts use ephemeral keys. Make them chained, cross-signed, and persistent. 3. **Context management**: basic history trimming is insufficient. Add turn-boundary trimming (like PicoClaw's) and a context-budget system. --- ## Anti-Patterns ### "Thin harness means small codebase" ZeroClaw is uncompromisingly thin by philosophy but medium-thick by implementation: ~700–800k Rust LOC across 1,015 files. The hardware/GPIO/SPI/USB support and 25+ provider slots are thickness most thin harnesses don't carry. Cure: read "thin" as a design intent (single binary, no telemetry, no SaaS, no hidden prompts), not a LOC count. RFC #5574 is closing the gap. ### "Tool receipts are a complete audit log" The tool-receipt system (HMAC-SHA256 over successful tool calls) addresses the fabricated-tool-claim attack, but it uses ephemeral keys. It is not yet a chained, cross-signed, durable audit log. Cure: treat receipts as an in-context integrity signal today, and implement the durable audit log (fix #2) before relying on them for post-hoc forensics. ### "Explicit-only memory is just a limitation" ZeroClaw's explicit-only memory is a deliberate security choice, not a missing feature. The agent cannot write to durable memory without an explicit `memory_store` call, which means an indirect injection cannot silently persist itself. Cure: read it as the opposite of Hermes's model-initiated-free-writes (DD-08) — ZeroClaw trades compounding capability for a smaller poisoning surface. The trade is intentional. --- ## Key Terms | Term | Definition | | --- | --- | | **Trait-driven kernel (ADR-002)** | The kernel depends only on `zeroclaw-api` traits, never on concrete implementations; adding anything is a trait impl wired through a factory | | **6-layer safety model** | Channel access control, autonomy level, workspace boundary, shell policy, OS sandbox, tool receipts — composed as a cascade, not a toggle | | **Tool receipts** | HMAC-SHA256 over successful tool calls + results, fed back into conversation to detect fabricated-tool-claim attacks (Module 11); caveat: ephemeral keys, not yet durable | | **Minimal-prompt philosophy** | No hidden system prompts; the model sees what the operator configures — responsibility for prompt behavior on the operator | | **Explicit-only memory** | Prompt context, tool output, files, and logs are NOT durable memory by default; a turn becomes memory only via an explicit `memory_store` call | | **Thickness paradox** | Thin by philosophy (single binary, no telemetry, no SaaS) but medium-thick by implementation (~700k LOC); RFC #5574 closing the gap | --- ## Lab Exercise See `07-lab-spec.md`. You build a minimal simulation of ZeroClaw's 6-layer safety cascade in Python: model each layer as a gate function, send a sequence of tool calls through the cascade, and confirm which calls are blocked at which layer. Then implement the tool-receipt system (HMAC over tool calls) and confirm it detects a fabricated tool claim. --- ## References 1. **ZeroClaw source** — github.com/zeroclaw-labs/zeroclaw (Apache-2.0, ~32k stars, v0.8.2). 2. **Architecture docs** — `docs/book/src/architecture/overview.md`, `crates.md`, ADR-002 (trait-driven extensibility), ADR-009 (WASM plugins). 3. **Security docs** — `docs/book/src/security/model.md`, `autonomy.md`. 4. **Module 5** — sandboxing; OS-level sandbox auto-detection. 5. **Module 6** — permission/safety; the 6-layer model as reference architecture. 6. **Module 11** — security; tool receipts vs. fabricated-tool-claim attacks; leak detector. 7. **DD-07 (OpenClaw)** — the heavyweight Claw flagship ZeroClaw positions against. 8. **DD-17 (PicoClaw)** — the Go thin-harness cousin.