NanoClaw is a free, open-source personal AI assistant and agent harness that runs AI agents in isolated containers on your own machine. It is built for local agent workflows where filesystem boundaries, owned code, and self-hosted control matter more than a hosted chat dashboard.
The project was created as a lightweight alternative to OpenClaw. OpenClaw relies on application-level permission controls, while NanoClaw keeps a single small host process and places each agent group inside a Linux container.
NanoClaw v2 runs on macOS or Linux, with Windows through WSL2. Docker is the default runtime, and Apple Container is an optional macOS-native runtime.
The installer registers the Anthropic credential with OneCLI, builds the agent container, pairs a first channel, and hands setup failures to Claude Code for diagnosis and recovery.
Features
- Claude Agent SDK base: The system uses Claude Code and Anthropic’s Claude Agent SDK for agent execution, setup recovery, debugging, and customization.
- Container Isolation: Agents run inside Linux containers through Docker by default. macOS installations can opt into Apple Container, and Docker Sandboxes provide a separate micro-VM isolation path.
- On-demand channels: Channel skills can add WhatsApp, Telegram, Discord, Slack, Microsoft Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, and email via Resend.
- Agent group isolation: Each agent group has its own filesystem, memory, container, and conversation context. Provider changes use the shared
memory/tree, and older memory layouts can move through/migrate-memory. - Scheduled Tasks: Use
ncl tasksto list, create, update, pause, resume, run, or delete recurring jobs. Task sessions stay separate from the chat session that created them. - Web Access Tools: Agents can search the web and fetch pages through Claude Code and connected tools.
- Skills-Based Customization: Channel and provider skills modify your fork. Commands such as
/add-telegram,/add-gmail,/add-codex,/add-opencode, and/add-ollama-provideradd specific capabilities. - AI-Native Operations: Claude Code handles setup recovery, configuration changes, customization, and troubleshooting through natural language conversation.
- Container Safety Defaults: New agent containers drop Linux capabilities, set
no-new-privileges, use Docker’s init process, and default to a 2,048-process limit. Installation-wide CPU and memory caps are available through environment variables. - Simple Architecture: One Node.js host process, SQLite state, per-session inbound and outbound databases, and per-agent containers keep the system inspectable.
NanoClaw vs. OpenClaw
NanoClaw targets readers who want OpenClaw-style automation with a local container boundary around each agent group. OpenClaw uses application-level controls for permissions, while NanoClaw relies on Linux containers and explicit filesystem mounts.
OpenClaw puts more of its convenience in a prebuilt ecosystem. NanoClaw puts more of its control in containers, source code, and the skills you install.
Comparison Table
| Feature | NanoClaw | OpenClaw |
|---|---|---|
| Security Model | Containerized. Agents run in Docker by default, or Apple Container as a macOS opt-in. Explicit mounts limit the directories they can see. New containers drop Linux capabilities and set no-new-privileges. | Application Controls. OpenClaw uses application-level permission controls for command and file access. |
| Architecture | Single Host Process. A small Node.js host process coordinates SQLite session databases and per-agent containers. | Large App Stack. OpenClaw uses a larger module and dependency model with more moving parts to inspect. |
| Extensibility | Skill-Installed Code. Channel and provider skills modify your fork, such as /add-telegram, /add-codex, or /add-opencode. | Plugin Ecosystem. OpenClaw relies on a larger prebuilt plugin and skill ecosystem. |
| Configuration | Code-First. You customize behavior in the source code, while group runtime settings live in NanoClaw’s database. | Config-Heavy. OpenClaw exposes more behavior through configuration and permission layers. |
| Channels | Installed on Demand. The installer can pair Telegram, Discord, WhatsApp, or a local CLI first. More channels install through /add-<channel> skills. | Omnichannel. OpenClaw emphasizes broad messaging support inside the main ecosystem. |
Why NanoClaw Uses Containers
OpenClaw uses application-level controls such as allowlists and pairing codes. That model keeps more features in the main installation, along with the permission logic that governs them.
NanoClaw runs each agent group in a container with explicit mounts, and credentials route through OneCLI Agent Vault. Raw credentials do not enter the container. The smaller codebase and on-demand channel model suit a fork that you plan to inspect and customize yourself, with maintenance kept close to the source tree.
Use Cases
- Personal Task Automation: Set up recurring jobs to compile news briefings from multiple sources every morning, review git history weekly and update documentation, or send project status updates at scheduled times.
- Secure Document Processing: Give your assistant access to specific folders, such as an Obsidian vault or project directory, while other host paths stay outside the container mounts.
- Multi-Channel Coordination: Run different isolated contexts for work, family, and personal chats, each with its own memory, session data, and permissions.
- Custom Workflow Integration: Add channel skills for Telegram, Slack, Discord, Gmail, or other messaging surfaces.
- Development Assistant: Have Claude monitor codebases, run tests automatically, and update documentation based on code changes.
How to Use It
NanoClaw requires macOS or Linux, or Windows through WSL2, plus Node.js 20+, pnpm 10+, Docker Desktop on macOS and Windows or Docker Engine on Linux, and Claude Code for setup recovery, customization, debugging, and channel skills. The installer can install Node.js, pnpm, and Docker when they are missing.
Local builds are the default and need no account. NanoClaw also offers an optional prebuilt hardened image; fetching that image requires a free registry account and shares your email address and image request with the registry. Your agents and message data are not part of that request.
Clone the repository and navigate to the directory:
git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2Run the installer:
bash nanoclaw.shThe installer registers your Anthropic credential with OneCLI, builds the agent container, and pairs your first channel. When a setup step fails, Claude Code examines the failure and resumes the setup path.
For a NanoClaw v1 migration, start from a fresh v2 checkout beside the v1 install:
bash migrate-v2.shRun the script directly, not from inside a Claude Code session. It copies state, group folders, session data, scheduled tasks, and selected channel authentication into v2, then hands judgment-heavy steps to Claude Code. Your v1 install stays untouched until you choose the switch to v2.
After setup completes, pair the first channel you want to use. The setup wizard applies the same /add-<channel> skills used for later channel installs. The selected Telegram, Discord, WhatsApp, Slack, or other adapter is copied into your fork.
Talk to your assistant using the trigger word (default: @Andy):
@Andy send an overview of the sales pipeline every weekday morning at 9am
@Andy review the git history for the past week each Friday
@Andy every Monday at 8am, compile news on AI developments and message meFrom a channel you own or administer, manage groups and recurring tasks:
@Andy list all scheduled tasks across groups
@Andy pause the Monday briefing task
@Andy join the Family Chat groupNanoClaw Cheat Sheet
Installation and lifecycle commands
| Command / Option | Purpose |
|---|---|
git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2 | Clone NanoClaw v2. |
cd nanoclaw-v2 | Enter the NanoClaw checkout. |
bash nanoclaw.sh | Install dependencies, register the Anthropic credential with OneCLI, build the agent container, and pair the first channel. |
bash migrate-v2.sh | Migrate a NanoClaw v1 install to v2 while leaving v1 untouched until you switch. |
NANOCLAW_V1_PATH=/path/to/nanoclaw | Point migration at a v1 install path. |
bash nanoclaw.sh --uninstall | Remove this NanoClaw install. |
bash nanoclaw.sh --uninstall --dry-run | Preview uninstall targets. |
bash nanoclaw.sh --uninstall --yes | Uninstall without prompts. |
pnpm exec tsx scripts/upgrade-state.ts set | Stamp the required v2 upgrade marker. |
source setup/lib/install-slug.sh && launchd_label | Show this install’s macOS service name. |
source setup/lib/install-slug.sh && systemd_unit | Show this install’s Linux service name. |
Claude Code slash commands and agent actions
| Command | Purpose |
|---|---|
@Andy ... | Send a task to the assistant. @Andy is the default trigger. |
/customize | Customize behavior, prompts, memory, or code. |
/debug | Debug setup, scheduler, delivery, or runtime issues. |
/setup | Older Claude-guided setup path. Current default is bash nanoclaw.sh. |
/manage-channels | Connect channels to agent groups and choose session isolation. |
/add-<channel> | Add a channel adapter from the channels branch. |
/add-telegram | Add Telegram. |
/add-discord | Add Discord. |
/add-slack | Add Slack. |
/add-whatsapp | Add WhatsApp. |
/add-gmail | Add Gmail when available in your fork. |
/add-gmail-tool | Add the v2-aligned Gmail tool skill when available. |
/add-gcal-tool | Add the v2-aligned Google Calendar tool skill when available. |
/add-codex | Add the Codex provider. |
/add-opencode | Add the OpenCode provider. |
/add-ollama-provider | Add the current Ollama provider path. |
/add-ollama | Older Ollama skill path. |
/convert-to-apple-container | Switch a macOS install to Apple Container. |
/init-onecli | Older OneCLI migration helper for Docker installs. |
/update-nanoclaw | Update NanoClaw through the sanctioned update path. |
/update | Older upstream update skill. |
/migrate-nanoclaw | Replay fork customizations onto a newer base. |
/migrate-memory | Migrate memory between provider stores. |
/migrate-from-v1 | Continue v1-to-v2 migration inside Claude Code. |
/clear | Clear the active conversation context. |
/compact | Compact the active conversation context. |
/cost | Show turn or usage cost information when supported. |
/capabilities | Show container-agent capabilities when installed. |
/status | Show agent status when installed. |
/remote-control | Use host-level Claude Code access when installed. |
/use-local-whisper | Add local Whisper transcription when installed. |
Admin CLI commands
The ncl admin CLI manages NanoClaw’s central database and runtime configuration. Run ncl help in your install before write operations, because command arguments can change across versions.
| Command | Purpose |
|---|---|
ncl help | Show admin CLI usage. |
ncl <resource> list --limit <n> | List resources with a row limit. |
ncl tasks list|create|update|cancel|pause|resume|run|delete|append-log | Manage scheduled tasks and their run logs. |
ncl groups config get | Read a group’s container runtime config. |
ncl groups config update --provider <provider> | Set a group’s provider. |
ncl groups config update --model <model> --effort <level> | Set a group’s Claude model and effort level. |
ncl groups config update --timezone <IANA> | Set a timezone for one agent group. |
ncl groups config add-mcp-server | Add an MCP server to a group. |
ncl groups config remove-mcp-server | Remove an MCP server from a group. |
ncl groups config add-package | Add a package to a group. |
ncl groups config remove-package | Remove a package from a group. |
ncl groups restart | Restart an agent group. |
ncl groups restart --rebuild | Restart and rebuild a group container. |
ncl groups restart --message "<message>" | Restart a group with an on-wake message. |
ncl destinations add | Add a destination through the approval flow. |
ncl destinations remove | Remove a destination through the approval flow. |
ncl sessions get | Read session data within allowed scope. |
Configuration options and environment variables
| Option | Purpose |
|---|---|
CONTAINER_CPU_LIMIT | Set an installation-wide Docker CPU cap, such as 2. It is empty by default. |
CONTAINER_MEMORY_LIMIT | Set an installation-wide Docker memory cap, such as 8g. It is empty by default. |
CONTAINER_PIDS_LIMIT | Set the container process limit. The default is 2048; 0 disables the limit. |
DEFAULT_AGENT_PROVIDER | Set the provider for new groups that have no explicit provider. |
provider | Set group provider: claude, codex, opencode, or ollama. |
model | Set a group-specific model. |
effort | Set a group-specific effort level. |
cli_scope | Set container CLI access: disabled, group, or global. |
session_mode | Set channel isolation: separate agent, shared, or agent-shared. |
on_wake | Send a message to a freshly restarted container. |
ANTHROPIC_BASE_URL | Use a Claude-compatible custom endpoint. |
ANTHROPIC_AUTH_TOKEN | Set token for a Claude-compatible endpoint. |
NANOCLAW_V1_PATH | Point migration at a v1 install. |
com.nanoclaw.<slug> | macOS per-install service label pattern. |
nanoclaw-<slug>.service | Linux per-install service unit pattern. |
Most day-to-day control still happens through natural-language messages. You can ask @Andy to join a chat group, inspect logs, or change the trigger word. Use ncl tasks when you need direct control over scheduled task records and runs.
Alternatives & Related Resources
- 7 Best OpenClaw Alternatives for Safe & Local AI Agents
- Automate Anything: 10 Best & Open-source AI Agents
- Most Popular Agent Skills on GitHub for Coding Agents
- NanoClaw Website: Project website for product information and documentation links.
- NanoClaw Docs: Documentation for setup, security, architecture, and operation.
- Claude Agent SDK Documentation: Documentation for the underlying agent SDK used by NanoClaw.
- Docker Desktop: Docker runtime for macOS, Windows, and Linux.
- Claude Code Download: Claude Code installer for setup recovery, debugging, and customization.
- OpenClaw Alternatives: Related ScriptByAI pages for OpenClaw-style assistants and alternatives.
Pros
- Explicit container mounts.
- Single Node.js host process.
- Channel skills keep forks lean.
- Local builds need no account.
Cons
- Docker or WSL2 setup.
- Claude Code required for skills.
- Channels install on demand.
FAQs
Q: What is NanoClaw?
A: NanoClaw is a free, open-source personal AI assistant and agent harness. It runs agent groups in isolated containers on your computer or server and connects them to messaging channels such as Telegram, Discord, WhatsApp, or a local CLI.
Q: Is NanoClaw free and open source?
A: Yes. NanoClaw is released under the MIT license, and a local build needs no NanoClaw account. You still need an AI provider, such as Anthropic’s Claude or an installed alternative provider, and provider usage can have separate costs. The optional prebuilt hardened image requires a free registry account.
Q: How is NanoClaw different from OpenClaw?
A: NanoClaw uses one small Node.js host process and per-agent Linux containers with explicit mounts. OpenClaw uses application-level permission controls and a larger prebuilt ecosystem. NanoClaw puts more customization in your fork and installed skills.
Q: Does NanoClaw have an Android APK?
A: NanoClaw is a self-hosted runtime for a computer or server, not an Android APK or mobile app. You can talk to the assistant through WhatsApp or Telegram after installing the relevant channel.
Q: Can NanoClaw run on Linux, Ubuntu, or Windows?
A: Yes. NanoClaw runs on macOS and Linux, and Windows through WSL2. Use Docker Desktop on macOS and Windows or Docker Engine on Linux, together with Node.js 20+, pnpm 10+, and Claude Code.
Q: Can NanoClaw run without Claude Code?
A: The default setup uses Claude Code for setup recovery, /customize, /debug, and channel skills. You can add Codex, OpenCode, or Ollama as a provider for an agent group, but those provider paths do not replace Claude Code for the guided setup and skill workflows.
Q: Does NanoClaw support WhatsApp, Telegram, Discord, and Slack?
A: Yes. The setup wizard and the /add-<channel> skills install channel adapters on demand. You can start with Telegram, Discord, WhatsApp, or a local CLI, then add Slack and other channels to your fork.
Q: Can NanoClaw use Codex, OpenCode, or Ollama?
A: Yes. Install /add-codex, /add-opencode, or /add-ollama-provider and choose the provider per agent group. Codex uses OpenAI’s Codex runtime, OpenCode routes through its configured providers, and Ollama connects local open-weight models.
Q: How does NanoClaw manage scheduled tasks?
A: Use ncl tasks to list, create, update, cancel, pause, resume, run, or delete tasks. Each task session stays separate from the chat session that created it, and delivery calls need a named destination.
Q: Can NanoClaw run on a server?
A: Yes. NanoClaw is self-hosted. A Linux server with Docker Engine, Node.js, pnpm, and Claude Code can run it. You manage the host, Docker runtime, channels, and provider credentials yourself.
Last Updated: August 1, 2026
