NanoClaw: a small, isolated, adaptable personal agent

Everything worth knowing about nanocoai/nanoclaw: a messaging AI assistant that runs every agent in a container and prioritizes a codebase the user can inspect and modify.

---

What NanoClaw is

NanoClaw is a personal AI agent for messaging apps. Its current proposal combines channels like WhatsApp, Telegram, Discord, Slack, Gmail, Microsoft Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, and WeChat with memory, scheduled tasks, and container-isolated agents. The repository states it uses Anthropic’s agent SDK; the official site documents additional installable providers, including Codex, OpenCode, and Ollama.

It doesn’t present itself as a general agent platform or a hosted service. It’s free software under MIT, meant for each person to fork and adapt to their needs. The official site describes a Node host process that routes messages and wakes containers per agent group; inside each session there are inbound and outbound SQLite databases, and each group keeps its own CLAUDE.md, memory, skills, and permitted mounts.

Origin: a reaction to complexity and privileged access

The repository was created on January 31, 2026. The first commit visible at the root describes it as a personal Claude assistant over WhatsApp, and the February 1 Hacker News launch was posted by jimminyx, who identified themselves there as the sole developer of a weekend project.

The stated motivation was tension with OpenClaw: its author said they weren’t comfortable handing access to their life over to complex software they couldn’t understand. The README contrasts that perceived risk with a small architecture and OS-level isolation. In the launch thread, they explained they used it to chat with Claude Code about a mounted Obsidian vault and to schedule tasks via WhatsApp.

The project didn’t originate under its current organization: the thread linked the historical repository gavrielc/nanoclaw; the canonical location as consulted today is nanocoai/nanoclaw. The official site also links NanoCo as the maintainer and announces a $12 million funding round, but that announcement is first-party material and doesn’t by itself allow inferring the software’s degree of technical maturity.

Philosophy and principles

NanoClaw states an explicit philosophy:

• Small enough to understand: one process, few files, no microservices; the site compares 132 source files and about 17,500 lines for NanoClaw against larger figures attributed to OpenClaw.

• Security through isolation: the agent only sees explicitly mounted directories, and terminal commands run inside the container, not directly on the host.
• Personal, not monolithic: forking the repository and adjusting it with a coding agent is encouraged, rather than growing it to include every possible feature.
• Skills before built-in features: the trunk holds the registry and infrastructure; channel and provider adapters are added on demand via skills.
• Hybrid installation: there’s an installer for the normal path, and Claude Code steps in when diagnosis or a contextual decision is needed.

This is a design stance, not a security certification. The project itself must be reviewed and operated with the right privileges for each installation.

How it works

The documented operational flow is as follows:

1. A channel receives a message, and the host process associates it via the entity model user → messaging group → agent group → session.
2. The router logs the input in inbound.db and wakes the corresponding container.
3. The container runs the agent with its isolated memory, instructions, and skills.
4. The output is written to outbound.db; the delivery component queries it and responds through the channel adapter.

Isolation is configurable per channel: you can split each channel into its own agent, share an agent and its memory across several channels, or group channels into a shared session. Outbound credentials route through OneCLI’s Agent Vault; per the site, it injects the key on request and applies per-agent policies and limits, so the agent never receives the raw key.

Adapters and providers are added as skills. For instance, the process described for /add-telegram pulls files from the channels registry branch, copies them without merging that branch, and runs a registration test; the contributing README also cites /add-slack, /add-discord, and /add-opencode.

Official and semi-official status

No evidence was found that NanoClaw has been accepted into an official Anthropic, OpenAI, Apple, Telegram, or other provider marketplace. Its verifiable status is that of a public MIT project with its own organization and site, with documented integration with Claude Code, Anthropic’s agent SDK, Docker, and OneCLI.

The official pages state that the agent uses Anthropic’s official SDK and can add alternative providers. That establishes documented technical integration, not sponsorship, audit, or approval from Anthropic, OpenAI, or the messaging services. The presence of over 30,000 stars and an active discussions community can indicate de facto attention, but not a formal standard designation.

The ecosystem

NanoCo repositories

Querying nanocoai’s public repositories identified components and extensions with an explicit relationship:

• nanocoai/nanoclaw-templates (4 stars): installable agent templates.
• nanocoai/nanoclaw-telegram (10), nanocoai/nanoclaw-whatsapp (10), nanocoai/nanoclaw-discord (1), nanocoai/nanoclaw-slack (1), nanocoai/nanoclaw-gmail (2), and nanocoai/nanoclaw-matrix (1): channel integrations.
• nanocoai/nanoclaw-opencode (0): work packaged to make OpenCode a first-class provider.
• nanocoai/nanoclaw-skills (16) and nanocoai/nanoclaw-community-skills (1): skills repositories.
• nanocoai/nanoclaw-dashboard (3): a monitoring interface that receives JSON snapshots.
• nanocoai/nanoclaw-docker-sandbox (8), nanoclaw-docker-sandboxes (0), and nanoclaw-docker-sandbox-windows (0): isolated environment variants.

These are repositories related by the same organization, not mandatory dependencies for every install. The contributing documentation specifically confirms that templates are maintained in nanocoai/nanoclaw-templates.

