Installation

Everything you need to know before running bash nanoclaw.sh. For the one-command install flow itself, see Quick start.

System requirements

macOS
Linux
Windows (WSL2)

macOS 12 (Monterey) or later
Intel or Apple Silicon (M1/M2/M3/M4)
4 GB RAM minimum, 8 GB recommended
4 GB free disk space (container image + node_modules)

What the installer needs

nanoclaw.sh installs most things for you. This list exists so you know the dependency surface before running it.

Dependency	Scope	Installer handles it?
Node 22	Host (orchestrator)	Yes — via nvm if missing
pnpm 10	Host (package manager)	Yes — via `corepack enable`
Docker (or Apple Container)	Host (container runtime)	Partial — prompts you to install or start it if absent
Build tools (gcc, python3)	Host (for `better-sqlite3` native compile)	No — install beforehand
OneCLI Agent Vault	Host (credential injection)	Yes — installs locally or reuses an existing configured instance
Bun 1.3.12	Container (agent-runner runtime)	Yes — baked into the agent container image

Build tools

better-sqlite3 is the only host dependency that needs native compilation. Install the platform toolchain before running nanoclaw.sh:

macOS
Linux
Windows (WSL2)

xcode-select --install

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

Same as Linux, inside your WSL terminal:

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

Container runtime

Docker is the default and works on all three platforms. Apple Container is an opt-in alternative on macOS 15+.

Docker (default)
Apple Container (macOS 15+)

macOS:

brew install --cask docker
open -a Docker

Linux:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
sudo systemctl enable --now docker
# Log out and back in for group membership to take effect

Windows (WSL2): Install Docker Desktop, then enable WSL integration in Settings → Resources → WSL Integration for your distro.

WSL users: do not install Docker Engine inside WSL directly. Use Docker Desktop’s WSL 2 backend. Installing both causes conflicts.

Lightweight native macOS runtime. Opt-in after setup via /convert-to-apple-container.

brew install container
container --version

The default installer picks Docker. To switch, run /convert-to-apple-container after NanoClaw is running. The skill modifies the runtime integration and uses git revert as the rollback path.

Advanced installer environment

nanoclaw.sh and setup:auto read environment variables when you need to debug or script part of setup.

Env var	Use
`NANOCLAW_SKIP`	Comma-separated setup steps to skip while debugging (`environment`, `container`, `onecli`, `auth`, `mounts`, `service`, `cli-agent`, `timezone`, `channel`, `verify`, `first-chat`)
`NANOCLAW_DISPLAY_NAME`	Skip the operator display-name prompt
`NANOCLAW_AGENT_NAME`	Set the messaging-channel agent name; the CLI scratch agent remains `Terminal Agent`
`SECRET_NAME`	OneCLI secret name for `setup/register-claude-token.sh` (default: `Anthropic`)
`HOST_PATTERN`	OneCLI host pattern for `setup/register-claude-token.sh` (default: `api.anthropic.com`)

If OneCLI is already installed and configured, setup asks whether to reuse it. For custom Anthropic-compatible model endpoints, set ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN in .env.

Run the installer

Once the system dependencies above are in place:

git clone https://github.com/qwibitai/nanoclaw.git
cd nanoclaw
bash nanoclaw.sh

The installer walks through bootstrap, container build, OneCLI credential registration, channel pairing, and service installation. Progress streams to your terminal; full per-step logs land in logs/setup.log and logs/setup-steps/. For the step-by-step breakdown of what each phase does, see Quick start.

File structure after install

nanoclaw

src

container

groups

main

CLAUDE.md

container.json

data

v2.db

env

v2-sessions

{agent_group_id}

{session_id}

inbound.db

outbound.db

.heartbeat

logs

.env

nanoclaw.sh

package.json

External files (outside the project directory):

Path	Purpose
`~/.config/nanoclaw/mount-allowlist.json`	Which host directories agents can mount
`~/.config/nanoclaw/sender-allowlist.json`	Optional per-channel sender access control
`~/Library/LaunchAgents/com.nanoclaw-v2-<slug>.plist` (macOS)	launchd service definition
`~/.config/systemd/user/nanoclaw-v2-<slug>.service` (Linux)	systemd user-service definition

Container image contents

