Skip to main content
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

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. 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:
  1. 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.
  2. 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.
  3. pnpm run setup:auto — the interactive wizard (setup/auto.ts). This is where the container build, credential gateway install (OneCLI by default; Advanced setup can pick Iron Proxy), 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 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.4.0 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:
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:

​
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:
Available steps: timezone, set-env, environment, container, register, pair-telegram, pair-dial, groups, whatsapp-auth, signal-auth, mounts, service, verify, provider-auth, cli-agent, registry, portal, registry-reconcile, gateway, gateway-auth.

​
Scripting the wizard

setup:auto reads environment variables for unattended or partial runs: For Anthropic-compatible custom endpoints, set ANTHROPIC_BASE_URL in .env — the host passes it through to the agent SDK inside the container.

​
Install on Proxmox VE

On a Proxmox VE host, a helper script creates a container and installs NanoClaw in it. The NanoClaw team maintains it on its own fork, glifocat/nanoclaw-proxmox. It uses the community-scripts engine but is not part of community-scripts, so report problems to NanoClaw, not to that project. Run this in the Proxmox VE host shell as root:
It supports Proxmox VE 8.0–8.9 and 9.0–9.2 and refuses other versions.
If newer container packages (pve-container, lxc-pve) are available for the host, the helper first offers to upgrade them. Accepting runs apt-get upgrade -y on the host, which upgrades every host package, not just those two. Decline it if you manage host updates yourself.
The helper creates:
  • An unprivileged Debian 13 LXC with 2 cores, 8 GiB RAM and a 40 GiB disk by default. The helper’s advanced settings let you change them. Nesting and keyctl are enabled so Docker can run inside the container.
  • The runtime: Docker, Node.js 22 and pnpm.
  • NanoClaw itself: the latest release in /home/nanoclaw/nanoclaw, the home folder of a dedicated nanoclaw account that builds and owns it instead of root. The checkout is a git repository at the release tag, so skills and the updater work as they do on any other install.
At the end, an interactive run asks Start NanoClaw setup now? Answer y to open the setup wizard as the nanoclaw user; it takes care of sign-in, the OneCLI vault, the agent image and the service. If you skip it, the helper prints the command to start the wizard from the host later:
Updating: open the container’s shell (pct enter <CTID>) and run update. It checks for a newer NanoClaw release and applies it through NanoClaw’s own update transaction. When a release lists breaking changes that need manual steps, the helper does not apply it: it prints those steps, keeps the running version, and you finish the update with /update-nanoclaw from /home/nanoclaw/nanoclaw as the nanoclaw user. The link is pinned to the nanoclaw-helper-v2.2 tag, and so are the install script and the community-scripts engine it loads. A container’s update command keeps using that helper version. It still installs new NanoClaw releases. Containers created with helper v2.1 or earlier keep NanoClaw in /opt/nanoclaw. For help, open an issue on the NanoClaw repository and mention Proxmox VE, or ask in Discord.

​
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. If you reach the internet through an outbound proxy, the service step reads HTTPS_PROXY and HTTP_PROXY (ALL_PROXY is used as a fallback for either) and NO_PROXY from your setup shell or .env and passes them to the service. Loopback addresses are always added to NO_PROXY. This needs Node 22.21+, 24.5+ or 25+: on an older Node the wizard warns that the proxy is ignored and NanoClaw connects directly. Only http:// and https:// proxy URLs are used. The values are kept in an owner-only data/service-proxy.env file (launchd keeps them in the owner-only plist), because a proxy URL can contain a password.
The plist lands at ~/Library/LaunchAgents/com.nanoclaw-v2-<slug>.plist with RunAtLoad and KeepAlive — it starts at login and restarts on crash.

​
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
groups
main
instructions.prepend.md
memory
CLAUDE.md
container.json
data
v2.db
v2-sessions
{agent_group_id}
.claude-shared
ipc
cli.sock
.env
nanoclaw.sh
The highlights:

​
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.
Last modified on October 22, 2026