Skip to content
Get packs

Guide · Open source

How to use NanoClaw: install, set up agents and channels

Updated · written with AI from the project's own documentation and checked against our catalogue data

NanoClaw is an open-source AI assistant that you run on your own machine. It connects to messaging apps such as WhatsApp, Telegram, Slack and Discord, and each agent runs in its own Linux container. This guide shows how to install it with the setup script, what you need beforehand, and how to customize it. By the end you will know how to get a first agent running and where the limits are.

NanoClawnanocoai/nanoclaw · ★ 31.1k · MIT

Quick start

  1. 1Check prerequisites. Make sure Git is installed. The setup script will install Docker, Node.js and pnpm if they are missing.
  2. 2Clone the repository. Run git clone on the nanocoai/nanoclaw repository into a folder named nanoclaw-v2.
  3. 3Enter the directory. Change into the nanoclaw-v2 folder with cd.
  4. 4Run the setup script. Run bash nanoclaw.sh. It builds the agent container and walks you through creating a named agent.
  5. 5Pair a channel. Choose a first channel such as Slack, Telegram, Discord or WhatsApp and pair it with your agent.
  6. 6Customize in a fork. Make your own fork and ask Claude Code to change the code to match your needs.

What you need before you install NanoClaw

NanoClaw uses a clone-and-build install. You need Git on your machine. The setup script installs Docker, Node.js and pnpm if they are missing. Install runs shell scripts, so it is best suited to people comfortable with a terminal.

The README lists macOS, Linux and WSL2 for containers. Native Windows is not listed, so use WSL2 there.

  • Git (required)
  • Docker (installed by the script if missing)
  • Node.js and pnpm (installed by the script if missing)
  • macOS, Linux, or WSL2 on Windows

Install NanoClaw with the setup script

Clone the repository, enter the folder and run the setup script. The repository is cloned into a folder named nanoclaw-v2.

The script takes you from a fresh machine to a named agent you can message. It installs Node, pnpm and Docker if missing, installs a credential gateway and registers your Anthropic credential with it, builds the agent container, and pairs your first channel. If a step fails, Claude Code is invoked automatically to diagnose and resume from where it broke.

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2 cd nanoclaw-v2 bash nanoclaw.sh

Connect a messaging channel

During setup you pick the first channel to pair. The README lists Slack, Telegram, Discord, WhatsApp, iMessage, or a local CLI. Other channels such as Microsoft Teams, Matrix and email via Resend are added later with skills like /add-telegram.

Each channel can be connected to its own agent, or several channels can share one agent. You choose this per channel with /manage-channels.

  • Slack: setup provisions each agent its own Slack app, so no tokens need to be pasted.
  • Other channels are installed on demand with /add-<channel> skills.

Customize NanoClaw by changing code

NanoClaw is designed to be modified as code rather than configured through many settings. The README suggests making your own fork and asking Claude Code to change it. Each agent group has its own CLAUDE.md, its own memory and its own container.

Alternative model providers are added with skills such as /add-codex, /add-opencode, /add-cursor and /add-ollama-provider. The provider can be set per agent group.

  • Each agent has its own CLAUDE.md, memory, container and allowed mounts.
  • Scheduled tasks run recurring jobs, with optional script gates that skip work when there is nothing to do.
  • Agent templates can be created with ncl groups create --template <ref>.

Migrate from NanoClaw v1 (optional)

If you already run v1, the README describes a migration script run from a fresh v2 checkout next to your v1 install. The script copies state into the v2 checkout and leaves your v1 install untouched. It does not switch the system service for you; you choose that at the prompt or do it manually after testing.

Run the script directly, not from inside a Claude session, because it needs interactive prompts and real shell I/O.

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2 cd nanoclaw-v2 bash migrate-v2.sh

Privacy and what leaves your machine

NanoClaw has no user accounts. It reports only anonymous setup diagnostics, and you can turn these off by setting NANOCLAW_NO_DIAGNOSTICS=1. Building the agent image locally needs no account and contacts nothing, which is the default.

Fetching a prebuilt agent image is optional and requires a free account. The README says that account reveals your email address and when you request an image, but nothing about your agents.

NANOCLAW_NO_DIAGNOSTICS=1

What people use it for

  • A developer who wants a small codebase to read and modify for a personal assistant.
  • Someone who wants an assistant reachable from Telegram or Slack with each agent isolated in its own container.
  • Separate agents with separate memory for work and personal chat channels.
  • Scheduled jobs run by an agent, such as recurring checks that skip when there is no work.

Frequently asked questions

Is NanoClaw free?

The README describes NanoClaw as an MIT-licensed open-source project. Building the agent image locally needs no account. Fetching a prebuilt image requires a free account.

What do I need to install NanoClaw?

You need Git, and the setup script installs Docker, Node.js and pnpm if they are missing. The README lists macOS, Linux and WSL2 for containers.

Does NanoClaw work on Windows?

The README lists macOS, Linux and WSL2 for containers, so native Windows is not listed. Use WSL2 on Windows.

How is NanoClaw different from OpenClaw?

The README describes NanoClaw as a smaller alternative to OpenClaw, with one process and a handful of files, and agents running in their own Linux containers. OpenClaw runs in one Node process with application-level security, according to the README.

Does NanoClaw have a dashboard?

No. The README says there is no monitoring dashboard or debugging UI, and problems are described to Claude Code in chat instead.

Can I connect NanoClaw to WhatsApp and Telegram at the same time?

Yes. The README says you can run one or many channels at the same time, including WhatsApp and Telegram, each added with its own /add-<channel> skill.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

NanoClaw suits developers who want a small codebase they can read and change, and people who want a chat-app assistant with container isolation. It is a poor fit for non-technical users who want a finished app with no setup, or for anyone who needs a monitoring dashboard.

Install options & downloads