Installation

This page is the depth companion to Quick start: what the installer actually does, how to install by hand, how the background service works, and where everything lands on disk. If you just want a running assistant, run bash nanoclaw.sh and follow the wizard — quick start covers that flow end to end.

Requirements

	Requirement
Platform	macOS or Linux. Windows works through WSL2 — the installer detects WSL and treats it as Linux.
RAM	4 GB+. The installer warns below 3,700 MB (a “4 GB” VM typically reports 3,700–3,900 MB after kernel reserves) and lets you override.
Node.js	22 or newer on the host (`engines` in `package.json`). Installed or upgraded for you if needed.
git	To clone the repository. Not auto-installed.
Agent credential	A credential for the provider you pick at setup. Default Claude: a subscription (browser sign-in), an OAuth token (`sk-ant-oat…`), or an Anthropic API key (`sk-ant-api…`). Pick Codex instead and it’s a ChatGPT subscription or an OpenAI API key. Either way it lands in the OneCLI vault, never the container.

Two hosts the installer explicitly flags in pre-flight:

Google Compute Engine VMs — GCE blocks the sudo commands setup needs, so NanoClaw is unlikely to run there. The installer detects GCE via DMI and warns before doing anything. Use a different provider.
Root on Linux — discouraged. The installer offers instructions for creating a regular user instead. If you insist, it installs a system-level systemd unit rather than a user one.

What’s installed for you

nanoclaw.sh installs everything below if it’s missing. You don’t need to pre-install any of it.

Dependency	Where it runs	How it’s installed
Homebrew (macOS only)	Host	Official installer, after a prompt. Pulls in Apple’s Command Line Tools (can take 5–10 minutes on a factory Mac).
Node 22	Host	`uvx nodeenv -n lts` if `uvx` is present; otherwise `brew install node@22` (macOS) or NodeSource + `apt-get` (Linux). Skipped if you already have Node 22+.
pnpm 10	Host	`corepack enable`, falling back to `npm install -g pnpm@<pinned>` at the version from `packageManager`.
Docker	Host	`brew install --cask docker` (macOS) or `get.docker.com` + `usermod -aG docker` (Linux/WSL). Setup also starts the daemon and works around stale group membership (`sg docker` re-exec, or a temporary ACL on the socket) so you don’t have to log out and back in.
OneCLI vault	Host	Installed by the wizard, or reuses an existing healthy OneCLI instance if it finds one.
Bun 1.3.12	Container	Baked into the agent container image. Never touches the host.

Build tools (Xcode Command Line Tools on macOS, gcc/make on Linux) are checked and reported but not installed. They only matter if better-sqlite3 has to compile from source — setup verifies the native binding loads and fails loudly if it doesn’t.

What the installer does under the hood

bash nanoclaw.sh is a three-stage chain:

nanoclaw.sh — pre-flight checks (RAM floor, GCE detection, root warning, Homebrew prompt on macOS), then runs the bootstrap under a spinner. Bash only — nothing else exists on the machine yet.
setup.sh — detects the platform (macOS / Linux / WSL), installs or upgrades to Node 22 via setup/install-node.sh if Node 22+ isn’t present, gets pnpm onto the PATH, runs pnpm install --frozen-lockfile, and verifies the better-sqlite3 native module loads.
pnpm run setup:auto — the interactive wizard (setup/auto.ts). This is where the container build, OneCLI vault, provider auth, service install, and channel pairing happen. Quick start walks through every wizard step.

The three installer stages: nanoclaw.sh pre-flight in bash, setup.sh bootstrap installing Node and dependencies, then the pnpm run setup:auto wizard where the real setup happens

Every run writes two logs: a progression log at logs/setup.log (one entry per step) and verbatim per-step output under logs/setup-steps/NN-name.log. When something fails, start there.

One runtime on the host, another in the container

NanoClaw deliberately splits runtimes:

Host: Node 22+ and pnpm. The wizard compiles TypeScript with tsc and the service runs node dist/index.js.
Agent container: Bun 1.3.12 runs the agent-runner TypeScript directly — no build step. The image (from container/Dockerfile) is based on node:22-slim with Chromium for browser automation and globally installed CLIs — @anthropic-ai/claude-code and agent-browser, each pinned to an exact version for reproducibility (the Vercel CLI is opt-in via /add-vercel). The versions live in container/cli-tools.json (installed by install-cli-tools.sh).