Forks, ports, and derivative projects

Among forks with their own description are taylorwalton/talon (89 stars), an autonomous SOC analyst agent; MedClaw-Org/MedClaw (32), a medical assistant; tobalo/bunclaw (29), a Bun-centered variant; Rlin1027/NanoGemClaw (19), a Gemini and Telegram variant; anagrambuild/solclaw (15), oriented toward Solana operations; and GaussianGuaicai/nanoclaw-codex (12), which states it uses the Codex SDK.

The repository search also found ports not marked as forks: ApeCodeAI/nanoclaw-py (187 stars) in Python, microclaw/microclaw (730) in Rust, agoodway/goodwizard (40) in Elixir, lorenzovenice/nanoclaw-venice (19) with the Venice API, and lmxxf/nanoclaw-on-openharmony (14), whose name indicates an OpenHarmony adaptation. No non-English community port or translation with verifiable documentation beyond that naming hint was found.

The root itself links README files in Chinese, Japanese, and Korean; the v2.1.54 release credits a contribution from arkjun for the Korean README. These are localizations included in the project, not independent translation repositories.

Repo numbers

Measured: August 12, 2026; GitHub API and page.

Metric	Value
Stars	30,492
Forks	12,864
Real subscribers	129
Visible GitHub commits	2,314
Branches	151
Tags	8
Primary language	TypeScript
License	MIT
Created	January 31, 2026
Latest release	v2.1.54, August 1, 2026

The API lists top contributors as gavrielc (1,190 contributions), github-actions[bot] (348), Koshkoshinsk (157), glifocat (130), and gabi-simons (97). The repository page shows 2,314 commits, while the general API doesn’t offer a direct commit total in its response; the page’s visible figure is kept for that reason.

The API’s open_issues_count value was 882, but it isn’t presented as issues exclusively: GitHub notes that field can include open pull requests. The page showed 313 issues and 569 pull requests separately. The API also duplicates stars in watchers_count; that’s why the table uses subscribers_count for real subscribers.

The v2.1.54 release is a rollup from v2.1.18 to v2.1.54; it mentions provider migration, memory, scheduled tasks, hardened images, and skill changes. It also showed 41 commits after that release as of viewing.

How to contribute

NanoClaw has a detailed contribution policy. Before starting, it suggests checking pull requests and issues with gh pr list --repo nanocoai/nanoclaw --search "<feature>" and gh issue list --repo nanocoai/nanoclaw --search "<feature>", confirming the change fits the philosophy, and limiting each PR to a single thing.

The bar is deliberately restrictive: bug or security fixes, simplifications, and code reductions are accepted; new capabilities, compatibility, or improvements must become skills. For a channel or provider skill, you must fork from main, create a self-registering module, add its registration test, prepare SKILL.md and REMOVE.md when it leaves changes behind, and open a PR. Skills must be tested on a clean clone.

Breaking changes are allowed, but not silently: every [BREAKING] changelog entry must link a migration path via a skill or documentation with detection, cause, fix, verification, and rollback. versions.json is the mechanical signal for external version changes, and /update-nanoclaw presents them after updating.

Quick-start guide

Installation and first run

Documented requirements: macOS, Linux, or Windows via WSL2; Node.js 20 or newer, pnpm 10 or newer, Claude Code, and Docker Desktop or Docker Engine.

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash nanoclaw.sh

The script installs Node, pnpm, and Docker if missing, registers the Anthropic credential with OneCLI, builds the container, and pairs the first channel. If a step fails, official documentation says Claude Code is invoked to diagnose and continue.

Common workflows

1. Add Telegram: run /add-telegram from the coding agent session. The skill pulls the adapter’s files from the channels branch, copies them into the clone, and verifies registration; it then walks through interactive token and bot configuration.
2. Add another channel or provider: the same pattern is documented for /add-slack, /add-discord, and /add-opencode. Channels and providers install on demand, so the clone doesn’t ship every adapter by default.
3. Separate sensitive conversations: choose an isolation relationship per channel — one agent per channel for privacy, one shared for common memory, or a shared session across several channels. Each group has its own container, memory, and instructions.
4. Schedule recurring actions: use the project’s scheduled tasks to launch Claude and receive the result over messaging; the site offers morning digests and weekly reviews as examples.

Essential configuration

• Each agent group’s CLAUDE.md: instructions for the isolated agent; each group keeps its own.
• Permitted mounts: define which directories the container can see; the most important practical control over host access.
• /add-<channel> and /add-<provider> skills: the documented mechanism for selectively adding adapters.
• versions.json: the mechanical signal of external versions used by the update path to detect migrations.
• docs/ and the changelog: the source of migration paths for breaking changes.

Common pitfalls and fixes

