Course: Master Course · Deep-Dive: DD-16 · Duration: 60 min · Prerequisites: Modules 0–12, DD-01–15
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.
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.
ZeroClaw is a Cargo workspace, not a monolithic crate. Three layers:
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).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).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.
ZeroClaw's most engineered aspect — and the deepest safety surface in the thin-harness category:
allowed_users, allowed_chats, webhook IP allowlists, enforced at the channel adapter before the runtime sees the event.readonly / supervised (default) / full. Tools are risk-classified: low runs, medium asks operator, high blocks.workspace_only confines reads/writes; forbidden_paths always blocks /etc, /sys, ~/.ssh.allowed_commands (strict allowlist), forbidden_commands, pattern-matcher runs before the shell.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.
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).
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.
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.
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.
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.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.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.
| 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<T,E>; 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.
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.
ZeroClaw's 6-layer safety model is the reference for thin-harness security design. The tool-receipt system (HMAC-SHA256 over tool calls) directly addresses fabricated-tool-claim attacks from Module 11. The outbound leak detector with high-entropy-token heuristic is a credential-exfiltration defense. Caveat: receipts are not yet a chained/durable audit log — keys are ephemeral, persistent storage is future work.
docs/book/src/architecture/overview.md, crates.md, ADR-002 (trait-driven extensibility), ADR-009 (WASM plugins).docs/book/src/security/model.md, autonomy.md.# Deep-Dive DD-16 — ZeroClaw: The Rust Microkernel Harness
**Course**: Master Course · **Deep-Dive**: DD-16 · **Duration**: 60 min · **Prerequisites**: Modules 0–12, DD-01–15
> *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.*
---
## The Subject
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.
## 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.
## 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 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.
## 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.
## 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<T,E>`; 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.*
### MLSecOps Relevance
> *ZeroClaw's 6-layer safety model is the reference for thin-harness security design. The tool-receipt system (HMAC-SHA256 over tool calls) directly addresses fabricated-tool-claim attacks from Module 11. The outbound leak detector with high-entropy-token heuristic is a credential-exfiltration defense. Caveat: receipts are not yet a chained/durable audit log — keys are ephemeral, persistent storage is future work.*
### 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.
---
## 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.