Two consequences worth knowing:

Agent source is never baked into the image. The host bind-mounts container/agent-runner/src read-only at /app/src, so agent-runner changes take effect on the next container spawn without a rebuild. The host’s own src/ is different: the service runs the compiled dist/, so host changes need pnpm run build and a service restart.
The image is per-checkout: nanoclaw-agent-v2-<slug>:latest, where the slug defaults to the first 8 hex chars of sha1(projectRoot). NANOCLAW_INSTALL_ID in the process environment overrides it with a stable ID: 1–32 lowercase letters, digits, underscores, or hyphens, starting with a letter or digit. Use a distinct ID for each install; sharing an ID also shares the scope used for images, services, and container cleanup.

The container step fetches a pre-built image by default: sign in with your NanoClaw account, and setup pulls the reference pinned as agent-image in versions.json — implemented by container/pull.sh — and retags it to the same local tag a build would produce. Building locally is the explicit Build it here choice (and the fallback when the pin or its login script is missing, sign-in doesn’t complete, or the provider isn’t claude). The choice persists as NANOCLAW_HARDENED_IMAGE in .env. See Get started with the Echo hardened runtime. Docker is the only runtime shipped in this repository. Session lifecycle operations live behind the driver interface in src/drivers/. NANOCLAW_RUNTIME_DRIVER selects a registered driver and defaults to docker; an unknown driver fails instead of falling back. src/container-runtime.ts retains the Docker binary constant for non-session operations such as image builds. If you render Chinese, Japanese, or Korean text, set INSTALL_CJK_FONTS=true in .env before the container build — it adds Noto CJK fonts (~200 MB) to the image.

Manual installation

If you’d rather not run nanoclaw.sh (or it failed partway), the pieces compose by hand:

git clone https://github.com/nanocoai/nanoclaw.git
cd nanoclaw
pnpm install
pnpm run setup:auto

setup:auto is the same wizard the one-liner hands off to — it builds the container image, sets up credentials, and installs the background service. Without it, you can run the host in the foreground:

pnpm run build && pnpm start   # compiled, what the service runs
pnpm run dev                   # tsx, no build step

Re-running individual steps

pnpm run setup is a step runner, not a second wizard. Use it to re-run one piece of setup without going through the whole flow:

pnpm run setup -- --step container   # rebuild and re-test the agent image
pnpm run setup -- --step service     # rebuild TypeScript and reinstall the service
pnpm run setup -- --step verify      # end-to-end health check

Available steps: timezone, set-env, environment, container, register, pair-telegram, pair-dial, groups, whatsapp-auth, signal-auth, mounts, service, verify, onecli, auth, provider-auth, cli-agent, registry, registry-reconcile.

Scripting the wizard

setup:auto reads environment variables for unattended or partial runs:

Env var	Use
`NANOCLAW_SKIP`	Comma-separated wizard steps to skip: `environment`, `container`, `onecli`, `auth`, `mounts`, `service`, `cli-agent`, `first-chat`, `timezone`, `channel`, `verify`
`NANOCLAW_DISPLAY_NAME`	Skip the “what should the assistant call you” prompt
`NANOCLAW_AGENT_NAME`	Set the messaging-channel agent name
`SECRET_NAME`	OneCLI secret name (default: `Anthropic`)
`HOST_PATTERN`	OneCLI host pattern (default: `api.anthropic.com`)

For Anthropic-compatible custom endpoints, set ANTHROPIC_BASE_URL in .env — the host passes it through to the agent SDK inside the container.

Running as a service

The wizard’s service step compiles TypeScript (pnpm run build), writes a service definition that runs node dist/index.js from the project root, starts it, and symlinks bin/ncl into ~/.local/bin so the ncl CLI works from anywhere. Service names embed the per-checkout slug, so look yours up rather than guessing.

macOS (launchd)
Linux (systemd)
No systemd (WSL fallback)

The plist lands at ~/Library/LaunchAgents/com.nanoclaw-v2-<slug>.plist with RunAtLoad and KeepAlive — it starts at login and restarts on crash.

# Find your label
launchctl list | grep nanoclaw

# Restart
launchctl kickstart -k gui/$(id -u)/com.nanoclaw-v2-<slug>

