Codakey
Play
← Back to nanoclaw

How to Deploy & Use nanoclaw

NanoClaw Deployment & Usage Guide

1. Prerequisites

Runtime & Tools:

  • Node.js (v18 or later) - Required for the TypeScript application
  • Git - For cloning the repository
  • Claude Code - The primary interface for setup and management (run claude in terminal)
  • Container runtime (choose one):
    • Apple Container (macOS) - Built-in on macOS
    • Docker (macOS/Linux) - For Linux or macOS with Docker
    • WSL2 + Docker (Windows) - For Windows users (requires skill)

Accounts & API Keys:

  • Anthropic API key - For Claude Agent SDK access
  • WhatsApp account - For WhatsApp connectivity (primary channel)
  • Optional: Telegram/Slack/Discord accounts for additional channels (via skills)

Platform Support:

  • macOS (primary) - Native Apple Container support
  • Linux - Docker-based containerization
  • Windows - Requires WSL2 + Docker (via /setup-windows skill)

2. Installation

# Clone the repository
git clone https://github.com/qwibitai/nanoclaw.git
cd nanoclaw

# Start Claude Code for guided setup
claude

Once Claude Code starts, run:

/setup

Claude Code will handle:

  • Installing Node.js dependencies
  • Setting up container runtime (Apple Container on macOS, Docker otherwise)
  • Configuring environment variables
  • Setting up database and data directories
  • Configuring WhatsApp authentication

Alternative Manual Setup:

# Install dependencies
npm install

# Build the TypeScript project
npm run build

# Initialize database and directories
npm run init

3. Configuration

Environment Variables: Create a .env file in the project root:

# Required: Anthropic API
ANTHROPIC_API_KEY=your_claude_api_key_here

# Required: WhatsApp
WHATSAPP_SESSION_DIR=./data/whatsapp-sessions

# Optional: Telegram (if using /add-telegram skill)
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_ONLY=false  # Set true to use Telegram instead of WhatsApp

# Optional: Discord (if using /add-discord skill)
DISCORD_BOT_TOKEN=your_discord_bot_token_here
DISCORD_ONLY=false

# Container Configuration
CONTAINER_IMAGE=node:20-alpine  # Default container image
CONTAINER_TIMEOUT=300000  # 5 minutes timeout
CONTAINER_MAX_OUTPUT_SIZE=1000000  # 1MB output limit

# Application Settings
ASSISTANT_NAME=Andy  # Default trigger: @Andy
TRIGGER_PATTERN=@Andy  # Change to customize trigger word
POLL_INTERVAL=2000  # Message polling interval in ms
IDLE_TIMEOUT=3600000  # 1 hour idle timeout

# Paths
DATA_DIR=./data
STORE_DIR=./data/store
GROUPS_DIR=./data/groups

Directory Structure:

nanoclaw/
├── data/                    # Auto-created
│   ├── store/              # SQLite database
│   ├── groups/             # Per-group isolated filesystems
│   └── whatsapp-sessions/  # WhatsApp authentication
├── container/              # Container agent runner
├── src/                    # Main application source
└── .claude/skills/         # Customization skills

Group Configuration: Each chat group gets its own isolated environment:

  • CLAUDE.md file in group folder for persistent memory
  • Isolated filesystem mounted to container
  • Separate session management

4. Build & Run

Development Mode:

# Build TypeScript
npm run build

# Or watch mode for development
npm run watch

# Start the application
npm start

Production Mode:

# Build optimized version
npm run build:prod

# Start with process manager (recommended)
npm run start:prod

# Or use PM2 for production
npm install -g pm2
pm2 start dist/index.js --name nanoclaw

Container Agent Runner: The agent runner builds automatically, but you can rebuild manually:

cd container/agent-runner
npm install
npm run build

Using Claude Code for Management:

# Start Claude Code interface
claude

# Available commands:
/setup          # Initial setup wizard
/customize      # Guided customization
/add-telegram   # Add Telegram support (skill)
/add-gmail      # Add Gmail integration (skill)
/list-tasks     # View scheduled tasks

5. Deployment

Recommended Platforms:

  1. Personal Server/VPS (Primary):

    # On Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm docker.io git

# Clone and setup
git clone https://github.com/qwibitai/nanoclaw.git
cd nanoclaw
npm install
npm run build

# Run as systemd service
sudo nano /etc/systemd/system/nanoclaw.service

    Systemd service file:

    [Unit]
Description=NanoClaw Assistant
After=network.target docker.service

[Service]
Type=simple
User=yourusername
WorkingDirectory=/path/to/nanoclaw
Environment="ANTHROPIC_API_KEY=your_key"
ExecStart=/usr/bin/npm start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

  2. Docker Deployment:

    # Build Docker image
docker build -t nanoclaw .

# Run with environment variables
docker run -d \
  --name nanoclaw \
  -v $(pwd)/data:/app/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e ANTHROPIC_API_KEY=your_key \
  -e WHATSAPP_SESSION_DIR=/app/data/whatsapp-sessions \
  nanoclaw

  3. Cloud Platforms:

    • Fly.io (Recommended for containerized apps):

      # Install flyctl
curl -L https://fly.io/install.sh | sh

# Launch
fly launch
fly secrets set ANTHROPIC_API_KEY=your_key
fly deploy

    • Railway.app:

      # Connect via CLI
railway init
railway up

  4. Home Lab/NAS:

    • Run on Synology DSM (Docker package)
    • Unraid Docker containers
    • Proxmox LXC container

Important Deployment Notes:

  • WhatsApp requires persistent session storage (mount ./data/whatsapp-sessions)
  • Container runtime must be accessible (Docker socket mount for Docker)
  • Ensure sufficient disk space for group isolation (each group gets its own folder)
  • Regular backups of ./data/store directory (SQLite database)

6. Troubleshooting

Common Issues:

  1. WhatsApp Authentication Fails:

    # Clear WhatsApp sessions and retry
rm -rf ./data/whatsapp-sessions/*
# Restart and run QR scan again

  2. Container Startup Errors:

    # Check container runtime
docker ps  # or: apple-container list

# Rebuild agent runner
cd container/agent-runner
npm run build

  3. Database Corruption:

    # Backup and recreate
cp ./data/store/db.sqlite ./data/store/db.sqlite.backup
rm ./data/store/db.sqlite
npm run init

  4. Memory/Performance Issues:

    # Check container resource limits
# Adjust in src/config.js:
CONTAINER_MAX_OUTPUT_SIZE=500000  # Reduce from 1MB
CONTAINER_TIMEOUT=180000  # Reduce from 5 minutes

  5. Trigger Word Not Working:

    # Check configuration
grep TRIGGER_PATTERN .env
# Default is "@Andy", change to your preference

  6. Scheduled Tasks Not Running:

    # Check task scheduler status
# From main channel (self-chat):
@Andy list all scheduled tasks across groups

# Or check database directly:
sqlite3 ./data/store/db.sqlite "SELECT * FROM scheduled_tasks;"

  7. Web Access/Search Fails:

    # Ensure network connectivity in containers
# Check container DNS settings
docker exec -it nanoclaw-container nslookup google.com

Logs & Debugging:

# Application logs
tail -f logs/nanoclaw.log

# Container logs (if using Docker)
docker logs nanoclaw-container

# Enable verbose logging
export DEBUG=nanoclaw:*
npm start

# Check Claude Agent SDK connectivity
curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":10,"messages":[{"role":"user","content":"test"}]}'

Getting Help:

← Project overviewView alternatives to nanoclaw →