What Is NanoClaw? The Lightweight Personal AI Agent You Can Self-Host

What Is NanoClaw? An Introduction to the NanoClaw AI Agent

Imagine having a personal AI assistant that lives on your own hardware, responds to you through WhatsApp or Telegram, runs every task inside a secure sandbox, and is built from a codebase small enough that you could read the whole thing during a lunch break. That is exactly what NanoClaw delivers.

NanoClaw is a lightweight, open-source NanoClaw AI agent framework that runs on your machine as a single Node.js process. It connects to the messaging apps you already use, executes AI agent sessions inside isolated Linux containers, and gives you complete control over your personal AI assistant. Since its launch in January 2026, the project has amassed over 25,500 stars on GitHub, making it one of the fastest-growing open-source AI agent projects of the year.

In this article, we will walk through everything you need to know about NanoClaw: what it does, how it compares to its predecessor OpenClaw, its architecture, features, use cases, and how to decide whether it is the right tool for you.

NanoClaw vs OpenClaw: Why NanoClaw Exists

To understand NanoClaw, you first need to know about OpenClaw. OpenClaw is a well-known open-source AI assistant platform that offers extensive functionality. However, it comes with significant complexity: nearly half a million lines of code, 53 configuration files, and 70+ dependencies.

NanoClaw’s creator put it bluntly: “I wouldn’t have been able to sleep if I had given complex software I didn’t understand full access to my life.” That concern led to NanoClaw, a ground-up reimplementation that delivers the same core functionality in a package that is radically smaller and more transparent.

Here is how the two compare side by side:

Metric	NanoClaw	OpenClaw
Source files	~15	3,680
Lines of code	~3,900	~434,453
Dependencies	<10	70+
Config files	0	53
Time to understand	~8 minutes	1-2 weeks
Security model	OS container isolation	Application-level checks
Architecture	Single process + isolated containers	Single process, shared memory

The difference is not just aesthetic. OpenClaw runs everything in one Node process with shared memory, relying on allowlists and pairing codes for security. NanoClaw uses real OS-level isolation: every agent session runs in its own Linux container with its own filesystem. If an agent goes rogue, it is trapped inside a sandbox with no access to anything you have not explicitly mounted.

Key Features of the NanoClaw AI Agent

Despite its small footprint, NanoClaw packs a comprehensive set of features. Here is what you get out of the box and through the skills system.

Multi-Channel Messaging

NanoClaw connects to the messaging platforms you already use every day. WhatsApp support is built in, and you can add Telegram, Discord, Slack, and Gmail through the skills system. Adding a new channel is as simple as running a command like /add-telegram inside Claude Code. You can run multiple channels simultaneously, each with their own configuration.

Once connected, you interact with your agent by mentioning a trigger word (the default is @Andy) in your messages. In your private self-chat (the “main channel”), you do not even need the trigger word.

Container Isolation

This is NanoClaw’s defining security feature. Every agent session runs inside its own isolated Linux container. On macOS, you can choose between Apple Container (a lightweight native runtime optimized for Apple silicon) or Docker. On Linux, Docker is the default. For even stronger isolation, NanoClaw supports Docker Sandboxes that run each container inside a micro VM.

Containers can only access directories that are explicitly mounted. There is no ambient access to your filesystem, environment variables, or processes. Bash commands that the agent runs execute inside the container, not on your host machine.

Agent Swarms

NanoClaw can spin up teams of specialized agents that collaborate on complex tasks. This makes it, according to the project, the first personal AI assistant to support multi-agent swarms. You could, for example, have one agent research a topic while another writes a summary and a third formats it for publication.

Per-Group Memory and Isolation

Each messaging group gets its own isolated environment. This includes a dedicated CLAUDE.md memory file, its own filesystem, its own container sandbox, and its own Claude session. Groups cannot access other groups’ data. This means you can use NanoClaw across a work group, a family chat, and a personal research channel, all with completely separate contexts and permissions.

Scheduled Tasks

NanoClaw includes a built-in task scheduler that supports cron expressions, interval-based timing, and one-shot execution. You can set up recurring tasks using plain language:

• “Send an overview of the sales pipeline every weekday morning at 9am”
• “Review the git history for the past week each Friday and update the README if there’s drift”
• “Every Monday at 8am, compile news on AI developments from Hacker News and TechCrunch and message me a briefing”

The scheduler polls the database every 60 seconds for due tasks and respects concurrency limits. Task containers close automatically 10 seconds after producing output to minimize resource usage.

