# sorretai/zeroclaw architecture

> Architecture diagram of the GitHub repository sorretai/zeroclaw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sorretai/zeroclaw
- Repository: https://github.com/sorretai/zeroclaw

## Overview

1. **Overall shape**
   - ZeroClaw is a Rust workspace centered on an agent runtime, with multiple front doors and back-end adapters. The core execution path is: inbound event or user request → runtime orchestration → model/provider call and tool execution → response back to the originating channel/client.

2. **Core runtime boundary**
   - `crates/zeroclaw-runtime` is the main orchestrator. It owns agent turns, approval gates, tool execution, history management, hooks, cron, SOP execution, health, daemon/control-plane concerns, and runtime observability.
   - This is the subsystem where “what happens next” is decided once a request enters the system.

3. **Ingress surfaces**
   - Requests can enter through multiple adapters: `crates/zeroclaw-channels` for external messaging systems, `crates/zeroclaw-gateway` for HTTP/WebSocket/API clients, and ACP/JSON-RPC over stdio for editor/IDE integrations.
   - The Tauri app (`apps/tauri`) and TUI/CLI app (`apps/zerocode`) are local user interfaces that talk to the runtime/gateway rather than implementing agent logic themselves.

4. **Model/provider layer**
   - `crates/zeroclaw-providers` abstracts LLM backends such as Anthropic, OpenAI, Ollama, Gemini, Bedrock, and other compatible/routed providers.
   - This layer includes auth, model dispatch, routing/fallback, and stream guards, so provider selection is a policy and configuration concern rather than hard-coded into the agent loop.

5. **Tooling layer**
   - `crates/zeroclaw-tools` is the first-party tool catalog: browser, shell, file ops, HTTP, search, MCP, memory operations, hardware tools, integrations, and specialized workflow tools.
   - Tools are invoked from the runtime during a turn, and the results are fed back into the agent history or approval/security flow.

6. **Memory and retrieval**
   - `crates/zeroclaw-memory` manages durable memory, embeddings, retrieval, response caching, consolidation, and knowledge graphs.
   - It supports multiple storage backends, including SQLite, Postgres, Qdrant, and “none,” making memory a pluggable subsystem rather than a single database.

7. **Configuration and policy**
   - `crates/zeroclaw-config` defines the config schema, migrations, env overrides, provider aliases, presets, secrets, and validation.
   - The configuration layer is tightly coupled to policy: it determines agent identities, provider bindings, channel setup, autonomy/risk profiles, and platform-specific behavior.

8. **Security and trust boundaries**
   - Security is a first-class subsystem in the runtime, with sandboxing, prompt guarding, leak detection, IAM/policy checks, approval flows, and verifiable intent support.
   - Tool execution is therefore not “direct”; it is mediated by policy, approvals, and receipts, especially for risky actions like shell or filesystem operations.

9. **Gateway and dashboard**
   - `crates/zeroclaw-gateway` exposes the operational API surface: REST, WebSocket, SSE, static files, pairing/auth, logs, config, skills, plugins, quickstart, and related admin endpoints.
   - The React/Vite web app in `web/` is the dashboard client for that gateway, used for chat, config editing, agents, cron, memory browsing, tools, and system status.

10. **Channels and event orchestration**
   - `crates/zeroclaw-channels` is a large adapter collection for messaging and voice surfaces such as Discord, Slack, Telegram, Matrix, email, WhatsApp, webhooks, and more.
   - It also includes orchestration pieces like media pipelines, transcription, TTS, wake/voice handling, and protocol-specific approval or allowlist logic. These channels are the main long-lived ingress/egress integration layer.

11. **Hardware and edge devices**
   - `crates/zeroclaw-hardware` plus the `firmware/` tree represent the hardware subsystem: board discovery, transport, serial/UF2 flashing, peripheral registry, and board-specific tools.
   - This subsystem extends the agent beyond software APIs into physical peripherals and embedded devices, with separate firmware packages for boards like ESP32, Pico, Nucleo, and UNO Q bridges.

12. **Plugins, skills, and extension points**
   - `crates/zeroclaw-plugins` provides a WASM plugin runtime for extensibility.
   - `crates/zeroclaw-runtime/src/skills` and related skill crates manage skill discovery, bundling, review, scaffolding, and execution; skills are treated as a structured extension mechanism distinct from ad hoc prompts or tools.

13. **Operational subsystems**
   - The runtime also contains control-plane, daemon, heartbeat, cron, hooks, tunnel, observability, and SOP engines.
   - These subsystems handle always-on operation, scheduled tasks, event-driven procedures, network exposure, tracing/logging/metrics, and background reliability behaviors.

14. **Repo structure and delivery**
   - The workspace is split into focused crates for major boundaries, plus app frontends, docs, packaging, and deployment assets.
   - CI/CD, Docker/Containerfile variants, Nix, k8s manifests, and release packaging live alongside the code, reflecting that ZeroClaw is intended to run locally, as a service, or in containerized deployments rather than as a single binary only.