• A local clone doesn’t migrate itself. Project policy requires a migration path for every breaking change; use /update-nanoclaw and follow the associated skill or document, rather than manually rebuilding the change from the diff.
• An adapter shouldn’t be merged into main. Skill documentation says to obtain files from the registry branch and copy them, not merge that branch; it also requires running the adapter’s registration test.
• Don’t assume isolation replaces permission design. The HN thread debated external actions and harmful consequences: thepoet asked how such actions were limited; the follow-up discussion distinguished container isolation, microVMs, and attack surface. Reviewing mounts, credentials, and policies before granting access is necessary.
• AI-generated documentation and code need review. At launch, avaer found an incorrect path in the quick start; jimminyx confirmed Claude Code had introduced it and fixed it. redfloatplane and MrJohz questioned the confidence inspired by apparently unreviewed documentation. That’s a concrete historical criticism, not a claim about the current release’s quality.

Integrations and migration

NanoClaw integrates Docker on macOS, Linux, and WSL2; on macOS, Apple Container appears as a native option. OneCLI provides the credential broker; Claude Code is the native path, and the documentation lists skills for Codex, OpenCode, and Ollama as per-group configurable alternatives.

Migration from an OpenClaw-type assistant isn’t documented as automatic data or configuration import. The verifiable practical path is to create a NanoClaw clone, add only the required channels and providers via skills, and configure mounts and agent groups. That difference responds precisely to the personalization-by-fork principle.

How the community received it

The direct Hacker News launch was thread 46850205: 533 points and 224 comments as retrieved. The initial text was from the author, so it credits launch, not an independent review. The conversation does offer concrete reactions:

• mark_l_watson said they liked the idea of a minor version of OpenClaw and noted interest in Apple Container, though they objected that the stated size didn’t match their rough estimate of TypeScript lines.
• thepoet valued Clawdbot’s capacity for broad permissions, asked how NanoClaw isolated potentially harmful external actions, and found Apple’s containers interesting; so their comment is both technical interest and a security reservation.
• avaer questioned a nonexistent clone instruction and asked whether it was an official Anthropic project. jimminyx replied that Claude Code had introduced that incorrect reference, fixed it, and described the project as rough but adequate for their needs.
• redfloatplane criticized that documentation with signs of AI generation lowered their confidence, even while liking the idea. MrJohz added that an apparently self-generated, unreviewed README can raise doubts about code review. These are user opinions, not independent audits.

GitHub has open discussions across announcements, general, ideas, polls, Q&A, and community extension showcases: the discussion “The evolution of this codebase” had 7 votes and 6 comments, and “Support for other LLM or openrouter” had 5 votes and 8 comments as of query. The discussion “How nanoclaw is different from Claude Channels?” logged 3 votes and 1 comment. These figures show activity, but don’t amount to a satisfaction survey.

No retrievable, verifiable evidence of specific Reddit threads, X posts, Product Hunt, Dev.to, Hashnode, podcasts, package registries, or independent videos was obtained during this run. Access protections and non-verifiable results aren’t interpreted as an absence of coverage.

NanoClaw vs. other approaches

Proposal	Verifiable match	Verifiable difference
OpenClaw	Both are AI assistants connected to messaging; NanoClaw explicitly positions itself as an alternative.	NanoClaw states a host-process architecture with per-group containers and selective adapter adoption; its official comparison claims to aim for smaller size and fewer dependencies. This is the project’s own characterization, not an independent benchmark.
ApeCodeAI/nanoclaw-py	Described as a small alternative to OpenClaw sharing tasks, file access, commands, and scheduling.	States it’s implemented in about 500 lines of Python; the main NanoClaw uses TypeScript per the API. Insufficient documentation was retrieved to compare security or compatibility.
microclaw/microclaw	An agent assistant that lives in chats and states it’s inspired by NanoClaw.	Its description states Rust and that it incorporates some NanoClaw ideas; the source doesn’t support further functional equivalence.
goodwizard	Its description presents it as a NanoClaw clone.	States Elixir; its README wasn’t retrieved, so no additional capabilities are attributed.

Use cases

• A person who wants to chat with an agent from their usual channel can connect WhatsApp, Telegram, Slack, or another adapter on demand and keep the agent’s memory and instructions inside an isolated group.
• Someone who needs an assistant with limited access to specific files can create an agent group with explicit mounts and review what data enters the container, instead of granting general host access.
• Small teams or advanced users wanting recurring automations can use scheduled tasks for summaries and reviews delivered via messaging, as long as they adjust OneCLI credentials and policies to each action’s sensitivity.
• Developers who want a modifiable base for a specific domain can fork the project and turn changes into skills, channels, providers, or templates; the Talon, MedClaw, and SolClaw derivatives show the community has already explored security, health, and Solana-operations specializations.

Resources

• Repository: https://github.com/nanocoai/nanoclaw
• Documentation and installation: https://docs.nanoclaw.dev
• Official site: https://nanoclaw.dev
• Contributing guide: https://github.com/nanocoai/nanoclaw/blob/main/CONTRIBUTING.md
• Official templates: https://github.com/nanocoai/nanoclaw-templates
• Discord community: https://discord.gg/VDdww8qS42
• Hacker News conversation: https://news.ycombinator.com/item?id=46850205
• Release and changelog: https://github.com/nanocoai/nanoclaw/releases/tag/v2.1.54

---

Note: this article combines official documentation, the GitHub API, the release notes, and a Hacker News thread gathered on August 12, 2026. Figures change over time.