NanoClaw: A Container-Isolated Agent Runner That Keeps the Codebase Small Enough to Read

Why NanoClaw exists: OpenClaw's complexity as a security problem

The README is explicit about the motivation: OpenClaw has nearly half a million lines of code, 53 config files, and 70+ dependencies, and its security is application-level, not OS-level. Everything runs in one Node process with shared memory. NanoClaw's author built it because they would not trust software they did not understand with full access to their life. That is a specific and honest framing. The project is not a generic assistant; it is a reaction to the risk of running a large, opaque agent on a host machine. For engineers who have read OpenClaw's source and balked at its surface area, NanoClaw offers a codebase that is one process and a handful of files. The trade-off is that you must be willing to read and modify code, because customization is defined as code changes, not config toggles.

The isolation model: containers as the security boundary

NanoClaw's core mechanism is that each agent runs in its own Linux container with filesystem isolation. The README states that agents can only see what is explicitly mounted, and that bash access is safe because commands run inside the container, not on the host. This is a different threat model from OpenClaw's allowlists and pairing codes. Instead of relying on permission checks at the application layer, NanoClaw uses Docker to create a kernel-level boundary. The docs mention an isolation model, referenced as docs/isolation-model.md, which presumably details how mounts and shared memory work across channels. The key point is that nothing crosses the container boundary unless you wire it to. That means you can give an agent web access or file access selectively, and a compromised agent does not automatically expose the host. This is a genuine security improvement for a single-user setup, though it depends on Docker being configured correctly on the host.

Getting started: one script from fresh machine to named agent

The quick start is a single command: clone the repo, cd into it, and run bash nanoclaw.sh. The script installs Node, pnpm, and Docker if missing, registers your Anthropic credential with OneCLI, builds the agent container, and pairs your first channel, which can be Slack, Telegram, Discord, WhatsApp, iMessage, or a local CLI. A notable feature is that if a step fails, Claude Code is invoked automatically to diagnose and resume from where it broke. That is an unusual design choice: the installer is deterministic for the common path but delegates judgment calls to an AI. The README warns to run the script directly, not from inside a Claude session, because the deterministic side needs interactive prompts and real shell I/O. This means you need a working Anthropic credential before you start, and you must be comfortable with Claude Code being part of the install loop.

Channel adapters and providers: skills over features

NanoClaw does not ship every channel adapter in the trunk. Instead, channels like Discord, Slack, Telegram, and WhatsApp live on a long-lived channels branch, and alternative providers like OpenCode and Ollama live on a providers branch. You run commands like /add-telegram or /add-opencode, and a skill copies exactly the modules you need into your fork. This is a deliberate anti-bloat strategy: you only get the features you ask for. The README lists a wide range of supported channels, including Microsoft Teams, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, and email via Resend. But the practical implication is that the trunk is minimal, and you must be willing to run these skills and potentially deal with branch-specific code. The per-agent group provider setting means you can mix Anthropic, OpenAI's Codex, OpenRouter, Google, DeepSeek, or local models via Ollama, but again, that requires installing the corresponding provider skill.

Memory and scheduled tasks: what the agent actually does

Each agent group has its own CLAUDE.md, its own memory, and its own container. The README says memory is per-agent, and there is a migration path for v1 that seeds the v2 DB from registered_groups and copies group folders, session data, and scheduled tasks. Scheduled tasks are recurring jobs executed by the agent, with optional script gates that avoid waking it when there is no work. That is a concrete mechanism: a gate script can check for conditions before the agent runs, saving API calls and compute. The isolation model also supports sharing one agent across many channels for unified memory, or folding multiple channels into a single shared session. This is more flexible than a one-channel-per-agent model, but the complexity of managing mounts and shared memory across channels is something you will need to verify in the docs, since the README does not detail the exact mechanics.

A real limitation: the dependency on Claude Code for everything

NanoClaw is built around Claude Code. The setup uses it for failure recovery, the README suggests asking Claude Code to walk you through the codebase, and the philosophy says that when a step needs judgment, control hands off to Claude Code. That is a strong coupling. If you do not want to use Anthropic's tooling, or if you want a purely deterministic installer, this is not for you. The README also states there is no monitoring dashboard or debugging UI; you describe problems in chat and Claude Code handles them. That means you are trading a GUI for an AI-driven debugging experience. If you are not comfortable with that, or if your use case requires auditing every action without an AI intermediary, this is a genuine friction point. The migration script also execs into Claude Code for parts that need judgment, so even upgrading from v1 requires the same dependency.

Alternatives: OpenClaw and the trade-off in approach

The obvious alternative is OpenClaw, which NanoClaw explicitly positions against. OpenClaw is a large, feature-rich project with application-level security and a single Node process. NanoClaw's approach is to shrink the codebase and use OS-level isolation. The difference is fundamental: OpenClaw gives you more features out of the box, at the cost of complexity and a larger attack surface. NanoClaw gives you a smaller, more auditable base, but you must add features yourself via skills. Another alternative is to build your own agent harness on top of Anthropic's Agents SDK directly, but that would require you to handle containerization, channel adapters, and memory yourself. NanoClaw abstracts those away while keeping the codebase small. If you need a production-grade, multi-tenant system with a full control plane, neither OpenClaw nor NanoClaw is ideal; you would look at a platform like LangGraph or a managed service, but those come with their own constraints.

Maintenance and upgrade cost: what the migration path reveals

The project is MIT-licensed, which means you can fork and modify it freely. The README explicitly encourages forking and having Claude Code modify the code to match your needs. That is a maintenance model: you are expected to maintain your own fork. The v2 migration script, migrate-v2.sh, is designed to move state from v1 to v2, including .env, the database, group folders, session data, and channel auth state. It does not flip the system service automatically; you pick "switch to v2" at the prompt or do it manually. This suggests that upgrades are not seamless and require active decision-making. The README references docs/v1-to-v2-changes.md for differences, which implies there are breaking changes between versions. The recent releases, v2.3.0, v2.2.0, and v2.1.54, indicate active development, but the maintenance cost is on you: you must track changes, test your fork, and reapply customizations. The README says the deterministic side of the migration needs interactive prompts and real shell I/O, so you cannot run it in a fully automated CI environment. That is a concrete operational constraint.

The verdict: who should adopt NanoClaw and what to verify first

NanoClaw is for engineers who value auditable code and OS-level isolation over feature completeness. It is for individuals who run their own assistants and are willing to edit TypeScript to customize behavior. It is not for teams that need a managed service, a GUI dashboard, or a quick plug-and-play deployment. Before adopting, verify that your host supports Docker (macOS/Linux/WSL2), read the isolation model docs to understand mount semantics, and test the scheduled-task script gates with a simple job. Also confirm that you are comfortable with the Claude Code dependency, because it is woven into setup, migration, and debugging. If you accept that, NanoClaw offers a genuinely different security posture than OpenClaw, and a codebase small enough that you can actually understand what your agent is doing.

Editorial conclusion

Adopt NanoClaw if you are an individual user who wants an AI assistant with true OS-level isolation, a codebase you can actually read and modify, and no interest in a large framework. Do not adopt it if you need a production-grade multi-tenant platform with a GUI dashboard or if you are unwilling to edit code for customization. Before adopting, verify that your OS supports Docker (macOS/Linux/WSL2), review the docs/v1-to-v2-changes.md and docs/isolation-model.md files, and test the scheduled-task script gates to confirm they fit your workflows. The project's reliance on Claude Code for setup and debugging is a deliberate trade-off that you must accept from day one.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes