NanoClaw
A container-isolated, customizable assistant for your messaging channels.
- Source repo
- nanocoai/nanoclaw
- Stars
- ★ 31k
- Last updated
- today
- License
- MIT
- Primary language
- TypeScript
- FA score
- 58/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesChatGPT · Codex · Claude Code · OpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- An individual with an Obsidian vault can explicitly mount that folder for one agent and have it send a weekday sales-pipeline overview.
- Not a fit if
- Teams that need declarative config files instead of code edits
- Windows users who cannot run Docker or WSL2
- Users who want a fully offline setup with no cloud LLM
- Source review
- 58/100 · Major gaps
What does this agent do, and when should you use it?
NanoClaw is a self-hosted personal AI assistant designed to run each agent in its own Linux container with only explicitly mounted files available to it. A single Node host process receives messages, routes sessions, wakes containers, and returns responses, while a Bun agent-runner inside each container runs the agent through the Claude Agent SDK. Each session exchanges work through its own inbound.db and outbound.db SQLite files. The project supports install-on-demand messaging adapters, per-agent workspaces and memory, and recurring jobs. It is best suited to individuals who can run Docker and prefer code-level customization over a broad configuration system.
A channel adapter passes an incoming message to the host, and src/router.ts routes it through the user, messaging group, agent group, and session model before writing it to that session's inbound.db. src/container-runner.ts starts the relevant agent-group container; container/agent-runner polls inbound.db, runs the agent with the Claude Agent SDK and MCP tools, then writes its output to outbound.db. src/delivery.ts polls outbound.db and delivers replies or system actions through the channel adapter, while src/host-sweep.ts performs stale detection, due-message wakes, and recurrence work every 60 seconds. OneCLI's Agent Vault injects credentials for outbound requests, so raw API keys do not enter the container.
- An individual with an Obsidian vault can explicitly mount that folder for one agent and have it send a weekday sales-pipeline overview.
- A developer can give a project group its own agent and schedule it to inspect the previous week's Git history and update a drifting README.
- A person active on Telegram, Discord, and WhatsApp can use /manage-channels to choose separate memory, a shared agent, or one shared session across those surfaces.
- Someone who wants a routine briefing can schedule a Monday task that compiles AI news from Hacker News and TechCrunch and sends it as a message.
- A user operating distinct assistants can configure providers per agent group, including Claude, Codex added through /add-codex, or providers added through OpenCode or Ollama.
How do you install or deploy this agent?
On macOS, Linux, or Windows through WSL2, run:
git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash nanoclaw.shThe script installs missing Node, pnpm, and Docker, registers an Anthropic credential with OneCLI, builds the agent container, and pairs a first Telegram, Discord, WhatsApp, or local CLI channel. The documented prerequisites are Node.js 20+, pnpm 10+, Docker, and Claude Code for customization, debugging, setup recovery, and all channel-addition skills.
How do you use this agent?
After pairing a channel, message the assistant with its trigger word; the default is @Andy. For example:
@Andy every Monday at 8am, compile news on AI developments from Hacker News and TechCrunch and message me a briefing
From a channel you own or administer, you can also send “@Andy list all scheduled tasks across groups” or “@Andy pause the Monday briefing task.” Add channel modules with /add-<channel>; the documented provider extensions are /add-codex, /add-opencode, and /add-ollama-provider.
What are this agent's strengths and limitations?
- Each agent group runs in a separate Linux container and can be limited to explicitly mounted directories, giving it a defined filesystem boundary.
- Host-container exchange uses two per-session, single-writer SQLite databases; the README explicitly describes no cross-mount contention, IPC, or stdin piping.
- Agent groups can have separate memory, CLAUDE.md files, containers, and mounts, which supports practical separation of personal, family, and work contexts.
- Channels and alternative providers are installed as needed, keeping unselected adapters out of the base checkout.
- OneCLI Agent Vault injects credentials at request time and documents per-agent policies and rate limits.
- It requires Docker, with Windows supported through WSL2, plus Node.js 20+ and pnpm 10+.
- Claude Code is a documented requirement for customization, debugging, setup failure recovery, and all /add-<channel> skills; the native path uses Anthropic's Claude Agent SDK.
- Messaging adapters and alternative providers are not included in trunk by default, so users must run the relevant /add-<name> skill and copy modules into their fork.
- The project intentionally favors source changes instead of configuration files, which may be a poor fit for teams that need declarative configuration management.
- Migrating from v1 requires a fresh v2 checkout and migrate-v2.sh; judgment-dependent steps hand off to Claude Code, and the system service is not switched automatically.
How does this agent compare with similar options?
NanoClaw presents itself as a lightweight alternative to OpenClaw. Its README contrasts OpenClaw's larger code and dependency footprint and shared-memory single-Node-process design with NanoClaw's smaller codebase and per-agent Linux-container filesystem isolation.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| NanoClaw This agent | 58 · Major gaps | CLIFree + model costs | ★ 31k | today | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API · Claude API |
| Hermes Agent Railway Console | 61 · Some gaps | Self-hosted serviceFree + model costs | ★ 325 | 16d ago | Python | Claude API |
| Manifold | 60 · Some gaps | Self-hosted serviceFree | ★ 503 | 16d ago | Go | OpenAI API · Claude API |
| VibePod — Containerized AI Coding Agent Runner | 50 · Major gaps | CLIFree + model costs | ★ 190 | 4d ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: agents run in containers with explicit mounts; credentials injected via OneCLI Agent Vault, not entering container; anonymous diagnostics can be disabled; uninstall requires confirmation. Deductions: user confirmation only in uninstall, not other sensitive operations; data flow transparency has architecture description but lacks implementation details; dependency security relies on version pinning without vulnerability scanning evidence; external effects have uninstall and diagnostics control but not comprehensive.
Evidence shows: architecture description consistent with code structure; CI and tests present; dependencies pinned. Deductions: failure messages only mention Claude Code auto-diagnosis without concrete error handling examples; dependency availability lacks mirror or cache strategy.
Evidence shows: supports multiple channels, providers, customization; trigger word and scheduled tasks; supports macOS/Linux/WSL2. Deductions: capability boundaries not fully listed; environment fit relies on Docker and Claude Code without alternatives.
Evidence shows: README, docs, FAQ, CHANGELOG, MIT license; install and migration scripts. Deductions: known limitations not explicitly listed; maintenance responsibility not clearly stated.
Evidence shows: output as message replies, scheduled tasks and customization; lighter than OpenClaw. Deductions: cost-benefit lacks performance or resource usage data.
Evidence shows: README has architecture description and doc links; tests present. Deductions: claims are assertions without independent verification; facts and inferences not clearly separated.
- Agents run in containers, but review mounts and network config to ensure least privilege.
- Relies on OneCLI Agent Vault; verify its security and availability.
- Install script installs Node, pnpm, Docker, may affect system environment; test in isolated environment.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v2026.10.1-rc.2 Pre-release
Release notes excerpt
NanoClaw 2026.10.1-rc.2 is the second release candidate for 2026.10.1. Installs on the beta channel get this candidate; stable stays on 2026.10.0 until 2026.10.1 is published. Since 2026.10.1-rc.1 it moves OneCLI to 1.45, where new agent groups get only their model key and other keys go to the groups you choose, makes the webhook server listen only on this machine by default, applies egress lockdown to agents that were already running, asks for Node's October 2026 security releases, and lets Claude agents read PDFs; Google Chat now checks that its webhooks come from your app. It also lets …View on GitHub ↗ -
Release notes excerpt
NanoClaw 2026.10.0 is the first release with calendar version numbers and the first one /update-nanoclaw installs by default: updates now follow published releases instead of the tip of main. It was tested first as 2026.10.0-rc.1 and 2026.10.0-rc.2 on the beta channel. It also makes updates and rollbacks more dependable, lets Iron Proxy reach a keyless local model over plain HTTP, routes the service through an outbound proxy when you have one, and shows Claude's own reason when a run fails. Iron Proxy installs need one setup rerun, so check the section below before you update. …View on GitHub ↗