Skip to main content
From a fresh machine to an agent you can message — one command and a handful of prompts.

​
Prerequisites

  • macOS or Linux (WSL works) with 4 GB+ RAM — the installer warns below ~3.7 GB
  • git to clone the repository
  • A Claude subscription (Pro or Max), an OAuth token, or an Anthropic API key
Everything else — Homebrew on macOS, Node 22, pnpm, Docker, the OneCLI vault — is installed by the script if missing. Two caveats from the installer’s pre-flight checks: don’t run as root on Linux (it walks you through creating a user instead), and Google Cloud VMs are known not to work.

​
The one-command flow

1

Clone and run

git clone https://github.com/nanocoai/nanoclaw.git
cd nanoclaw
bash nanoclaw.sh
The script runs pre-flight checks (RAM, root user, Homebrew on macOS), installs the basics — Node 22, pnpm, and native modules — under a single spinner, then hands off to the interactive setup wizard (pnpm run setup:auto). If a step fails during the wizard, it offers AI-assisted recovery inline and resumes from the step that broke instead of starting over.
2

Answer the wizard

Press Enter on Standard setup (or pick Advanced to override defaults), then the wizard walks through:
  1. System check — verifies your environment
  2. Sandbox build — builds the agent container image. First build pulls a base image and takes 3–10 minutes on a fresh machine.
  3. OneCLI vault — installs the credential vault, or offers to reuse an existing OneCLI instance. Your agent never sees your API keys; the vault injects them into approved requests as they leave the sandbox.
  4. Choose your agent runtime and connect — Claude is the default: press Enter, then sign in with your Claude subscription (opens a browser), paste an OAuth token (sk-ant-oat…), or paste an API key (sk-ant-api…). Or pick Codex to install it inline and authenticate with a ChatGPT subscription or OpenAI API key — either way the credential lands in the vault, never the container
  5. Access rules — writes the assistant’s filesystem access rules (empty to start — the sandbox only sees what you explicitly share later)
  6. Background service — starts NanoClaw under launchd (macOS) or a systemd user service (Linux)
  7. Your name — what the assistant should call you
  8. First contact — the wizard pings your assistant and waits for a reply. First startup takes 30–60 seconds while the sandbox warms up. You can pause here and chat from the terminal.
  9. Timezone — auto-detected, confirmed with you
  10. Channel — connect Telegram (recommended), Discord, WhatsApp, Signal, iMessage, Slack, or Microsoft Teams — or skip and use the terminal. Other channels install after setup with /add-<name> in Claude Code.
  11. Final check — makes sure everything works together: credentials, service, and configured channels, flagging anything left to fix
3

Send your first message

If you connected a channel, the wizard wires your first agent and the assistant DMs you a welcome — check your phone and say hi.If you skipped the channel step, chat from the terminal:
pnpm run chat hi
Either way, you can watch what’s happening live:
tail -f logs/nanoclaw.log

​
What just happened

You now have a host service (launchd or systemd) running NanoClaw from this checkout. It routes messages between your channels and agents, where each agent runs in its own Docker container sandbox that wakes on incoming messages and sleeps when idle. Your Anthropic credential lives in the OneCLI vault — never inside the container. Agent workspaces live under groups/, runtime state under data/, and logs under logs/. See Architecture for the full picture. Claude is the default agent provider that the wizard connects you to. You can switch a group to Codex, OpenCode, or a local Ollama model afterward — see Agent providers.
Coming from NanoClaw v1? Run bash migrate-v2.sh before setup — see the migration guide.
Re-running bash nanoclaw.sh on a folder that already has an install lets you keep it and continue, or uninstall this copy and exit — see Uninstall NanoClaw.

​
Next steps

Add more channels

Connect Telegram, Discord, WhatsApp, Slack, and more — during setup or any time after.

The ncl CLI

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

Customize an agent

Edit instructions, mounts, and behavior for your first agent.

Troubleshooting

Setup logs live in logs/setup.log; runtime issues start at logs/nanoclaw.log.
Last modified on June 15, 2026