Welcome to NanoClaw
NanoClaw is a personal Claude assistant that runs agents securely in their own containers. It’s lightweight, built to be easily understood, and completely customizable for your needs.Using Claude Code, NanoClaw can dynamically rewrite its code to customize its feature set for your needs.
Why NanoClaw?
NanoClaw provides the core functionality of complex AI assistants, but in a codebase small enough to understand: one process and a handful of files. Claude agents run in their own Linux containers with filesystem isolation, not merely behind permission checks.Quick start
Get NanoClaw running in minutes with Claude Code handling setup
Installation
Detailed installation instructions for macOS and Linux
Security
Learn about container isolation and security boundaries
Architecture
Understand how NanoClaw works under the hood
Architecture
Understand how NanoClaw works under the hood
Key features
Container isolation
Agents run in Linux containers (Apple Container on macOS, or Docker) with true filesystem isolation. They can only see what’s explicitly mounted.Multi-messenger support
Message NanoClaw from your phone via:- WhatsApp (default)
- Telegram (via
/add-telegram) - Discord (via
/add-discord) - Slack (via
/add-slack) - Gmail (via
/add-gmail)
Isolated group context
Each group has its own:CLAUDE.mdmemory file- Isolated filesystem
- Separate container sandbox with only that filesystem mounted
Agent swarms
NanoClaw is the first personal AI assistant to support Agent Swarms. Spin up teams of agents that collaborate in your chat.
Scheduled tasks
Set up recurring jobs that run Claude and message you back:Philosophy
Small enough to understand
One process, a few source files and no microservices. Ask Claude Code to walk you through the entire codebase.
Secure by isolation
Agents run in Linux containers and can only see what’s explicitly mounted. Bash access is safe because commands run inside the container, not on your host.
Built for the individual user
NanoClaw isn’t a monolithic framework; it’s software that fits each user’s exact needs. Make your own fork and have Claude Code modify it to match your needs.
Customization = code changes
No configuration sprawl. Want different behavior? Modify the code. The codebase is small enough that it’s safe to make changes.
AI-native
No installation wizard; Claude Code guides setup. No monitoring dashboard; ask Claude what’s happening. No debugging tools; describe the problem and Claude fixes it.
Skills over features
Instead of adding features to the codebase, contributors submit Claude Code skills like
/add-telegram that transform your fork. You end up with clean code that does exactly what you need.Core architecture
NanoClaw is built with simplicity in mind:- Single Node.js process - No microservices or complex orchestration
- SQLite database - Per-group message queue with concurrency control
- Container runtime - Apple Container (macOS) or Docker (macOS/Linux)
- Claude Agent SDK - Runs Claude Code directly in containers
- IPC via filesystem - Simple, reliable inter-process communication
Codebase size: 34.9k tokens (17% of Claude’s context window). Small enough to understand completely.
Key source files
| File | Purpose |
|---|---|
src/index.ts | Orchestrator: state, message loop, agent invocation |
src/channels/whatsapp.ts | WhatsApp connection, auth, send/receive |
src/ipc.ts | IPC watcher and task processing |
src/router.ts | Message formatting and outbound routing |
src/group-queue.ts | Per-group queue with global concurrency limit |
src/container-runner.ts | Spawns streaming agent containers |
src/task-scheduler.ts | Runs scheduled tasks |
src/db.ts | SQLite operations (messages, groups, sessions, state) |
groups/*/CLAUDE.md | Per-group memory |
Get started
Quick start guide
Start using NanoClaw in 5 minutes
Installation details
Complete installation requirements and setup