A personal AI assistant that runs securely in Docker containers with peer-to-peer agent networking.
NanoClaw is a lightweight, self-hosted AI assistant you can message via WhatsApp. Each conversation group runs in an isolated Docker container with its own filesystem and memory. Agents can communicate with other AI agents across the internet via Pilot Protocol.
Key features:
- WhatsApp I/O — Message your AI assistant from your phone
- Container isolation — Each group runs in its own Docker sandbox
- Pilot Protocol — Agents discover and message other agents peer-to-peer
- Scheduled tasks — Recurring jobs that run autonomously
- Agent Swarms — Teams of agents collaborating on complex tasks
- Per-group memory — Isolated
CLAUDE.mdmemory per conversation - Extensible via skills — Add Gmail, Telegram, X/Twitter and more
| Dependency | Version | Purpose |
|---|---|---|
| Node.js | 20+ | Host process runtime |
| Docker | Latest | Container runtime for agents |
| socat | Any | Pilot Protocol socket bridge (macOS) |
| Pilot Protocol | Latest | Agent-to-agent networking (optional) |
| Claude Code | Latest | AI-native setup and customization |
macOS (Homebrew):
brew install node socat
# Docker Desktop: https://docker.com/products/docker-desktopLinux (apt):
sudo apt install nodejs npm socat docker.ioPilot Protocol (optional):
curl -fsSL https://raw.githubusercontent.com/TeoSlayer/pilotprotocol/main/install.sh | sh
pilotctl init --registry 34.71.57.205:9000 --beacon 34.71.57.205:9001
pilotctl daemon start --hostname my-agentgit clone https://github.com/gavrielc/nanoclaw.git
cd nanoclaw
claudeThen run /setup. Claude Code handles the rest: dependencies, WhatsApp authentication, container build, and service configuration.
Create a .env file in the project root:
# Authentication (one of these is required)
ANTHROPIC_API_KEY=sk-ant-api03-... # Pay-per-use API key
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-... # Claude subscription token
# Agno agent model (optional, defaults to Claude)
AGNO_MODEL_ID=claude-sonnet-4-5-20250514
AGNO_API_KEY=sk-ant-api03-...
AGNO_BASE_URL=https://api.anthropic.com
AGNO_TEMPERATURE=0.7
AGNO_MAX_TOKENS=4096
# App settings (optional)
ASSISTANT_NAME=Andy # Trigger word (default: Andy)
CONTAINER_TIMEOUT=1800000 # Container timeout in ms (default: 30min)
MAX_CONCURRENT_CONTAINERS=5 # Parallel container limit
LOG_LEVEL=info # debug | info | warn | errorOnly auth variables and
AGNO_*/PILOT_BRIDGE_PORTare passed into containers. Other env vars stay on the host.
# Install host dependencies
npm install
# Build the host process
npm run build
# Build the agent container image
./container-agno/build.shVerify the container:
docker run --rm --entrypoint pilotctl nanoclaw-agent-agno:latest --json contextDevelopment:
npm run devProduction (macOS launchd):
# Install as persistent service
cp launchd/com.nanoclaw.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
# Manage
launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist # stop
launchctl kickstart -k gui/$(id -u)/com.nanoclaw # restartLogs:
tail -f logs/nanoclaw.log # host logs
ls groups/*/logs/container-*.log # per-container logsWhatsApp ──► Node.js host ──► Docker container (Agno agent)
│ │
├── SQLite DB ├── /workspace/group (isolated fs)
├── IPC watcher ├── /workspace/ipc (file-based IPC)
├── Task scheduler ├── pilotctl (Pilot Protocol CLI)
└── socat bridge └── socat ──► host daemon
│
▼
Pilot Protocol daemon ──► P2P overlay network
Host process (src/index.ts): Connects to WhatsApp, routes messages to containers, manages IPC and scheduling.
Agent container (container-agno/): Python + Agno framework. Each group gets its own isolated container with mounted workspace. Includes pilotctl for agent-to-agent communication.
Pilot Protocol bridge: On macOS, Docker runs in a Linux VM so Unix sockets can't cross the boundary. A socat TCP bridge (port 19191) relays between the host daemon socket and containers.
| File | Purpose |
|---|---|
src/index.ts |
WhatsApp connection, message routing, IPC |
src/container-runner.ts |
Container lifecycle, mounts, Pilot bridge |
src/task-scheduler.ts |
Scheduled task execution |
src/db.ts |
SQLite operations |
container-agno/Dockerfile |
Agent image (Python + Agno + pilotctl) |
container-agno/agent-runner/ |
Code that runs inside containers |
container-agno/skills/ |
Skills synced into each agent session |
groups/*/CLAUDE.md |
Per-group persistent memory |
Pilot Protocol gives your agent a permanent address on a P2P encrypted network. Other agents can discover and message yours.
Setup on host:
pilotctl daemon start --hostname my-agent
pilotctl info # show your address and peersInside containers, agents can:
pilotctl --json info # node status
pilotctl send-message other-agent --data "hello" # send message
pilotctl --json inbox # check inbox
pilotctl send-file other-agent /workspace/group/report # send file
pilotctl ping other-agent # test connectivity
pilotctl handshake other-agent "collaboration request" # establish trustThe bridge is automatic — when ~/.pilot/config.json exists on the host, container-runner.ts starts a socat bridge and passes PILOT_BRIDGE_PORT to containers. The container entrypoint creates a local socket so pilotctl works transparently.
Talk to your assistant with 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 message agent-alpha asking for the latest report
From the main channel, manage groups and tasks:
@Andy list all scheduled tasks across groups
@Andy pause the Monday briefing task
@Andy join the Family Chat group
Tell Claude Code what you want:
- "Change the trigger word to @Bob"
- "Make responses shorter and more direct"
- "Add a custom greeting when I say good morning"
Or run /customize for guided changes.
| Skill | Purpose |
|---|---|
/setup |
First-time installation and configuration |
/customize |
Add channels, integrations, modify behavior |
/debug |
Container issues, logs, troubleshooting |
/add-telegram |
Add Telegram channel |
/add-gmail |
Gmail integration |
/x-integration |
X/Twitter integration |
Don't add features. Add skills.
Contribute a skill file (.claude/skills/your-skill/SKILL.md) that teaches Claude Code how to transform a NanoClaw installation. Users run /your-skill and get clean code tailored to their needs.
See existing skills for examples.
/add-slack— Slack channel/add-discord— Discord channel/setup-windows— Windows via WSL2 + Docker
Why WhatsApp?
Because the author uses WhatsApp. Fork it and run a skill to switch. That's the whole point.Can I run this on Linux?
Yes. Run/setup and Docker is configured automatically.
Is this secure?
Agents run in Docker containers with only explicitly mounted directories visible. See docs/SECURITY.md for the full security model.How do I debug issues?
Runclaude, then /debug. Or ask Claude directly: "Why isn't the scheduler running?"
Is Pilot Protocol required?
No. It's optional. Without it, your agent works normally but can't communicate with other agents on the network.Questions? Ideas? Join the Discord.