> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nullclaw/nullclaw/llms.txt
> Use this file to discover all available pages before exploring further.
# Architecture
> NullClaw's vtable-driven pluggable architecture
## Overview
NullClaw is built on a **vtable-driven pluggable architecture** where every subsystem implements a common interface pattern. This design enables zero-overhead abstraction with full runtime swappability — change any component via configuration, no code changes required.
```
678 KB binary · <2 ms startup · 3,230+ tests · 22+ providers · 18 channels · Pluggable everything
```
## Core Design Principles
### 1. Vtable Interface System
Every subsystem uses Zig's type-erased interface pattern (vtable-based polymorphism):
```zig theme={null}
pub const Provider = struct {
ptr: *anyopaque,
vtable: *const VTable,
pub const VTable = struct {
chatWithSystem: *const fn(...) anyerror![]const u8,
chat: *const fn(...) anyerror!ChatResponse,
supportsNativeTools: *const fn(...) bool,
getName: *const fn(...) []const u8,
deinit: *const fn(...) void,
// Optional methods...
};
};
```
This pattern provides:
* **Zero runtime overhead**: Direct function pointers, no dynamic dispatch
* **Compile-time safety**: Type checking at build time
* **Runtime flexibility**: Swap implementations via config
* **No allocator overhead**: Static vtables, minimal indirection
### 2. No Dependencies
NullClaw depends only on:
* `libc` (standard C library)
* `sqlite` (optional, for memory backends)
No VM, no runtime, no framework. The entire binary is **678 KB** in release mode.
### 3. Static Binary
The entire runtime compiles to a single static binary:
* Boots in **\<2 ms** on Apple Silicon
* Runs on **\$5 hardware** (any ARM/x86/RISC-V board)
* Deploys with `scp` — no installation, no package manager
## Subsystem Table
Every subsystem implements a vtable interface:
| Subsystem | Interface | Ships With | Extend |
| ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| **AI Models** | `Provider` | 22+ providers (OpenRouter, Anthropic, OpenAI, Ollama, Venice, Groq, Mistral, xAI, DeepSeek, Together, Fireworks, Perplexity, Cohere, Bedrock, etc.) | `custom:https://your-api.com` — any OpenAI-compatible API |
| **Channels** | `Channel` | CLI, Telegram, Signal, Discord, Slack, iMessage, Matrix, WhatsApp, Webhook, IRC, Lark/Feishu, OneBot, Line, DingTalk, Email, Nostr, QQ, MaixCam, Mattermost | Any messaging API |
| **Memory** | `Memory` | SQLite (hybrid FTS5 + vector cosine similarity), Markdown | Any persistence backend |
| **Tools** | `Tool` | shell, file\_read, file\_write, file\_edit, memory\_store, memory\_recall, memory\_forget, browser\_open, screenshot, composio, http\_request, hardware\_info, hardware\_memory, and more | Any capability |
| **Observability** | `Observer` | Noop, Log, File, Multi | Prometheus, OTel |
| **Runtime** | `RuntimeAdapter` | Native, Docker (sandboxed), WASM (wasmtime) | Any runtime |
| **Security** | `Sandbox` | Landlock, Firejail, Bubblewrap, Docker, auto-detect | Any sandbox backend |
| **Identity** | `IdentityConfig` | OpenClaw (markdown), AIEOS v1.1 (JSON) | Any identity format |
| **Tunnel** | `Tunnel` | None, Cloudflare, Tailscale, ngrok, Custom | Any tunnel binary |
| **Heartbeat** | Engine | HEARTBEAT.md periodic tasks | — |
| **Skills** | Loader | TOML manifests + SKILL.md instructions | Community skill packs |
| **Peripherals** | `Peripheral` | Serial, Arduino, Raspberry Pi GPIO, STM32/Nucleo | Any hardware interface |
| **Cron** | Scheduler | Cron expressions + one-shot timers with JSON persistence | — |
## Data Flow
```mermaid theme={null}
flowchart TD
User[User Input] --> Channel[Channel vtable]
Channel --> Gateway[Gateway/Daemon]
Gateway --> Agent[Agent Loop]
Agent --> Provider[Provider vtable]
Provider --> LLM[LLM API]
LLM --> Response[Response]
Response --> Tools{Tool Calls?}
Tools -->|Yes| Tool[Tool vtable]
Tool --> Execute[Execute]
Execute --> Memory[Memory vtable]
Memory --> Agent
Tools -->|No| Channel
Agent --> Observer[Observer vtable]
Observer --> Audit[Audit Log]
```
### Message Flow (Channel → Agent)
1. **Channel receives message** (Telegram webhook, Discord WebSocket, CLI stdin, etc.)
2. **Channel vtable** normalizes to `ChannelMessage` struct
3. **Gateway/Daemon** routes to agent session
4. **Agent loop** appends to conversation context
5. **Provider vtable** sends to LLM API
6. **Response parsing** extracts text/tool calls
7. **Tool dispatch** executes via `Tool` vtable
8. **Memory storage** persists via `Memory` vtable
9. **Outbound delivery** via `Channel.send()`
### Security Layers
Every request passes through:
1. **Pairing check** (gateway authentication)
2. **Channel allowlist** (sender validation)
3. **Workspace scoping** (filesystem boundaries)
4. **Sandbox isolation** (OS-level containment)
5. **Audit logging** (signed event trail)
All subsystems are **fail-safe by default**: deny-by-default access, explicit opt-in for elevated permissions, structured error propagation.
## Extension Points
### Adding a New Provider
```zig theme={null}
const MyProvider = struct {
api_key: []const u8,
pub fn chatWithSystem(
ptr: *anyopaque,
allocator: std.mem.Allocator,
system_prompt: ?[]const u8,
message: []const u8,
model: []const u8,
temperature: f64,
) anyerror![]const u8 {
const self: *MyProvider = @ptrCast(@alignCast(ptr));
// Implementation...
}
pub fn provider(self: *MyProvider) Provider {
return .{ .ptr = @ptrCast(self), .vtable = &vtable };
}
pub const vtable = Provider.VTable{
.chatWithSystem = chatWithSystem,
.chat = chat,
.supportsNativeTools = supportsNativeTools,
.getName = getName,
.deinit = deinit,
};
};
```
### Adding a New Channel
```zig theme={null}
const MyChannel = struct {
config: Config,
pub fn start(ptr: *anyopaque) anyerror!void {
const self: *MyChannel = @ptrCast(@alignCast(ptr));
// Start listening...
}
pub fn send(
ptr: *anyopaque,
target: []const u8,
message: []const u8,
media: []const []const u8,
) anyerror!void {
const self: *MyChannel = @ptrCast(@alignCast(ptr));
// Send message...
}
pub fn channel(self: *MyChannel) Channel {
return .{ .ptr = @ptrCast(self), .vtable = &vtable };
}
pub const vtable = Channel.VTable{
.start = start,
.stop = stop,
.send = send,
.name = name,
.healthCheck = healthCheck,
};
};
```
## Performance Characteristics
| Metric | Value | Why |
| --------------------- | ------------ | -------------------------------------------- |
| **Binary Size** | 678 KB | Zero dependencies, Zig comptime optimization |
| **Startup Time** | \<2 ms | No runtime init, static binary |
| **Memory Usage** | \~1 MB | No GC, explicit allocations |
| **Test Coverage** | 3,230+ tests | Comprehensive subsystem validation |
| **Dispatch Overhead** | \~0 ns | Direct function pointers |
NullClaw's vtable pattern has **zero runtime overhead** compared to direct function calls — the vtable is resolved at init time, then all calls are direct jumps.
## Next Steps
Learn about AI model provider integration
Explore messaging platform channels
Understand tool execution system
Deep dive into memory backends