Installation

Complete installation guide for NanoClaw on macOS, Linux, and Windows (WSL).

System requirements

Operating system

macOS
Linux
Windows (WSL)

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

Prerequisites

1. Node.js 20 or later

NanoClaw requires Node.js 20 or later.

macOS
Linux
Windows (WSL)

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

Inside your WSL terminal, use nvm (recommended):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
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
Windows (WSL)

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

Install Claude Code inside WSL using npm:

npm install -g @anthropic-ai/claude-code

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
Windows (WSL) — Docker Desktop

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 macOS, Linux, and Windows (via WSL2).

Docker is the default container runtime and works on macOS, Linux, and Windows (via WSL2).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.

WSL uses Docker Desktop’s WSL 2 backend.

Install Docker Desktop for Windows
Open Docker Desktop Settings > Resources > WSL Integration
Enable integration with your WSL distro (e.g., Ubuntu)
Verify from inside WSL:
```
docker --version
docker info
```

Do not install Docker Engine inside WSL directly — use Docker Desktop’s WSL 2 backend. Installing both causes conflicts.

4. Build tools (for native modules)

NanoClaw uses better-sqlite3, which requires native compilation.

macOS
Linux
Windows (WSL)

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

Same as Linux — run inside your WSL terminal:

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

Verify:

gcc --version
python3 --version

5. OneCLI (v1.2.22+)

Starting in v1.2.22, NanoClaw uses OneCLI for credential management. OneCLI is a local gateway that injects API keys into container traffic without exposing secrets.

curl -fsSL onecli.sh/install | sh
curl -fsSL onecli.sh/cli/install | sh

Verify installation:

onecli version

Run onecli --help to see all available commands for managing secrets and gateway configuration.

OneCLI is also installed automatically by the /setup skill if not already present. It’s listed here so you know about the dependency upfront.

What /setup handles for you: OneCLI installation, npm dependencies, container image build, channel configuration, and service setup. What you need beforehand: Node.js, Claude Code, a container runtime, and build tools.

Installation steps

Once all prerequisites are installed:

Fork and clone the repository

Fork qwibitai/nanoclaw on GitHub, then clone your fork:

git clone https://github.com/<you>/nanoclaw.git
cd nanoclaw

Forking gives you a remote to push your customizations to. A plain git clone works for trying things out — you can migrate to a fork later.

WSL users: Clone into the Linux filesystem (~/nanoclaw), not the Windows mount (/mnt/c/...). File operations on /mnt/c/ are significantly slower due to the 9P filesystem bridge.

Launch Claude Code

claude

Run setup

In Claude Code:

/setup

Claude will handle dependencies, container setup, marketplace plugin installation, and channel configuration automatically.At the end of setup, you’ll be asked about opt-in diagnostics. NanoClaw can send anonymized system info (version, OS, architecture, node version, channels selected) to help improve the project. You can choose Yes, No, or Never ask again. No personally identifiable information is collected.

See the Quick start guide for detailed setup instructions.

Docker sandbox one-liner

If you just want NanoClaw’s Docker sandboxes without the full setup:

macOS / Linux
Windows (WSL)

curl -fsSL https://nanoclaw.dev/install-docker-sandboxes.sh | bash

curl -fsSL https://nanoclaw.dev/install-docker-sandboxes-windows.sh | bash

Package dependencies

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

{
  "dependencies": {
    "@onecli-sh/sdk": "^0.2.0",     // OneCLI gateway integration (v1.2.22+)
    "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
    "yaml": "^2.8.2",              // YAML parsing
    "zod": "^4.3.6"                // Schema validation
  }
}

Channel-specific dependencies (e.g., @whiskeysockets/baileys for WhatsApp, grammy for Telegram) are added when you install a channel skill. Only core dependencies ship on main.

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

Container image

The agent container includes:

Base: Node.js 24 (Debian slim)
Browser: Chromium with CJK and emoji font support
Claude Agent SDK: @anthropic-ai/claude-code (pre-installed)
Tools: agent-browser, bash, git, curl
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

dist

container

groups

main

CLAUDE.md

logs

store

messages.db

auth

data

sessions

logs

nanoclaw.log

nanoclaw.error.log

.env

package.json

External files:

~/.config/nanoclaw/mount-allowlist.json - Mount permissions
~/.config/nanoclaw/sender-allowlist.json - Sender access control (optional)
~/Library/LaunchAgents/com.nanoclaw.plist (macOS) - Service config
~/.config/systemd/user/nanoclaw.service (Linux/WSL with systemd) - 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.getAllRegisteredGroups())"

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

WSL-specific issues

Docker not found in WSL: Ensure Docker Desktop’s WSL integration is enabled (Settings > Resources > WSL Integration). Verify with:

docker --version

If Docker Desktop is running but WSL can’t find it, restart WSL:

# In PowerShell (not WSL)
wsl --shutdown

Slow file operations: If builds or installs are slow, you may have cloned into /mnt/c/. Move to the Linux filesystem:

mv /mnt/c/Users/you/nanoclaw ~/nanoclaw
cd ~/nanoclaw

getuid warnings: On native Windows (without WSL), process.getuid() is unavailable. The container runner handles this gracefully — the warning is informational and can be ignored. Inside WSL, getuid works normally.

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

Changelog

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)

5. OneCLI (v1.2.22+)

Installation steps

Docker sandbox one-liner

Package dependencies

Container image

File structure

Service management

Verification

Troubleshooting

Node.js native module errors

Container build fails

Service won’t start

WSL-specific issues

Docker group permission issues (Linux)

Next steps

Quick start

Security

Customizing

Troubleshooting

Get Started

Core Concepts

Features

Integrations

Advanced

Changelog

​Installation

​System requirements

​Operating system

​Prerequisites

​1. Node.js 20 or later

​2. Claude Code

​3. Container runtime

​4. Build tools (for native modules)

​5. OneCLI (v1.2.22+)

​Installation steps

​Docker sandbox one-liner

​Package dependencies

​Container image

​File structure

​Service management

​Verification

​Troubleshooting

​Node.js native module errors

​Container build fails

​Service won’t start

​WSL-specific issues

​Docker group permission issues (Linux)

​Next steps

Quick start

Security

Customizing

Troubleshooting

Installation

System requirements

Operating system

Prerequisites

1. Node.js 20 or later

2. Claude Code

3. Container runtime

4. Build tools (for native modules)

5. OneCLI (v1.2.22+)

Installation steps

Docker sandbox one-liner

Package dependencies

Container image

File structure

Service management

Verification

Troubleshooting

Node.js native module errors

Container build fails

Service won’t start

WSL-specific issues

Docker group permission issues (Linux)

Next steps