# Stop / start
launchctl unload ~/Library/LaunchAgents/com.nanoclaw-v2-<slug>.plist
launchctl load   ~/Library/LaunchAgents/com.nanoclaw-v2-<slug>.plist

# Logs (stdout and stderr go to files, not the system log)
tail -f logs/nanoclaw.log logs/nanoclaw.error.log

A user unit lands at ~/.config/systemd/user/nanoclaw-v2-<slug>.service with Restart=always. (If you set up as root, it’s a system unit at /etc/systemd/system/ instead — drop the --user flag.)

# Find your unit
systemctl --user list-units 'nanoclaw-v2-*'

systemctl --user restart nanoclaw-v2-<slug>
systemctl --user status  nanoclaw-v2-<slug>

# Logs append to files, not the journal
tail -f logs/nanoclaw.log logs/nanoclaw.error.log

Setup runs loginctl enable-linger so the user service survives SSH logout. Verify with loginctl show-user $USER | grep Linger.

On WSL (or any Linux) without a systemd user session, setup writes a wrapper script instead of a unit:

bash start-nanoclaw.sh        # start (stops any previous instance first)
kill $(cat nanoclaw.pid)      # stop
tail -f logs/nanoclaw.log     # logs

To get a real service, enable systemd in WSL (/etc/wsl.conf → [boot] systemd=true, then wsl --shutdown from PowerShell) and re-run pnpm run setup -- --step service.

Where files live

Most application state lives inside the checkout. Security allowlists and registry account state live in ~/.config/nanoclaw/; service definitions, Docker state, command symlinks, and update transaction backups also live outside it.

nanoclaw

src

dist

container

groups

main

instructions.prepend.md

memory

CLAUDE.md

container.json

data

v2.db

v2-sessions

{agent_group_id}

{session_id}

.claude-shared

env

ipc

cli.sock

logs

bin

.env

nanoclaw.sh

The highlights:

Path	Purpose
`groups/<folder>/instructions.prepend.md`	The group’s standing instructions and persona — this is the file you edit.
`groups/<folder>/memory/`	The agent’s durable memory tree, scaffolded at boot and shared by every provider.
`groups/<folder>/CLAUDE.md`	Regenerated at every container spawn from the shared base plus enabled skills. Don’t edit it — your changes get overwritten.
`groups/<folder>/container.json`	Generated projection of the group’s database-backed container configuration. Edit it through `ncl`, not this file.
`container/CLAUDE.md`	Shared base instructions inlined into the generated group `CLAUDE.md`.
`data/v2.db`	Host state database (groups, sessions, wirings, users, and configuration).
`data/v2-sessions/`	Per-session message queues and scheduled-task occurrences — `inbound.db` (host writes) and `outbound.db` (container writes).
`~/.config/nanoclaw/mount-allowlist.json`	Which host directories agents may mount. Never mounted into containers.
`~/.config/nanoclaw/sender-allowlist.json`	Optional per-channel sender access control.
`~/.local/bin/ncl`	Symlink to `bin/ncl` so the CLI works from any directory.
`~/Library/LaunchAgents/com.nanoclaw-v2-<slug>.plist`	launchd service (macOS).
`~/.config/systemd/user/nanoclaw-v2-<slug>.service`	systemd user service (Linux).

Next steps

Quick start

The one-command flow and the wizard, step by step.

Architecture

How the host, containers, and the two-DB session model fit together.

The ncl CLI

Inspect agents, groups, and sessions from the command line.

Troubleshooting

Setup failures start at logs/setup.log; runtime issues at logs/nanoclaw.log.

Get started

Channels

Operate

Build with agents

Templates

Extend

Understand

Changelog

Requirements

What’s installed for you

What the installer does under the hood

One runtime on the host, another in the container

Manual installation

Re-running individual steps

Scripting the wizard

Running as a service

Where files live

Next steps

Quick start

Architecture

The ncl CLI

Troubleshooting

​Requirements

​What’s installed for you

​What the installer does under the hood

​One runtime on the host, another in the container

​Manual installation

​Re-running individual steps

​Scripting the wizard

​Running as a service

​Where files live

​Next steps

Quick start

Architecture

The ncl CLI

Troubleshooting

Requirements

What’s installed for you

What the installer does under the hood

One runtime on the host, another in the container

Manual installation

Re-running individual steps

Scripting the wizard

Running as a service

Where files live

Next steps