Web Access

Agents have the ability to search the web, fetch content from URLs, and browse pages. This means your personal agent can research topics, pull in current data, and summarize findings, all from within your messaging conversation.

Skills System

Rather than adding features to the core codebase, NanoClaw uses a “skills over features” philosophy. Skills are Claude Code commands (like /add-telegram, /add-gmail, /customize) that modify your fork to add capabilities. This keeps the base system minimal while letting each user customize their installation without inheriting features they do not want.

NanoClaw Architecture Overview: How It Works Under the Hood

NanoClaw’s architecture is refreshingly straightforward. The entire system is a single Node.js process that orchestrates all components. Here is the data flow:

Message In (WhatsApp / Telegram / etc.)
        |
        v
   [ SQLite DB ]  -- store & deduplicate
        |
        v
   [ Polling Loop ]  -- checks every 2 seconds
        |
        v
   [ Group Queue ]  -- per-group FIFO ordering
        |
        v
   [ Container ]  -- Claude Agent SDK runs here
        |
        v
   Response streamed back to channel

Let us break down the key components:

The Orchestrator (index.ts)

This is the brain. It polls the SQLite database every 2 seconds for new messages, filters by registered groups, checks for the trigger pattern, and routes messages to the appropriate group queue. It also maintains cursor state to track which messages have been processed.

The Group Queue (group-queue.ts)

Each messaging group gets a dedicated FIFO queue. The system enforces a maximum of 5 concurrent containers by default (configurable via the MAX_CONCURRENT_CONTAINERS environment variable). When a container is already active for a group, new messages are piped directly to the running container through IPC rather than spawning a new one. Failed runs are retried with exponential backoff (5-second base, up to 5 retries).

The Container Runner (container-runner.ts)

This component handles the lifecycle of isolated agent containers. It builds volume mounts based on group privileges, spawns the container via Docker CLI, streams output in real time, and handles cleanup. Containers have a default hard timeout of 30 minutes with activity-based reset, meaning the timer restarts on each piece of streaming output.

IPC via Filesystem

Containers communicate with the host through JSON files in per-group directories. The host polls these files, validates authorization, executes requests, and cleans up. This approach is simple, auditable, and avoids complex IPC mechanisms.

The Database (db.ts)

NanoClaw uses SQLite for all persistence: messages, sessions, groups, tasks, and router state. No external database server required.

Key Source Files

If you want to understand the full codebase, here are the files that matter:

