<!-- source: https://deepwiki.com/qhkm/zeptoclaw/1-overview -->

# Overview

- AGENTS.md
- CHANGELOG.md
- CLAUDE.md
- README.md
- deploy/homebrew/zeptoclaw.rb
- landing/zeptoclaw/docs/src/assets/logo.svg
- landing/zeptoclaw/docs/src/styles/custom.css
- landing/zeptoclaw/index.html
- src/cli/common.rs
- src/lib.rs
- src/tools/mod.rs

This document introduces ZeptoClaw's architecture, design philosophy, and core value propositions. It provides a high-level view of the system's components and their interactions, serving as an entry point to the technical documentation.

For installation and setup instructions, see **Getting Started**. For detailed configuration options, see **Configuration**. For security architecture, see **Security**.

## What is ZeptoClaw

ZeptoClaw is a self-hosted AI assistant infrastructure implemented in Rust. It provides a complete agent execution environment in a single ~6MB binary with 50ms startup time and ~6MB RAM usage [README.md34-42](https://github.com/qhkm/zeptoclaw/blob/2c743d31/README.md?plain=1#L34-L42) The system orchestrates LLM interactions, tool execution, multi-channel communication, and security enforcement through a hub-and-spoke architecture centered around the `AgentLoop`, `MessageBus`, and `ChannelManager` [src/lib.rs1-71](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L1-L71)

**Core capabilities:**

- Agent Execution : LLM-powered conversation loop with tool calling, context management, and loop detection src/agent/mod.rs 46-47
- Multi-Channel Gateway : 10 communication channels including Telegram, Slack, Discord, WhatsApp (Web & Cloud), Lark, Email, Webhook, Serial, and MQTT AGENTS.md 15-16
- Tool System : 33 built-in tools, MCP (Model Context Protocol) integration, binary plugins, and natural language composed tools src/tools/mod.rs 1-140
- Security : 9-layer defense-in-depth including prompt injection detection, secret leak scanning, policy engine, and 6 sandbox runtimes README.md 58-69
- Multi-Provider LLM : Support for Anthropic, OpenAI, Gemini, Groq, Ollama, vLLM, OpenRouter, Azure, xAI, NVIDIA, and Zhipu src/lib.rs 58-61

Sources: [README.md1-71](https://github.com/qhkm/zeptoclaw/blob/2c743d31/README.md?plain=1#L1-L71) [src/lib.rs1-101](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L1-L101) [CLAUDE.md1-85](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CLAUDE.md?plain=1#L1-L85) [AGENTS.md1-55](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L1-L55)

## System Architecture Layers

### High-Level Component Interaction

This diagram bridges the conceptual layers to the specific Rust modules and files that implement them.

```

```

**Architecture Characteristics:**

Sources: [src/lib.rs1-101](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L1-L101) [CLAUDE.md52-82](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CLAUDE.md?plain=1#L52-L82) [AGENTS.md24-51](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L24-L51)

## Request Processing Pipeline

This sequence diagram details the lifecycle of a message as it traverses the system, highlighting the "Natural Language" to "Code Entity" transitions.

```

```

**Pipeline Stages:**

1. Ingestion : Channel implementations (e.g., TelegramChannel ) receive platform-specific events and convert them to InboundMessage src/lib.rs 47
2. Routing : The MessageBus routes messages to the appropriate AgentLoop instance src/lib.rs 9
3. Validation : SafetyLayer performs a pre-scan for 21 injection patterns and 22 secret leak patterns README.md 71-72
4. Context Building : ContextBuilder assembles the prompt including system instructions, skills, and memory src/lib.rs 46
5. Execution : ToolRegistry executes requested tools within a ContainerRuntime (Native, Docker, Landlock, etc.) src/lib.rs 62-65
6. Loop Guarding : LoopGuard calculates SHA256 signatures of tool calls to detect and break infinite loops AGENTS.md 46

Sources: [src/lib.rs1-101](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L1-L101) [README.md61-78](https://github.com/qhkm/zeptoclaw/blob/2c743d31/README.md?plain=1#L61-L78) [AGENTS.md27-51](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L27-L51)

## Design Philosophy

ZeptoClaw is built on four core technical pillars:

### 1. Resource Minimalism

ZeptoClaw is designed to run on everything from $10 IoT boards to high-end servers.

- Binary Size : ~6MB via aggressive dependency pruning and Rust's zero-cost abstractions README.md 37
- Memory Footprint : ~6MB base RAM usage, enabling hundreds of concurrent agents on commodity hardware README.md 39
- Startup Latency : ~50ms, critical for serverless or ephemeral container deployments README.md 38

### 2. Defense-in-Depth Security

Unlike frameworks that trust LLM output, ZeptoClaw assumes the LLM may be compromised or manipulated.

- Isolation : Support for 6 runtimes including Landlock, Firejail, and Bubblewrap AGENTS.md 16
- Leak Prevention : Regex-based scanners catch API keys before they are sent to the LLM or returned to the user README.md 72
- Taint Tracking : The TaintEngine monitors data flow from untrusted sources to sensitive sinks src/lib.rs 35

### 3. Resilience and Self-Healing

- Fallback Chains : Automatic provider switching if the primary LLM is down AGENTS.md 21
- Session Repair : Auto-fixes malformed LLM responses, such as orphan tool results or duplicate messages CHANGELOG.md 29
- Channel Supervision : A supervisor polls channels every 15s and restarts failed connections AGENTS.md 27-28

### 4. Extensibility

- Model Context Protocol (MCP) : Native support for external tool servers via HTTP or stdio AGENTS.md 55
- Binary Plugins : JSON-RPC 2.0 interface for tools written in any language src/lib.rs 94
- Natural Language Composition : Users can create new tools by describing them to the agent using the CreateToolTool CHANGELOG.md 61

Sources: [README.md44-71](https://github.com/qhkm/zeptoclaw/blob/2c743d31/README.md?plain=1#L44-L71) [AGENTS.md21-51](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L21-L51) [src/lib.rs1-101](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L1-L101)

## Module Structure

The codebase is organized into functional modules exposed through the library facade:

Sources: [src/lib.rs1-45](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L1-L45) [CLAUDE.md52-82](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CLAUDE.md?plain=1#L52-L82)
