CodeDocs Vault

NanoClaw Architecture Documentation

Deep-dive analysis of NanoClaw's design, patterns, and implementation.

Documents

# Document What it covers
00 Overview Purpose, tech stack, directory structure, system diagram, data flow
01 Entry Points & Execution Startup sequence, message processing pipeline, shutdown, container lifecycle
02 Core Logic Message routing, container management, task scheduling, cursor recovery
03 Key Abstractions Channel interface, GroupQueue, MessageStream, IPC, security patterns, skill system
04 Configuration Environment variables, SQLite state, security files, container-side config
05 Framework Lessons Transferable patterns for building your own agentic framework
06 Landscape Analysis NanoClaw vs OpenClaw, the Claw family, competitor matrix, industry trends

Quick Reference

Host process: src/index.ts — single Node.js process, polls SQLite every 2s for messages

Container agent: container/agent-runner/src/index.ts — reads JSON from stdin, runs Claude Agent SDK, writes sentinel-marked JSON to stdout

Communication: File-based IPC through volume-mounted directories at /workspace/ipc/

Security model: OS-level container isolation + external allowlists + credential proxy (agents never see API keys)

Key Insights for Framework Builders

  1. Container as sandbox — permissionMode: 'bypassPermissions' is safe because the container IS the permission boundary. No need for application-level guardrails when OS isolation handles it.

  2. File-based IPC over networking — Simpler, more debuggable, works with any container runtime. Atomic write-then-rename prevents partial reads.

  3. Push-to-pull message streaming — MessageStream (async iterable) bridges push-based IPC events to the SDK's pull-based consumption model, keeping multi-turn conversations alive without isSingleUserTurn.

  4. Dual-cursor crash recovery — Global cursor for "seen" messages, per-group cursor for "processed" messages, with DB-backed recovery from the last bot reply.

  5. Conditional task wake — Bash scripts run before agent wake, with wakeAgent: false to skip API calls when nothing interesting happened.

  6. Skills as git branches — Features are code transformations, not runtime plugins. No plugin API, no versioning, no dynamic loading.

  7. Context accumulation — Non-trigger messages are stored but not processed. When a trigger arrives, the agent sees the full conversation since its last response.

  8. Credential proxy pattern — OneCLI gateway intercepts HTTPS, injects real keys. Containers see a fake ANTHROPIC_BASE_URL pointing to the gateway. .env is shadowed with /dev/null.

  9. Pre-compact archival — SDK hook archives full conversation transcripts before context compaction, preserving complete history that would otherwise be summarized away.

  10. Idle timeout, not eager shutdown — Containers stay alive after responding, ready for follow-up messages. Only killed after 30 min of inactivity. This avoids cold-start latency for multi-turn conversations.