File	Purpose
src/index.ts	Orchestrator: state, message loop, agent invocation
src/channels/registry.ts	Channel registry with self-registration at startup
src/container-runner.ts	Spawns containers with isolated mounts, streams output
src/group-queue.ts	Per-group FIFO queue with concurrency limits and retry backoff
src/ipc.ts	IPC watcher and task processing with authorization checks
src/db.ts	SQLite operations for messages, groups, sessions, and state
src/task-scheduler.ts	Cron, interval, and one-shot scheduled task execution
src/router.ts	Message formatting and outbound routing
groups/*/CLAUDE.md	Per-group memory files

Prerequisites: What You Need Before Setting Up NanoClaw

Before you can get NanoClaw running, you need the following:

• Operating system: macOS, Linux, or Windows (via WSL2).
• Node.js 20+: NanoClaw requires a modern Node.js runtime.
• Claude Code: This is Anthropic’s CLI tool. NanoClaw is built on it and uses it for setup, customization, and debugging. You can install it from claude.com/product/claude-code.
• A container runtime: Apple Container on macOS (lightweight and native) or Docker on macOS/Linux. Docker is configured automatically during setup.
• Claude API key or Claude Code subscription: Since NanoClaw runs on the Claude Agent SDK, you need access to Claude. This can be a direct API key or a Claude Pro/Team subscription.

The actual setup process is AI-native. After cloning the repo, you run claude in the project directory and then type /setup. Claude Code handles everything: dependency installation, authentication, container configuration, and service startup. No manual config files to edit.

git clone https://github.com/qwibitai/nanoclaw.git
cd nanoclaw
claude
# Then inside Claude Code, type: /setup

Use Cases: What People Do With NanoClaw

NanoClaw’s combination of messaging integration, scheduling, and agent capabilities opens up a wide range of practical applications. Here are some of the most compelling use cases.

Personal Research Assistant

Message your agent through WhatsApp while on the go: “Research the latest developments in quantum computing and send me a summary by tonight.” NanoClaw’s web access lets the agent browse sources, compile information, and deliver a structured briefing to your chat.

Automated Daily Briefings

Set up scheduled tasks to compile news, monitor competitors, or summarize email threads. For example: “Every weekday at 8am, compile the top AI news from Hacker News and TechCrunch into a two-paragraph briefing.” The scheduler handles the timing, and the agent does the research and writing.

Code Repository Monitoring

Point NanoClaw at your project directories (mounted into the container) and have it review git history weekly, flag documentation drift, or generate changelogs. Since the agent runs inside a container with access only to what you mount, this is safe even for sensitive codebases.

Family and Group Coordination

With per-group isolation, you can add NanoClaw to a family WhatsApp group with its own memory and context, completely separate from your work channels. It can help plan events, answer questions, or maintain shared lists, all without mixing contexts.

Multi-Agent Workflows

The agent swarm feature lets you tackle complex tasks by spinning up specialized agents. For instance, a research agent gathers data, an analysis agent processes it, and a writing agent produces the final report. All coordinated automatically and running in isolated containers.

Email Management via Gmail Integration

By running the /add-gmail skill, you can have NanoClaw monitor and respond to emails, summarize your inbox, draft responses, or flag important messages to your WhatsApp.

Cost: What Does NanoClaw Actually Cost to Run?

NanoClaw itself is completely free and open source under the MIT license. There is no subscription, no premium tier, and no feature gating. You get the full codebase with no restrictions.

The cost comes from the underlying AI model usage. Since NanoClaw runs on the Claude Agent SDK, you need one of the following:

• Claude API key: Pay-as-you-go based on token usage. Costs vary depending on how much you interact with your agent. NanoClaw is designed to be lightweight in token usage.
• Claude Code subscription: A flat monthly subscription through Anthropic that includes Claude Code usage.

NanoClaw also supports third-party and open-source model endpoints that are compatible with the Anthropic API format. You can set ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN in your .env file to point at local models via Ollama, or hosted alternatives like Together AI or Fireworks. This can significantly reduce or eliminate ongoing costs if you are willing to trade some capability for savings.

Infrastructure costs are minimal since NanoClaw runs on your own machine. There is no cloud hosting required unless you choose to deploy it on a VPS.

Who Should Use the NanoClaw AI Agent?

NanoClaw is not for everyone, and it is designed that way. Here is who will get the most value from it.

Developers and Technical Users

If you are comfortable with a terminal, git, and Node.js, NanoClaw is straightforward to set up and customize. The small codebase means you can actually understand what your AI agent is doing, modify its behavior, and extend it with new capabilities. Here at AI Tools Hub, we consider this level of transparency rare and valuable in the AI agent space.

Privacy-Conscious Users

Everything runs on your hardware. Your messages, your data, and your agent’s memory stay on your machine. The container isolation means even the agent itself cannot access files you have not explicitly granted. If you have been hesitant about cloud-based AI assistants, NanoClaw addresses those concerns directly.

Power Users Who Want Automation

The combination of messaging integration, scheduled tasks, and agent swarms makes NanoClaw a powerful automation platform. If you currently use multiple tools for monitoring, scheduling, and AI chat, NanoClaw can consolidate those into a single, private assistant.

Teams and Small Organizations

With per-group isolation, different teams or projects can each have their own agent context, memory, and permissions. A work channel stays separate from a personal channel, with no data leakage between them.

Who Should Probably Wait

If you are not comfortable with running terminal commands or managing a Node.js environment, NanoClaw may be challenging despite its AI-native setup. The project is also still relatively young (launched January 2026), so expect active development and occasional rough edges.

Conclusion: Is NanoClaw the Right AI Agent for You?

NanoClaw represents a different philosophy in the AI agent space. Rather than building the most feature-rich platform possible, it builds the most understandable and secure one. With roughly 3,900 lines of code, real container isolation, and support for the messaging apps you already use, the NanoClaw AI agent delivers genuine personal AI assistance without requiring you to trust software you cannot audit.

The numbers speak for themselves: 25,500+ GitHub stars in just two months, a growing community on Discord, and an active skills ecosystem. If you value security, simplicity, and ownership, NanoClaw is worth your time.

The project is open source, free to use, and designed to be forked and customized. Whether you want a WhatsApp assistant that sends you daily briefings, a code review bot that monitors your repositories, or a multi-agent system that handles complex research tasks, NanoClaw gives you the foundation to build it, on your own terms.

Ready to get started? Head to the NanoClaw GitHub repository and follow the three-line setup. For a detailed walkthrough, check out the official documentation.