The agent container image is scoped per checkout, with a name like nanoclaw-agent-v2-<slug>:latest. It is built from container/Dockerfile:

Base: node:22-slim
tini as PID 1 — reaps Chromium zombies, forwards signals so outbound.db writes finalize on SIGTERM
Bun 1.3.12 runs the agent-runner TypeScript directly (no tsc build step)
Chromium for browser automation via agent-browser
Global Node CLIs (pnpm): @anthropic-ai/claude-code, agent-browser, vercel
Non-root node user, /workspace/group as working directory
Source is never baked in — /app/src is a read-only bind mount from the host, so code changes take effect without rebuilding

Optional: INSTALL_CJK_FONTS=true in .env adds Chinese/Japanese/Korean font support (~200 MB).

Service management

NanoClaw runs as a background service so the host stays responsive to channel events between your messages.

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

# Start / stop
# Replace <label> with com.nanoclaw-v2-<slug>
launchctl load ~/Library/LaunchAgents/<label>.plist
launchctl unload ~/Library/LaunchAgents/<label>.plist

# Restart
launchctl kickstart -k gui/$(id -u)/<label>

# Status
launchctl list | grep nanoclaw

# Logs
tail -f logs/nanoclaw.log

# Replace <unit> with nanoclaw-v2-<slug>
systemctl --user start <unit>
systemctl --user stop <unit>
systemctl --user restart <unit>
systemctl --user status <unit>

# Enable on boot
systemctl --user enable <unit>

# Logs
journalctl --user -u <unit> -f

VM / SSH users: the installer runs loginctl enable-linger so the service survives SSH logout. Verify with loginctl show-user $USER | grep Linger.

If WSL doesn’t have systemd enabled, the installer drops a wrapper script:

bash start-nanoclaw.sh
pkill -f "bun.*src/index.ts"     # stop
tail -f logs/nanoclaw.log        # logs

To enable systemd in WSL (recommended):

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

Troubleshooting

`better-sqlite3` build errors

pnpm rebuild better-sqlite3
# or
rm -rf node_modules pnpm-lock.yaml && pnpm install

If the error mentions Python: sudo apt-get install python3 (Linux/WSL) or xcode-select --install (macOS).

Container build fails

# Docker
docker builder prune -f
./container/build.sh

# Apple Container
container builder stop && container builder rm && container builder start
./container/build.sh

Service won’t start

Check the error log and the setup progression log:

cat logs/nanoclaw.error.log
cat logs/setup.log

Ask the agent itself for a diagnostic once it’s up:

@Andy /debug

WSL: Docker integration

If docker commands aren’t found in WSL, enable WSL integration in Docker Desktop (Settings → Resources → WSL Integration → toggle your distro). Restart WSL from PowerShell if needed:

wsl --shutdown

WSL: slow builds

Clone into the Linux filesystem (~/nanoclaw), not /mnt/c/. The 9P bridge to Windows drives is 10-100× slower than native Linux FS operations.

Next steps

Quick start

Run bash nanoclaw.sh and send your first message

Architecture

How the two-DB session model works

Integrations

Add channels: Telegram, Slack, Discord, and more

Customization

Change the trigger word, adjust timeouts, tune engage modes

Get Started

Core Concepts

Features

Integrations

Advanced

Changelog

System requirements

What the installer needs

Build tools

Container runtime

Advanced installer environment

Run the installer

File structure after install

Container image contents

Service management

Troubleshooting

`better-sqlite3` build errors

Container build fails

Service won’t start

WSL: Docker integration

WSL: slow builds

Next steps

Quick start

Architecture

Integrations

Customization

Get Started

Core Concepts

Features

Integrations

Advanced

Changelog

Documentation Index

​System requirements

​What the installer needs

​Build tools

​Container runtime

​Advanced installer environment

​Run the installer

​File structure after install

​Container image contents

​Service management

​Troubleshooting

​better-sqlite3 build errors

​Container build fails

​Service won’t start

​WSL: Docker integration

​WSL: slow builds

​Next steps

Quick start

Architecture

Integrations

Customization

System requirements

What the installer needs

Build tools

Container runtime

Advanced installer environment

Run the installer

File structure after install

Container image contents

Service management

Troubleshooting

`better-sqlite3` build errors

Container build fails

Service won’t start

WSL: Docker integration

WSL: slow builds

Next steps