NanoClaw Developer Guide
NanoClaw is a small, container-isolated AI assistant runtime built to be understandable, customizable, and secure by OS-level separation rather than only by application permissions. This guide explains how NanoClaw works, how setup is designed, how its host and container layers cooperate, and where to extend it.
This guide is based on the official NanoClaw docs and the official nanocoai/nanoclaw repository, checked on June 26, 2026.
In this section​
- Setup and first run
- Architecture and runtime
- Configuration and security
- Extending and contributing
- Simple user guide
1. What NanoClaw is​
The shortest accurate description is:
NanoClaw is a small host runtime that runs AI agents in their own containers and keeps the codebase intentionally easy to understand and customize.
The README is unusually explicit about its design stance:
- small enough to understand,
- secure by isolation,
- built for individuals,
- customization through code,
- and skills over bloated built-ins.
2. The mental model​
Think of NanoClaw as five cooperating layers:
| Layer | What it does |
|---|---|
| host process | Routes messages, manages sessions, handles delivery |
| per-agent containers | Isolated execution environments for assistants |
| session storage | Uses SQLite files for inbound and outbound message flow |
| channel and provider registry | Adds messaging channels and model providers on demand |
| user-owned fork and skills | Encourages bespoke customization instead of config sprawl |
3. Why developers would choose it​
- It is built around real container isolation.
- The codebase is deliberately small and auditable.
- It treats customization as code, not as an endless settings UI.
- It supports multi-channel messaging without forcing all features into trunk.
4. What makes it unusual​
NanoClaw's strongest opinion is that the safest extensibility model is:
keep trunk small, install channels and providers via skills, and let users own their fork
That is a very different philosophy from "ship every feature in one monolith."
5. Recommended reading order​
- this overview,
- quick start,
- architecture and isolation model,
- security documentation,
- contribution guidance around skills and branches.