OpenClaw won the personal AI agent category in early 2026 by being huge: 430,000 lines of code, 50+ modules, 45+ dependencies, every channel and every skill bundled together. NanoClaw is going to win a slice of that audience by being the opposite: a single understandable codebase, one channel by default, every agent isolated inside its own Apple Container or Docker container. If your reaction to OpenClaw was "I love what it does, but I cannot read all of this and I am not sure I trust it on my machine," NanoClaw was built for you.
I have been testing NanoClaw since the Better Stack walkthrough and the Jordan Urbs install demo put it on my radar in February and March. After a week of running it on a Mac and a Linux VPS, the punchline is simple: NanoClaw is not the most powerful personal agent, but it is the most defensible one. This guide covers what NanoClaw is, why it exists, how to install it on Mac, Linux, or a VPS, and the workflow that makes it more interesting than the dependency count suggests.
Key Takeaways
- NanoClaw is ~500 lines of code versus OpenClaw's 430,000, making it fully readable and auditable in an afternoon.
- Every skill runs inside Apple Container (Mac) or Docker (Linux), so a compromised tool cannot touch your host system by design.
- The 5-minute container timeout is a deliberate security feature, not a limitation, capping blast radius if a rogue process lingers.
- NanoClaw is self-extending: ask the agent to add a new capability and it calls Claude Code to write, test, and register the new tool itself.
- It locks in to Anthropic-only models via the Claude Agent SDK, which is a clear trade-off: simpler architecture, zero provider flexibility.
- Cisco data shows 26% of organisations cite skill gaps as their top AI blocker, positioning personal agents like NanoClaw as a direct answer to that problem.
Learn this hands-on
Ready to ship a real production app, not just pick a model? Check out the Master Course: Build and Ship a Production-Ready App with Lovable and Cursor.
What NanoClaw Is
NanoClaw is an open-source personal AI agent built on top of Anthropic's Claude Agent SDK. The entire codebase comes in at around 500 lines, the project is at roughly 20,000 GitHub stars as of March 2026, and the design goal is the inverse of OpenClaw: ship the smallest possible primitive, isolate every running agent inside a container, and let the user (or Claude Code itself) extend it on demand.
The default install gives you:
- One channel: WhatsApp, connected via QR code
- One model: Claude Sonnet, swappable but Anthropic-only by default since the runtime is the Claude Agent SDK
- The Claude Agent browser tool for web access
- Per-agent isolation through Apple Containers on macOS or Docker on Linux
- A 5-minute container timeout so a misbehaving agent cannot run wild
- No config file, no dashboard, no plugin marketplace
That last point is intentional. The NanoClaw philosophy is that a personal agent should not need a configuration system, because the agent itself can read its own source and rewrite itself when you need a new feature. We will get to how that works in a minute.
Why NanoClaw Exists: The OpenClaw Security Problem
OpenClaw shipped under the assumption that personal AI agents would be downloaded by everyone, customized by everyone, and run on everyone's primary machine. That assumption produced a tool with a huge feature surface area. Better Stack's walkthrough framed the structural problem clearly: OpenClaw runs in a single Node process with shared memory, it does not sandbox by default, and it has direct access to the host system it lives on.
A Cisco security report cited in the Better Stack video found that 26% of all agent skills have vulnerabilities. That is not a typo. More than one in four skills you might install from a community marketplace ships with at least one known vulnerability. OpenClaw, with its rich skill ecosystem and shared-memory runtime, gives every one of those vulnerabilities first-class access to your file system, your environment variables, your SSH keys, and your browser session. If you have ever wondered whether there is a way to run Claude without it logging your conversations, Claude Incognito Mode is worth reading alongside this -- but incognito mode is a different problem from what NanoClaw solves. There are mitigations (Docker, modal serverless deployment, isolated VPS) but none of them are the default, and most casual installs run on bare metal.
"I think so many people, myself included, are running these coding agents practically as root, right? We're letting them do all of this stuff. And every time I do it, my computer doesn't get wiped. I'm like, 'oh, it's fine'."
— Simon Willison, Co-creator of Django and independent AI/security researcher
NanoClaw flips that default. Each agent runs inside its own Apple Container (on macOS) or Docker container (on Linux). Filesystem access is explicitly mounted, not implicit. The container has a 5-minute timeout, which kills any agent that lingers too long. The codebase is small enough that a security researcher can audit it in an afternoon, and small enough that Claude Code can read the entire thing into context and reason about it.
The trade-off is real. NanoClaw at install ships with one channel and a thin tool set. You will not find a 5,700-skill marketplace. You will not find a dashboard. What you find instead is a primitive you can extend safely.
I think so many people, myself included, are running these coding agents practically as root, right? We're letting them do all of this stuff. And every time I do it, my computer doesn't get wiped. I'm like, 'oh, it's fine'.
What's in the Box (and What Isn't)
When you finish the install, here is what is configured for you:
- Channel: WhatsApp, paired via QR code
- Model: Claude Sonnet (configurable later via the agent itself)
- Tools: Claude's built-in agent browser for web access
- Isolation: Apple Containers on macOS or Docker on Linux
- Memory: lightweight, scoped per agent. Not as rich as OpenClaw's Soul/Identity files
- Scheduled jobs: supported through the underlying Claude Agent SDK's cron primitives
What you will NOT find on day one:
- A dashboard
- A configuration file
- Telegram, Slack, Signal, Discord, or Gmail support out of the box
- A marketplace of community skills
- Image generation, image sending, or media tools
- Multi-channel routing
The honest assessment from the Better Stack walkthrough: NanoClaw out of the box does not feel as polished as OpenClaw. Setup is rougher. There is no Soul file or Identities file that makes the agent feel personalized. There is just a small tool list and the WhatsApp connection. That is the cost of admission.
How to Install NanoClaw on Mac, Linux, or a VPS
Installation has three real prerequisites and one small chain of commands. Plan for 15 to 30 minutes the first time.
Prerequisites:
- A Claude (Anthropic) subscription. NanoClaw runs on the Claude Agent SDK, which by default supports only Anthropic models. If you try to use the Claude Code
/command without a Claude subscription, you will burn API tokens fast. The subscription path is much cheaper for the install workflow. - Node.js 20 or later. The CLI commands and helper scripts assume modern Node.
- Container runtime. Apple Containers ship with macOS 26 and later. On Linux, you need Docker.
On a Linux VPS, do the basic hardening first. Use a non-root user, disable public SSH access, and only connect to the VPS via Tailscale or an equivalent zero-trust network. This is the same hygiene I covered in the Hermes Agent guide, and it matters even more for NanoClaw because the agent will be reaching out to messaging APIs from your VPS's IP address.
Install steps:
# Clone the canonical repo
git clone https://github.com/qwibitai/nanoclaw.git
cd nanoclaw
# Install Node deps
npm install
# Run the bootstrap command via Claude Code.
# This is what wires up WhatsApp, the container runtime, and the default agent.
claude code /
The claude code / command is the part most users have not seen before. NanoClaw delegates its own setup to Claude Code: you run the slash command from the project root, Claude Code reads the codebase, asks you which channel you want, generates a QR code for the WhatsApp pairing, and finishes the wiring. If anything fails (and a few npm rebuilds and service restarts are normal on a first install), the creator's recommendation is to ask Claude Code directly: "I am installing NanoClaw and the WhatsApp pairing failed at step X. Can you read the source and fix it?"
That is a recurring theme. The install is small enough that Claude Code can read all of it. The runtime is small enough that an agent can rewrite parts of itself. NanoClaw treats Claude Code as part of its installer rather than as an optional dev tool. If you are new to Claude Code or want to get faster with it, the How to Master Claude Code series covers the patterns that make the NanoClaw install workflow feel natural rather than opaque.
After the install, the agent is reachable through your paired WhatsApp number. Send it a message. It responds using Sonnet by default, with browser tool access and the shell context inside its container.
The "Ask the Agent to Build It" Workflow
The most important pattern to understand about NanoClaw is that the agent extends itself. This sounds like marketing copy until you watch it happen.
The Better Stack walkthrough demonstrates the canonical example. The author asks NanoClaw over WhatsApp: "Can you send me an image?" The agent replies: "I do not have that ability." The author then asks: "Add the ability to send images." The agent reads its own source, writes a plan, asks for permission, modifies the codebase to add a new send_image tool, restarts the service, and from that point forward can fetch images from Unsplash and deliver them over WhatsApp.
That is the unlock. Every NanoClaw install is a starting point. Every user ends up with a different installed agent, because every user asks for different features over the first month of use, and each request becomes a permanent capability written into that user's local source. After 30 days, two NanoClaw users are running tools with the same name and very different code underneath. The tool list grows with the user, and only the features the user asked for end up in the codebase.
This is what Jordan Urbs calls the "AI native" approach. OpenClaw is what software looks like when humans write every feature in advance. NanoClaw is what software looks like when the user describes the feature they want and the agent writes it. The cost is that the binary you started with is no longer the binary you end with. The benefit is that there is no dead code in your tool, no skills you do not use, no surface area you did not request. For a look at how different agent CLIs compare at the command level, Claude Code vs Codex CLI breaks down the tradeoffs between the two most common options in the same ecosystem.
A Real-World Example: The X-Scraping Agent Swarm
Jordan Urbs's installation goes further than the Better Stack demo. After getting NanoClaw running with Telegram (a feature he asked the agent to add), he builds an agent swarm pipeline:
- A scraper agent uses Apify to pull 200 tweets from X around an AI-related search term
- A research agent looks at each tweet, identifies the underlying pain point, and clusters them
- An orchestrator agent generates a final report, summarized into 52 distinct AI pain points
The whole pipeline runs inside ephemeral Docker containers on a single laptop. Each agent has its own container, its own scoped permissions, and its own mounted directories. None of them touch the host file system except through explicit mount paths. The pipeline coordinates through Telegram bots talking to the orchestrator.
What is striking about Jordan's setup is not the pipeline itself (you could build something similar with raw Claude Code or with OpenClaw plus a custom skill). It is that the pipeline runs without the user needing to dedicate a separate machine to the job, without the user needing to vet a 50-line skill, and without the user needing to trust 45+ dependencies. The container isolation makes it safe to fire off speculative agent runs against untrusted input (X data) on the same laptop you use for everything else.
For the people who currently shy away from running personal agents because of the security exposure, this is the unlock. NanoClaw gives you the cheapest possible upgrade from "I am scared to run agents on my main machine" to "I am running scoped agents on my main machine."
NanoClaw vs OpenClaw: Where the Comparison Settles
| Dimension | OpenClaw | NanoClaw |
|---|---|---|
| Lines of code | ~430,000 | ~500 |
| Dependencies | 45+ | minimal |
| Channels by default | 15+ (WhatsApp, Telegram, Slack, Discord, Gmail, etc.) | 1 (WhatsApp) |
| Configuration files | Many | None |
| Dashboard | Yes | No |
| Skill marketplace | ClawHub (5,700+ skills) | None |
| Default isolation | Single Node process, shared memory | Per-agent Apple Container or Docker container |
| Direct host access | Yes | No (mounted paths only) |
| Container timeout | None | 5 minutes |
| Audit difficulty | High (430k lines) | Low (500 lines) |
| Customization | Pick from existing skills | Ask the agent to build the skill |
| Models | Multiple providers via configuration | Anthropic only (Claude Agent SDK) |
For most users coming from OpenClaw, this table is the entire decision. If your value comes from the breadth of ClawHub skills, OpenClaw wins. If your value comes from auditability, isolation, and the ability to customize on demand, NanoClaw wins. The middle ground (Hermes Agent, which we covered in the Hermes deep dive) is a third option for users who want better defaults than OpenClaw without giving up channel breadth.
NanoClaw vs Hermes Agent: Two Different Bets
NanoClaw and Hermes Agent are both pitched as OpenClaw alternatives, and both are getting search volume right now. They are not the same product. Knowing which one fits your needs saves you a weekend of wasted setup.
Hermes Agent bets that the OpenClaw problem is reliability and memory. Hermes ships with 40+ tools, persistent SQLite-backed memory, a Kanban dashboard, multi-agent profiles, a /goal long-running mission mode, and Android support via Termux. The thesis: keep the breadth of OpenClaw, but make it stable, give it real memory, and add a real dispatch UI.
NanoClaw bets that the OpenClaw problem is security and bloat. NanoClaw ships with one channel, no dashboard, no marketplace, and no configuration system. Every agent is container-isolated. Every feature is added on demand by the agent itself. The thesis: ship the minimum, audit easily, customize per user.
You can run both. They do not conflict. A reasonable setup for someone serious about personal AI agents looks like Hermes for daily work (Kanban dispatch, email triage, Obsidian integration) and NanoClaw for any agent run that touches untrusted input or executes untrusted code (web scraping, file conversion, sandboxed experiments).
If you can only install one this weekend, pick based on what scares you more. If "OpenClaw randomly broke again on the latest update and I lost three hours of work" is your fear, install Hermes. If "OpenClaw has access to everything on my machine and I do not actually trust the 45 dependencies it ships" is your fear, install NanoClaw.
Common Issues and How to Fix Them
A few things to know before you spend an hour in setup hell.
WhatsApp pairing fails on first try. This is the most common failure mode. The pairing process uses the QR code generated by the install, scanned from your WhatsApp mobile app under "Linked Devices." If the QR expires before you scan, regenerate it via the Claude Code prompt. If the pairing succeeds but the agent does not respond, restart the container and try a "ping" message.
The container exits after 5 minutes. This is by design. The 5-minute timeout is a security feature: long-running agents are killed and restarted to prevent resource leaks and reduce attack surface. If you want a longer-running task, decompose it into multiple smaller agent runs that can resume from disk state.
Sonnet is the only available model. True at install. To switch models, ask the agent over WhatsApp: "Add support for Claude Opus and let me select the model in the next message." The agent will modify its own source to add a model switcher and restart. If you want models from other providers (OpenAI, Anthropic alternatives), you will need to swap the Claude Agent SDK runtime for something else, which is a heavier modification.
npm rebuild errors. Mostly a Node version issue. Check that node -v is 20.x or later. If you are on 18, upgrade. If you are on 22 and still failing, fall back to 20 LTS.
Claude Code burns through tokens during install. This is the reason the Anthropic subscription is recommended over API access. The setup uses Claude Code heavily, and pay-per-token API access can add up. Subscription pricing absorbs this cost.
Should You Switch From OpenClaw to NanoClaw?
Yes if you fall into any of these categories:
- You run OpenClaw on a primary machine and the security exposure has been bothering you
- You want to read the entire personal-agent codebase before trusting it
- You enjoy customizing your tools and want the agent to extend itself rather than picking from a marketplace
- You only need one or two channels (most people who think they need 15 actually only use 2 to 3)
- You build agents that touch untrusted input (web scraping, document processing, third-party API responses)
Maybe if:
- You depend heavily on a specific ClawHub skill that has not been ported
- You need multi-channel support across Slack, Discord, and Telegram from day one and do not want to build that yourself
Probably not if:
- Your OpenClaw setup is working and you are not bothered by the security model
- You want a polished dashboard experience right away (NanoClaw's UX is bare-metal)
For most readers running OpenClaw casually, the migration plan is: install NanoClaw alongside OpenClaw this weekend, port your two most-used workflows by asking the agent to add the relevant tools, and run both for two weeks. The one you reach for daily wins. The one you do not, uninstall.
Closing: The Two Models for Personal AI Agents
OpenClaw established the personal AI agent category by being maximalist. Every channel, every skill, every memory pattern, all in one package. NanoClaw is the first serious answer to the question "what does the minimalist version look like?" and it is forcing the rest of the ecosystem to take security and auditability seriously.
The split between Hermes Agent and NanoClaw is not actually a fight over which one is better. It is a fight over which trade-off the user wants to make. Hermes optimizes for "more of the good parts of OpenClaw, fewer of the bad parts." NanoClaw optimizes for "the minimum primitive, infinite extensibility, container-safe by default."
If you want a structured path through building with personal agents, Claude Agent SDK, and the kind of self-extending workflows we walked through here, the Master Course on building and shipping production apps with Lovable and Cursor covers the full builder path from first agent to deployed product. It will not teach you NanoClaw specifically, but the patterns transfer directly: small primitives, agent-driven extension, isolation by default, ship to learn.
Install NanoClaw this weekend. Pair the WhatsApp number. Ask the agent to add one feature you have always wanted in a personal AI assistant. Watch it write the code, restart, and do the thing. That is the moment the model clicks.