Installation

Complete installation guide for NanoClaw on macOS and Linux.

System requirements

Operating system

macOS
Linux

macOS 11 (Big Sur) or later
Intel or Apple Silicon (M1/M2/M3)
4GB RAM minimum, 8GB recommended
2GB free disk space

Windows is not officially supported. You can use WSL2 (Windows Subsystem for Linux) with Ubuntu.

Prerequisites

1. Node.js 20 or later

NanoClaw requires Node.js 20 or later.

macOS
Linux

Using Homebrew (recommended):

brew install node@22

Using nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22

Verify installation:

node --version  # Should show v20.x or higher

Using NodeSource:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Using nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22

Verify installation:

node --version  # Should show v20.x or higher

2. Claude Code

Claude Code is required to run the /setup command and customize NanoClaw. Download from: claude.ai/download

macOS
Linux

Download Claude Code for macOS
Open the DMG file
Drag Claude Code to Applications
Launch Claude Code
Sign in with your Anthropic account

Verify installation:

claude --version

Download Claude Code for Linux (.deb or .AppImage)

Install the package:

sudo dpkg -i claude-code_*.deb
# or run the AppImage directly

Launch Claude Code
Sign in with your Anthropic account

Verify installation:

claude --version

You need a Claude Pro or Claude Team subscription, or an Anthropic API key.

3. Container runtime

Agents run in isolated containers. You need either Apple Container (macOS only) or Docker.

Apple Container (macOS)
Docker

Apple Container is a lightweight, native macOS container runtime.Installation:

brew install container

Verify:

container --version

Benefits:

Native macOS integration
Lighter resource usage than Docker
Faster startup times

Apple Container is macOS-only. During setup, you can choose between Apple Container and Docker. Docker is the default and works on both macOS and Linux.

Docker is the default container runtime and works on both macOS and Linux.macOS:

# Using Homebrew
brew install --cask docker

# Start Docker Desktop
open -a Docker

Linux:

# Install Docker
curl -fsSL https://get.docker.com | sh

# Add your user to the docker group
sudo usermod -aG docker $USER

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Log out and back in for group changes to take effect

Verify:

docker --version
docker info

On Linux, after adding yourself to the docker group, you must log out and back in for the changes to take effect.

4. Build tools (for native modules)

NanoClaw uses better-sqlite3, which requires native compilation.

macOS
Linux

Install Xcode Command Line Tools:

xcode-select --install

Verify:

gcc --version

Install build essentials:

sudo apt-get update
sudo apt-get install -y build-essential python3

Verify:

gcc --version
python3 --version

Installation steps

Once all prerequisites are installed:

Clone the repository

git clone https://github.com/qwibitai/NanoClaw.git
cd NanoClaw

Launch Claude Code

claude

Run setup

In Claude Code:

/setup

Claude will handle the rest automatically.

See the Quick start guide for detailed setup instructions.

Package dependencies

NanoClaw uses these core dependencies (from package.json):

{
  "dependencies": {
    "@whiskeysockets/baileys": "^7.0.0-rc.9",  // WhatsApp Web API
    "better-sqlite3": "^11.8.1",                // SQLite database
    "cron-parser": "^5.5.0",                    // Task scheduling
    "pino": "^9.6.0",                           // Logging
    "pino-pretty": "^13.0.0",                   // Log formatting
    "qrcode": "^1.5.4",                         // QR code generation
    "qrcode-terminal": "^0.12.0",               // Terminal QR codes
    "yaml": "^2.8.2",                           // YAML parsing
    "zod": "^4.3.6"                             // Schema validation
  }
}

All dependencies are installed automatically by /setup via npm install.

Container image

The agent container includes:

Base: Node.js 22 Alpine Linux
Claude Agent SDK: Pre-installed
Tools: bash, git, curl, jq
User: Non-root node user (uid 1000)

The container is built during setup:

./container/build.sh

This creates the nanoclaw-agent image.

File structure

After installation, NanoClaw creates:

NanoClaw/
├── src/                    # Source code
├── dist/                   # Compiled JavaScript
├── container/              # Container build files
├── groups/                 # Per-group data
│   └── main/              # Main channel
│       ├── CLAUDE.md      # Group memory
│       └── logs/          # Container logs
├── store/                  # WhatsApp session
│   └── auth/              # Authentication data
├── data/                   # SQLite database
│   ├── nanoclaw.db        # Messages, groups, tasks
│   └── sessions/          # Claude sessions per group
├── logs/                   # Application logs
│   ├── nanoclaw.log       # Main log
│   └── nanoclaw.error.log # Error log
├── .env                    # Credentials (not in git)
└── package.json           # Dependencies

