This guide covers the full installation process, from requirements to running your first agent.
Requirements
Platform
macOS or Linux
Windows via WSL2 is supported
Authentication
Claude Code subscription (Pro/Max), or
Anthropic API key
Installation Methods The /setup command in Claude Code handles everything automatically.
Clone and open
git clone https://github.com/andrewsiah/nanoclaw-pro.git cd nanoclaw-pro claude
Run setup
In Claude Code: The setup will:
Check for Node.js 20+ and install if needed
Run npm install and build dependencies
Detect or install container runtime (Docker/Apple Container)
Build the agent container image
Configure Claude authentication
Set up your messaging channel
Configure directory access permissions
Start the background service
Verify installation
The setup automatically verifies:
✓ Service is running
✓ Container runtime is available
✓ Authentication is configured
✓ At least one channel is registered
✓ Mount allowlist is configured
You can manually verify anytime: npx tsx setup/index.ts --step verify
Install Node.js
macOS (Homebrew)
Linux (apt)
Using nvm
Verify installation: node --version # Should be v20.0.0 or higher
Clone repository
git clone https://github.com/andrewsiah/nanoclaw-pro.git cd nanoclaw-pro
Install dependencies
npm install npm run build
If you encounter build errors for better-sqlite3, install build tools: Then retry npm install.
Install container runtime
Build container image
This builds the nanoclaw-agent:latest image that runs Claude Code in an isolated container. If you switched to Apple Container, the build script automatically detects and uses the container CLI.
Continue with automated setup
Even with manual installation, use /setup in Claude Code to complete:
Claude authentication
Messaging channel configuration
Service installation
Authentication Setup NanoClaw supports two authentication methods:
If you have Claude Pro or Claude Max:
Generate OAuth token
In a separate terminal (not Claude Code), run: This generates an OAuth token from your Claude subscription.
Copy the token
The command outputs a token starting with sk-ant-oat01-... Copy this token.
Add to .env file
Create or edit .env in your project root: CLAUDE_CODE_OAUTH_TOKEN = sk-ant-oat01-...
Do not commit .env to git. It’s already in .gitignore.
If you want pay-per-use pricing:
Add to .env file
Create or edit .env in your project root: ANTHROPIC_API_KEY = sk-ant-api03-...
Only authentication variables (CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY) are passed to containers. Other environment variables in .env are not exposed to agents.
Channel Setup NanoClaw uses a skill-based channel system. Each messaging platform is added via a Claude Code skill:
WhatsApp Authenticates via QR code or pairing code
Telegram Requires bot token from @BotFather
Discord Requires Discord bot token
Slack Uses Slack app with Socket Mode
Gmail OAuth-based email integration The /setup command prompts you to select channels and runs the appropriate skills automatically.
Starting the Service NanoClaw runs as a background service that polls for messages and executes scheduled tasks.
macOS
Linux
WSL2
Development
The service is managed by launchd: # Install service cp launchd/com.nanoclaw.plist ~/Library/LaunchAgents/ # Start service launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist # Check status launchctl list | grep nanoclaw # Restart service launchctl kickstart -k gui/ $( id -u ) /com.nanoclaw # Stop service launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
View logs: tail -f logs/nanoclaw.log tail -f logs/nanoclaw.error.log
The service is managed by systemd: # Start service systemctl --user start nanoclaw # Check status systemctl --user status nanoclaw # Restart service systemctl --user restart nanoclaw # Stop service systemctl --user stop nanoclaw # View logs journalctl --user -u nanoclaw -f
If running as root (not recommended): systemctl start nanoclaw # omit --user flag
If WSL doesn’t have systemd enabled:
Enable systemd (recommended):
echo -e "[boot]\nsystemd=true" | sudo tee /etc/wsl.conf
Then restart WSL and use the Linux systemd commands.
Or use the generated wrapper script:
Run directly without installing as a service: This runs with hot reload and verbose logging. Troubleshooting
Error : bash setup.sh shows NODE_OK: falseSolution : Install Node.js 20 or higher:# macOS brew install node@22 # Linux curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs # Or use nvm nvm install 22 && nvm use 22
better-sqlite3 build fails
Error : NATIVE_OK: false during setupSolution : Install build tools:# macOS xcode-select --install # Linux sudo apt-get install build-essential
Then: rm -rf node_modules package-lock.json npm install
Error : docker info fails or container build failsSolution :# macOS open -a Docker # Wait 15 seconds for Docker to start # Linux sudo systemctl start docker # Verify docker info
Container build cache issues
Error : Stale files in container after rebuildSolution : Prune the builder cache:# Docker docker builder prune -f ./container/build.sh # Apple Container container builder stop container builder rm container builder start ./container/build.sh
Error : Service loads but doesn’t process messagesSolution : Check logs and verify configuration:# View error logs tail -f logs/nanoclaw.error.log # Verify setup npx tsx setup/index.ts --step verify # Common issues: # - Missing .env file # - Wrong Node.js path in service file # - Missing channel credentials
Rebuild and restart: npm run build # macOS launchctl kickstart -k gui/ $( id -u ) /com.nanoclaw # Linux systemctl --user restart nanoclaw
Error : Claude Code process exited with code 1 in logsCauses :
Container runtime not running
Wrong session mount path
Missing authentication
Solution :# 1. Ensure runtime is running docker info # or: container system start # 2. Check container logs cat groups/ * /logs/container- * .log # 3. Verify .env has authentication cat .env | grep -E 'CLAUDE_CODE_OAUTH_TOKEN|ANTHROPIC_API_KEY'
Linux Docker socket permissions
Error : permission denied while trying to connect to the Docker daemon socketSolution : Add your user to the docker group:sudo usermod -aG docker $USER
Then log out and back in. If using systemd and the error persists: # Immediate fix sudo setfacl -m u: $( whoami ) :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:USERNAME:rw /var/run/docker.sock EOF # Replace USERNAME with your username sudo systemctl daemon-reload
Next Steps
First Conversation Learn how to interact with your assistant
Proactive Agent Enable morning check-ins and afternoon follow-ups
Memory System How NanoClaw remembers context
Customization Tailor NanoClaw to your needs