Main entry points: [`crates/zeroclaw-runtime`](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-runtime) (Runtime), [`crates/zeroclaw-runtime/src/agent/turn`](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-runtime/src/agent/turn) (Turn engine), [`crates/zeroclaw-gateway`](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-gateway) (Gateway), [`crates/zeroclaw-runtime/src/rpc`](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-runtime/src/rpc) (RPC layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
end

subgraph group_interfaces["Interfaces"]
  node_apps_zerocode["Zerocode<br/>tui/cli app"]
  node_apps_tauri["Tauri app<br/>desktop/mobile app"]
  node_web_dashboard["Web dashboard<br/>react/vite client"]
  node_gateway["Gateway<br/>HTTP/WebSocket API"]
  node_channels["Channels<br/>messaging adapters"]
end

subgraph group_core["Core runtime"]
  node_runtime["Runtime<br/>agent orchestrator"]
  node_runtime_turn["Turn engine<br/>turn lifecycle"]
  node_runtime_security{{"Security<br/>policy/sandbox"}}
  node_runtime_control["Control plane<br/>daemon/task mgmt"]
  node_runtime_rpc["RPC layer<br/>local transport"]
  node_providers["Providers<br/>model backends"]
  node_memory[("Memory<br/>durable retrieval")]
  node_config["Config<br/>schema/policy"]
  node_observability["Observability<br/>logs/metrics/traces"]
end

subgraph group_extensions["Extensions"]
  node_runtime_skills["Skills<br/>skill system"]
  node_plugins["Plugins<br/>wasm runtime"]
  node_tools["Tools<br/>tool catalog"]
end

subgraph group_ops["Ops & delivery"]
  node_hardware["Hardware<br/>device subsystem"]
  node_firmware["Firmware<br/>embedded targets"]
  node_docs["Docs<br/>documentation"]
  node_release["Delivery<br/>build/deploy"]
end

node_apps_zerocode -->|"ACP/JSON-RPC"| node_runtime_rpc
node_apps_tauri -->|"UI API"| node_gateway
node_web_dashboard -->|"browser API"| node_gateway
node_channels -->|"ingress events"| node_runtime
node_gateway -->|"session bridge"| node_runtime_rpc
node_runtime_rpc -->|"turn requests"| node_runtime
node_runtime -->|"orchestrates"| node_runtime_turn
node_runtime_turn -->|"model calls"| node_providers
node_runtime_turn -->|"tool use"| node_tools
node_runtime_turn -->|"retrieve/store"| node_memory
node_runtime_turn -->|"gated by"| node_runtime_security
node_runtime -->|"policy input"| node_config
node_runtime -->|"events"| node_observability
node_runtime -->|"daemon ops"| node_runtime_control
node_runtime -->|"skills"| node_runtime_skills
node_runtime_skills -->|"extends via"| node_plugins
node_tools -->|"device ops"| node_hardware
node_hardware -->|"targets"| node_firmware
node_docs -.->|"documents"| node_config
node_release -.->|"ships"| node_gateway

click node_apps_zerocode "https://github.com/sorretai/zeroclaw/tree/master/apps/zerocode"
click node_apps_tauri "https://github.com/sorretai/zeroclaw/tree/master/apps/tauri"
click node_web_dashboard "https://github.com/sorretai/zeroclaw/tree/master/web"
click node_gateway "https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-gateway"
click node_channels "https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-channels"
click node_runtime "https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-runtime"
click node_runtime_turn "https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-runtime/src/agent/turn"
click node_runtime_security "https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-runtime/src/security"
click node_runtime_control "https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-runtime/src/control_plane"
click node_runtime_rpc "https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-runtime/src/rpc"
click node_runtime_skills "https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-runtime/src/skills"
click node_plugins "https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-plugins"
click node_providers "https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-providers"
click node_tools "https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-tools"
click node_memory "https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-memory"
click node_config "https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-config"
click node_observability "https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-log"
click node_hardware "https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-hardware"
click node_firmware "https://github.com/sorretai/zeroclaw/tree/master/firmware"
click node_docs "https://github.com/sorretai/zeroclaw/tree/master/docs"
click node_release "https://github.com/sorretai/zeroclaw/tree/master/dist"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_apps_zerocode,node_apps_tauri,node_web_dashboard,node_gateway,node_channels toneAmber
class node_runtime,node_runtime_turn,node_runtime_security,node_runtime_control,node_runtime_rpc,node_providers,node_memory,node_config,node_observability toneMint
class node_runtime_skills,node_plugins,node_tools toneRose
class node_hardware,node_firmware,node_docs,node_release toneIndigo
```

## Components

### Interfaces

User-facing clients and ingress surfaces

- [Zerocode](https://github.com/sorretai/zeroclaw/tree/master/apps/zerocode): tui/cli app · Local terminal UI and ACP/JSON-RPC client for the runtime · `apps/zerocode`
- [Tauri app](https://github.com/sorretai/zeroclaw/tree/master/apps/tauri): desktop/mobile app · Local GUI that talks to gateway and runtime services · `apps/tauri`
- [Web dashboard](https://github.com/sorretai/zeroclaw/tree/master/web): react/vite client · Browser UI for chat, config, tools, logs, and agent management · `web`
- [Gateway](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-gateway): HTTP/WebSocket API · REST, WS, SSE, static files, pairing, auth, and admin endpoints · `crates/zeroclaw-gateway`
- [Channels](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-channels): messaging adapters · Messaging, webhook, and voice ingress/egress adapters · `crates/zeroclaw-channels`

### Core runtime

Agent execution, policy, memory, and orchestration

- [Runtime](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-runtime): agent orchestrator · Main turn engine that coordinates requests, tools, approvals, and responses · `crates/zeroclaw-runtime`
- [Turn engine](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-runtime/src/agent/turn): turn lifecycle · Call prep, provider call, stream handling, parsing, and post-execution · `crates/zeroclaw-runtime/src/agent/turn`
- [Security](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-runtime/src/security): policy/sandbox · Approvals, sandboxing, prompt guards, leak detection, and intent verification · `crates/zeroclaw-runtime/src/security`
- [Control plane](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-runtime/src/control_plane): daemon/task mgmt · Daemon boot, task registry, watchdogs, heartbeats, and lifecycle control · `crates/zeroclaw-runtime/src/control_plane`
- [RPC layer](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-runtime/src/rpc): local transport · ACP, session, websocket, local transport, and editor/client bridge · `crates/zeroclaw-runtime/src/rpc`
- [Providers](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-providers): model backends · LLM abstraction with auth, routing, dispatch, and stream guards · `crates/zeroclaw-providers`
- [Memory](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-memory): durable retrieval · Embeddings, caching, consolidation, retrieval, and knowledge graph storage · `crates/zeroclaw-memory`
- [Config](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-config): schema/policy · Configuration schema, env overrides, presets, provider aliases, and validation · `crates/zeroclaw-config`
- [Observability](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-log): logs/metrics/traces · Structured logging, tracing, metrics, and runtime event broadcasting · `crates/zeroclaw-log`

### Extensions

Skills, plugins, and tool catalogs

- [Skills](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-runtime/src/skills): skill system · Skill discovery, bundling, review, scaffolding, and execution support · `crates/zeroclaw-runtime/src/skills`
- [Plugins](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-plugins): wasm runtime · WASM-based plugin host for tool and channel extensions · `crates/zeroclaw-plugins`
- [Tools](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-tools): tool catalog · First-party tools for shell, browser, file, search, memory, MCP, and integrations · `crates/zeroclaw-tools`

### Ops & delivery

Packaging, docs, deployment, and firmware

- [Hardware](https://github.com/sorretai/zeroclaw/tree/master/crates/zeroclaw-hardware): device subsystem · Discovery, transport, peripherals, flashing, and board tooling · `crates/zeroclaw-hardware`
- [Firmware](https://github.com/sorretai/zeroclaw/tree/master/firmware): embedded targets · Board-specific firmware and bridge packages for physical devices · `firmware`
- [Docs](https://github.com/sorretai/zeroclaw/tree/master/docs): documentation · Architecture, API, setup, channels, security, tools, and operations docs · `docs`
- [Delivery](https://github.com/sorretai/zeroclaw/tree/master/dist): build/deploy · Docker, Nix, k8s, packaging, CI, and release automation assets · `dist`

## Connections

- Zerocode → RPC layer: ACP/JSON-RPC · Local terminal UI connects through runtime RPC and session transport
- Tauri app → Gateway: UI API · Desktop/mobile UI uses the gateway for operational actions and status
- Web dashboard → Gateway: browser API · Web dashboard consumes the gateway's REST, SSE, and WebSocket APIs
- Channels → Runtime: ingress events · External messages are normalized and handed to the runtime for turns
- Gateway → RPC layer: session bridge · Gateway mediates client sessions and forwards work into runtime RPC
- RPC layer → Runtime: turn requests · RPC layer submits conversations, approvals, and control actions to runtime
- Runtime → Turn engine: orchestrates · Main agent execution path is implemented by the turn lifecycle
- Turn engine → Providers: model calls · Turns call out to model providers for generation and streaming
- Turn engine → Tools: tool use · Turns request tools, then collect and feed results back into history
- Turn engine → Memory: retrieve/store · Turns consult durable memory and persist relevant state
- Turn engine → Security: gated by · Tool execution and risky actions pass through policy and approval checks
- Runtime → Config: policy input · Configuration shapes identities, providers, channels, autonomy, and risk
- Runtime → Observability: events · Runtime emits logs, traces, metrics, and broadcast events
- Runtime → Control plane: daemon ops · Background control-plane functions manage tasks, heartbeats, and boot
- Runtime → Skills: skills · Runtime loads and executes structured skills as a separate extension path
- Skills → Plugins: extends via · Skills and tool extensions can be packaged through the plugin runtime
- Tools → Hardware: device ops · Some tools surface board discovery, flashing, and peripheral access
- Hardware → Firmware: targets · Hardware subsystem manages board-specific firmware packages and bridges
- Docs → Config: documents · Docs describe configuration, deployment, runtime, and security behavior
- Delivery → Gateway: ships · Packaging and deployment artifacts deliver the service and dashboard surfaces