Nanoclaw architecture

What is Nanoclaw?

NanoClaw is a personal AI assistant that runs agents in containers. It was written as a deliberately small alternative to larger self-hosted assistants: one host process and a handful of files, with isolation enforced at the container boundary rather than by application-level permission checks.

That makes its architecture the feature rather than an implementation detail. What runs in the host process versus inside an agent container? Where does state live, and what crosses the boundary between the two? How do chat channels plug in, and what does a skill get access to once it runs? If you are going to give an assistant access to your life, these are the questions worth answering first.

The map on this page is JigsawML's read of the NanoClaw repository. It groups the code into the twelve areas below, shows where the host ends and the container begins, and lets you open any area to see the code.

Key components in the Nanoclaw architecture

JigsawML identified and labelled these components automatically by analysing the Nanoclaw repository. Open the interactive map to expand any of them and read the underlying code.

• Host Process

  The single long-running process that receives messages and supervises agents.

• Central DB

  The shared store holding conversation state and configuration.

• Admin CLI

  Command-line administration for pairing channels and managing agents.

• Channel Provider

  The connectors that terminate each chat platform's protocol.

• Host Feature

  Optional modules that extend the host without changing its core.

• Agent Container

  The isolated Linux container an agent actually executes inside.

• Setup Wizard

  The guided installer taking a fresh machine to a paired, working agent.

• Channel Skills

  Per-channel capabilities layered on top of the raw connectors.

• Operational Skills

  Task-level abilities the agent can invoke while handling a request.

• Dev Ops

  Scripts for building, migrating, and maintaining an installation.

• Docs Assets

  Documentation and static assets kept alongside the code.

• External Services

  Model providers and chat platforms the assistant depends on at runtime.

How this map was generated

JigsawML ingested the public repository, resolved its dependencies, and grouped the code into architectural components using AI agents and a knowledge graph. Nothing here was drawn by hand. The same process runs against private repositories and cloud accounts, and re-runs on every commit so the map never goes stale.

Other open-source architectures

• Axios architecturePromise-based HTTP client for the browser and node.js
• Flask architectureThe Python micro framework for building web applications
• Hono architectureAn ultrafast web framework built on Web Standards
• Instro architectureAn open-source Python library for scripting and automating test equipment
• Nemoclaw architectureA reference stack for running OpenClaw in OpenShell
• OpenClaw architectureA self-hosted gateway that connects chat apps to AI coding agents
• OpenHands architectureA self-hosted developer control center for coding agents and automations
• Pydantic architectureData validation library for Python
• Pyramid architectureThe Start Small, Finish Big, Stay Finished Framework
• Zod architectureA TypeScript-first validation library