External files:

~/.config/nanoclaw/mount-allowlist.json - Mount permissions
~/Library/LaunchAgents/com.nanoclaw.plist (macOS) - Service config
~/.config/systemd/user/nanoclaw.service (Linux) - Service config

Service management

NanoClaw runs as a background service:

macOS (launchd)
Linux (systemd)
WSL (without systemd)

# Start service
launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist

# Stop service
launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist

# Restart service
launchctl kickstart -k gui/$(id -u)/com.nanoclaw

# Check status
launchctl list | grep nanoclaw

# View logs
tail -f ~/workspace/NanoClaw/logs/nanoclaw.log

# Start service
systemctl --user start nanoclaw

# Stop service
systemctl --user stop nanoclaw

# Restart service
systemctl --user restart nanoclaw

# Check status
systemctl --user status nanoclaw

# Enable on boot
systemctl --user enable nanoclaw

# View logs
journalctl --user -u nanoclaw -f

If your WSL doesn’t have systemd enabled:

# Start service
bash start-nanoclaw.sh

# Stop service
pkill -f "node dist/index.js"

# View logs
tail -f logs/nanoclaw.log

To enable systemd in WSL:

echo -e "[boot]\nsystemd=true" | sudo tee /etc/wsl.conf
# Restart WSL

Verification

Verify your installation:

# Check service is running
# macOS
launchctl list | grep nanoclaw

# Linux
systemctl --user status nanoclaw

# Check logs
tail -f logs/nanoclaw.log

# Test database
node -e "const db=require('./dist/db.js');console.log(db.getGroups())"

Or ask Claude Code:

/debug

Troubleshooting

Node.js native module errors

# Rebuild native modules
npm rebuild

# Or reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Container build fails

# Clear build cache
# Docker
docker builder prune -f

# Apple Container
container builder stop
container builder rm
container builder start

# Rebuild
./container/build.sh

Service won’t start

macOS
Linux

# Check error logs
cat logs/nanoclaw.error.log

# Verify Node.js path
which node

# Ensure .env exists
ls -la .env

# Rebuild and restart
npm run build
launchctl kickstart -k gui/$(id -u)/com.nanoclaw

# Check service status
systemctl --user status nanoclaw

# View logs
journalctl --user -u nanoclaw -n 50

# Verify Docker access
docker ps

# Rebuild and restart
npm run build
systemctl --user restart nanoclaw

Docker group permission issues (Linux)

If you see “permission denied” errors:

# Immediate fix
sudo setfacl -m u:$USER:rw /var/run/docker.sock

# Persistent fix
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/socket-acl.conf << EOF
[Service]
ExecStartPost=/usr/bin/setfacl -m u:$USER:rw /var/run/docker.sock
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

Next steps

Quick start

Complete the setup process

Security

Learn about container isolation

Customizing

Modify NanoClaw for your needs

Troubleshooting

Fix common issues

Get Started

Core Concepts

Features

Integrations

Advanced

Installation

Installation

System requirements

Operating system

Prerequisites

1. Node.js 20 or later

2. Claude Code

3. Container runtime

4. Build tools (for native modules)

Installation steps

Package dependencies

Container image

File structure

Service management

Verification

Troubleshooting

Node.js native module errors

Container build fails

Service won’t start

Docker group permission issues (Linux)

Next steps

Quick start

Security

Customizing

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Integrations

Advanced

​Installation

​System requirements

​Operating system

​Prerequisites

​1. Node.js 20 or later

​2. Claude Code

​3. Container runtime

​4. Build tools (for native modules)

​Installation steps

​Package dependencies

​Container image

​File structure

​Service management

​Verification

​Troubleshooting

​Node.js native module errors

​Container build fails

​Service won’t start

​Docker group permission issues (Linux)

​Next steps

Quick start

Security

Customizing

Troubleshooting

Build docs developers (and LLMs) love

Installation

System requirements

Operating system

Prerequisites

1. Node.js 20 or later

2. Claude Code

3. Container runtime

4. Build tools (for native modules)

Installation steps

Package dependencies

Container image

File structure

Service management

Verification

Troubleshooting

Node.js native module errors

Container build fails

Service won’t start

Docker group permission issues (Linux)

Next steps