How to Self-Host NanoClaw 24/7 on a Dedicated Mac mini

1. Why Run NanoClaw on a Dedicated Mac mini?

NanoClaw only answers while its host is on and connected, the quickstart says so plainly, which rules out a laptop that sleeps. It needs a Mac or Linux machine with at least 4 GB of RAM plus Docker (Docker Desktop on macOS), and its GitHub description positions it as a lightweight alternative to OpenClaw that runs in containers for security. A shared Linux VPS can be cheaper than a Mac mini, so be clear about what you are buying: a dedicated 1:1 physical Apple Silicon Mac that nobody else shares, the only platform where NanoClaw's local iMessage backend works, a real desktop session for Docker Desktop, and a box you can also use for Xcode builds or local models.

2. Prerequisites

Before you begin, make sure you have the following. Everything below comes from the official NanoClaw README, quickstart and installation pages, plus Docker's and Anthropic's terms for the platform facts:

• A dedicated Mac mini from MyRemoteMac, M4 from $85/mo (16 GB / 256 GB) or Mac mini M6 from $149/mo. NanoClaw asks for at least 4 GB of RAM (the installer warns below 3,700 MB); every plan clears that by a wide margin.
• SSH and VNC access (both included with your subscription). VNC is needed once: Docker Desktop is a GUI application and must be launched from the desktop the first time.
• Docker Desktop for Mac, running whenever NanoClaw starts. Docker's terms: free for personal use, education, non-commercial open source and companies with fewer than 250 employees and less than US$10 million in annual revenue; larger companies and government entities need a paid subscription.
• Homebrew, git, Node.js 22+ and pnpm 10. git must be present; the installer offers to install Homebrew and installs Node and pnpm itself if they are missing (Node 20 is unsupported since 2.3.0).
• The Claude Code CLI on the Mac. It is not optional: every /add-<channel> skill, /customize, /debug, /update-nanoclaw and the installer's error recovery run inside Claude Code from the project root.
• An Anthropic API key (sk-ant-api…) from console.anthropic.com, billed per token. The wizard also offers to sign in with a Claude subscription, but Anthropic's legal terms state that OAuth is intended for ordinary use of Claude Code and native Anthropic apps, and that products built on the Agent SDK should use API key authentication, so for a business or always-on deployment, use a key.
• A messaging account on Telegram, WhatsApp or Discord to connect your agent (the built-in terminal channel needs nothing).

3. Step 1: Connect via SSH, Install Docker Desktop and Claude Code

First, SSH into your Mac mini with the credentials from your MyRemoteMac dashboard and check the two tools the installer expects to find. The NanoClaw installer will install Homebrew, Node and Docker for you, but pre-installing Docker Desktop lets you start it and verify the daemon before the wizard needs it.

Connect via SSH

# Connect to your Mac mini
ssh admin@your-server-ip

# Verify you're on Apple Silicon
uname -m
# Expected output: arm64

# git is required (not auto-installed); Homebrew is offered by the installer if missing
git --version
brew --version

Install and Start Docker Desktop for Mac

This is the exact command NanoClaw's own setup/install-docker.sh runs on macOS when docker is missing. Docker Desktop is a desktop application: launch it once from the Mac's desktop over VNC, then confirm from SSH that the daemon answers. If it is not running when NanoClaw starts, the host exits with "FATAL: Container runtime failed to start".

# Install Docker Desktop for Mac (the same Homebrew cask NanoClaw's installer uses)
brew install --cask docker

# Start Docker Desktop, a GUI app: do the first launch from the desktop (VNC)
open -a Docker

# The daemon must answer before NanoClaw can start
docker info

Install Claude Code on the Host

NanoClaw's setup/install-claude.sh runs the same command when claude is missing. You will use Claude Code for every channel, provider and update from now on:

# Official Claude Code installer (the command NanoClaw's setup/install-claude.sh runs)
curl -fsSL https://claude.ai/install.sh | /bin/bash
claude --version

4. Step 2: Install NanoClaw and Configure Your Claude API Key

NanoClaw is not an npm package you install globally: you clone the repository and run a one-shot installer that turns the checkout into your own install. Keep the folder where it is afterwards, the launchd label, the image name and the install slug are derived from its path. Plan 30 to 60 minutes; the wizard is interactive.

Clone and Run the Installer

# Clone the canonical repo (nanocoai: the old qwibitai URL redirects here)
cd ~
git clone https://github.com/nanocoai/nanoclaw.git
cd nanoclaw

# One-shot installer: Node 22 + pnpm + Docker if missing, OneCLI gateway,
# credential registration, sandbox image, launchd service, optional channel
bash nanoclaw.sh

The wizard walks you through the documented choices: Standard setup → Fresh agent → sandbox image: fetch the prebuilt hardened image built by Echo (needs a free NanoClaw sign-in, about 800 MB from a single US region) or build it locally (3–10 minutes, no account, contacts nothing, may be faster from Europe or Asia) → AI runtime: Claude → paste your Anthropic API key (recommended; "Sign in with my Claude subscription" is also offered, see the note in Prerequisites) → Skip for now for the messaging channel. The installer stores your key in the OneCLI Agent Vault, a credential gateway that is mandatory since 2.4.0: agent containers never hold raw API keys.

Scripted Alternative and First Message

If you prefer a non-interactive run, the installation page documents setup-time variables that pre-answer the prompts. Either way, test with the built-in terminal channel from the project folder, the first reply may take a little time while the container starts:

# Scripted setup (documented alternative to the wizard)
pnpm install
pnpm run setup:auto
# Pre-answer prompts with NANOCLAW_AGENT_PROVIDER, NANOCLAW_CHANNELS,
# NANOCLAW_HARDENED_IMAGE, NANOCLAW_SKIP; NANOCLAW_NO_DIAGNOSTICS=1 disables setup diagnostics

# First message through the built-in CLI channel (no credentials needed)
pnpm run chat "hello, who are you?"

# Re-run individual steps later: rebuild the image, reinstall the service, health check
pnpm run setup -- --step container
pnpm run setup -- --step service
pnpm run setup -- --step verify

Choose the Model and Set the Basics in .env

Install-wide settings live in .env at the project root (created with mode 0600 by setup); per-agent-group settings live in the database and are edited with the ncl admin CLI. Since 2.4.0, Claude groups with no model set use Opus 5.5 (claude-opus-5-5, $4 input / $20 output per million tokens); Claude Sonnet 5 costs $2 / $10, so pin it for a personal assistant if cost matters. Other providers are per agent group: /add-codex (OpenAI) and /add-opencode (OpenRouter, OpenAI, Google, DeepSeek). Local models: the README lists /add-ollama-provider, but the providers page on docs.nanoclaw.dev states it is not a supported drop-in switch on current main, treat it as an experiment, not a way to replace Claude.

# Install-wide model for every Claude group with no model set
# (aliases sonnet | opus | haiku, or a full id such as claude-sonnet-5)
echo 'NANOCLAW_DEFAULT_MODEL=sonnet' >> .env

# Timezone for scheduled tasks and timestamps (IANA name)
echo 'TZ=Europe/Paris' >> .env

# .env is read only by the host process: restart it after edits
launchctl kickstart -k gui/$(id -u)/com.nanoclaw-v2-<slug>

# Per-group overrides via the ncl admin CLI (symlinked at ~/.local/bin/ncl by setup)
ncl groups config update --id <group-id> --model opus
ncl groups config update --id <group-id> --timezone Europe/Lisbon
# Switch a group to another provider (takes effect on the next container spawn)
ncl groups config update --id <group-id> --provider opencode

5. Step 3: Connect Messaging Channels

Channels are not bundled: each one is installed on demand as a Claude Code skill run from the project root, which adds the adapter to your checkout. Telegram is the fastest to get working, create a bot with @BotFather, paste the token when the skill asks (it is stored as TELEGRAM_BOT_TOKEN in .env), then send the one-time 6-digit pairing code to the bot as a message containing nothing but the digits. Polling mode means no public URL, webhook or open port:

# Step 1: Open Telegram and search for @BotFather
# Step 2: Send /newbot and follow the prompts
# Step 3: Copy the token

# Every channel is a Claude Code skill run from the project root
cd ~/nanoclaw && claude
/add-telegram
# Paste the token when asked (stored as TELEGRAM_BOT_TOKEN in .env).
# The wizard prints a one-time 6-digit pairing code: send exactly those digits to the bot.

# Groups: BotFather -> /mybots -> Bot Settings -> Group Privacy -> Turn off

Connect WhatsApp

The native adapter speaks the WhatsApp Web protocol (Baileys, not Meta's official API): scan the QR code, which rotates about every 60 seconds, or enter the 8-character pairing code under WhatsApp → Linked Devices. In shared-number mode the assistant replies in your own "You" self-chat; for a dedicated number use a separate SIM and set ASSISTANT_HAS_OWN_NUMBER=true. If compliance matters, use /add-whatsapp-cloud (Meta Cloud API) instead:

claude
/add-whatsapp
# Scan the QR (rotates ~60 s) or enter the 8-character code in WhatsApp -> Linked Devices
# Auth state persists in store/auth/: keep that folder private

# Dedicated number (separate SIM) instead of your own chat:
# ASSISTANT_HAS_OWN_NUMBER=true in .env

# Meta's official Cloud API instead of the Web-protocol adapter:
# /add-whatsapp-cloud

Connect Discord, iMessage and the Rest

Discord uses a bot token and a Gateway listener (no public URL). The catalog also covers Slack, Mattermost (new in 2.4.0), Signal, iMessage, Microsoft Teams, Google Chat, Matrix, Webex, WeChat, GitHub, Linear, Delta Chat, Emacs, email via Resend and a real phone number via Dial. The local iMessage backend is the macOS-only feature: the Mac mini must be signed in to iMessage with an Apple ID and the exact node binary needs Full Disk Access (the hosted Photon backend needs neither). Re-running an /add-<channel> skill later refreshes the adapter; /manage-channels wires each conversation to an agent group:

claude
/add-discord
# others: /add-slack /add-imessage /add-signal /add-teams /add-mattermost /add-matrix ...

# Wire conversations to agent groups
/manage-channels

# Silent agent? Check why messages were dropped (no_agent_wired, no_agent_engaged, ...)
ncl dropped-messages list
ncl sessions list

6. Step 4: Run 24/7 with launchd, Then Update Safely

For 24/7 operation NanoClaw must start on boot and restart on failure. The installer already handled this: its service step writes a per-user launchd LaunchAgent named com.nanoclaw-v2-<slug> (slug = first 8 hex characters of the SHA-1 of the project path; older tutorials still show the pre-2.3.0 label com.nanoclaw) with RunAtLoad and KeepAlive, logging to logs/nanoclaw.log and logs/nanoclaw.error.log. The plist sets only PATH and HOME and does not source .env, so restart the host after every .env edit.

Verify and Manage the Service

# Is the LaunchAgent loaded? Find your label (com.nanoclaw-v2-<slug>)
launchctl list | grep nanoclaw
ls ~/Library/LaunchAgents/ | grep nanoclaw

# Health: host + connected adapters (ncl status is new in 2.4.0)
ncl status
pnpm run setup -- --step verify
docker ps --filter label=nanoclaw-install

# Live logs
tail -f logs/nanoclaw.log logs/nanoclaw.error.log

# Restart (also after every .env edit) / stop / start / reinstall the service
launchctl kickstart -k gui/$(id -u)/com.nanoclaw-v2-<slug>
launchctl unload ~/Library/LaunchAgents/com.nanoclaw-v2-<slug>.plist
launchctl load ~/Library/LaunchAgents/com.nanoclaw-v2-<slug>.plist
pnpm run setup -- --step service   # regenerates the plist (wipes manual edits)

Survive a Reboot on a Headless Mac mini

This part is our operations recommendation, assembled from Apple's and Docker's documentation, NanoClaw's docs do not cover headless Macs. The LaunchAgent lives in your user session and Docker Desktop is a GUI app, so after a reboot nothing runs until someone logs in. Enable Automatic login for the same user account that ran bash nanoclaw.sh, the LaunchAgent and Docker Desktop's start-at-sign-in setting are both per-user, so auto-logging-in another account would leave the service unloaded and Docker stopped (Apple: Automatic login is not available while FileVault is on). Remember that anyone who restarts the Mac lands in that session, which is acceptable only on a dedicated Mac mini reachable solely over SSH, VNC and WireGuard; if you prefer a non-admin account for it, install NanoClaw under that account, knowing that installing Homebrew and running sudo pmset still need an administrator (Docker Desktop itself runs as an unprivileged user and only asks for privileged access for specific features). Then turn on Docker Desktop's "Start Docker Desktop when you sign in to your computer" setting, and disable sleep:

# 1. System Settings > Users & Groups > Automatic login = the user that ran bash nanoclaw.sh
#    (over VNC; not available with FileVault on; LaunchAgent + Docker Desktop are per-user)
# 2. Docker Desktop > Settings > General > "Start Docker Desktop when you sign in to your computer"

# 3. Keep the Mac awake (same as in our OpenClaw guide)
sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

# 4. Reboot-test, then log back in over SSH and check
sudo reboot
docker info
launchctl list | grep nanoclaw

Update NanoClaw (Never git pull)

The upgrading page is explicit: "Do not update with a raw git pull." NanoClaw records each sanctioned upgrade in data/upgrade-state.json and a startup tripwire refuses to start on a mismatch. The only supported path is /update-nanoclaw in Claude Code: it creates a backup branch and tag, stages upstream in a separate worktree, validates (install, build, tests), stops the service and containers, snapshots .env, data, groups and store, cuts over, restarts and health-checks. It is blocked on a dirty working tree or when NanoClaw is not running under launchd. Before moving to 2.4.0, pin your model if you do not want unset Claude groups to switch to Opus 5.5:

# Optional: pin the model BEFORE upgrading (2.4.0 default for unset Claude groups is Opus 5.5)
echo 'NANOCLAW_DEFAULT_MODEL=sonnet' >> .env

# The only supported update path: inside Claude Code, from the project root
cd ~/nanoclaw && claude
/update-nanoclaw
# Refresh installed channel/provider skills only:
/update-skills

# After resolving merge conflicts, or to roll back after cutover:
pnpm exec tsx scripts/update-nanoclaw.ts resume --id "$id"
pnpm exec tsx scripts/update-nanoclaw.ts rollback --id "$id"

# Remove this checkout only (service, containers, image, data; .env backed up to .env.bak)
bash nanoclaw.sh --uninstall --dry-run
bash nanoclaw.sh --uninstall

7. Security Hardening (Least Privilege)

NanoClaw's threat model is "assume the agent gets prompt-injected, then make sure a compromised agent has nothing to steal and nowhere to go." Out of the box each session runs in its own container as the unprivileged node user with --cap-drop=ALL, --security-opt no-new-privileges, --init, a pids limit and setuid bits stripped; there is no host home, no .ssh, no Docker socket, and the OneCLI gateway rewrites auth headers in flight so containers never see your API key. Approval cards (packages, MCP servers, sub-agents, new chat registration) need an admin answer and auto-deny when unanswered, keep them. The safest documented configuration adds the following, and never disables approvals or the gateway:

• Unknown senders: set --unknown-sender-policy strict (dropped silently) or request_approval on every messaging group strangers can reach.
• Mounts: leave the allowlist (~/.config/nanoclaw/mount-allowlist.json) absent or minimal, without it all additional mounts are blocked, and .ssh.gnupg.aws.kube.docker, credentials.env and .netrc are blocked patterns anyway. Mounts are read-only unless explicitly allowed.
• Isolation: "when in doubt, start more isolated." A family chat and a client channel should not be one agent; an agent with a mounted repo and deploy credentials must not share an agent group with one that talks to strangers. Separate sessions are not a confidentiality boundary inside a group.
• Limits and egress: set CONTAINER_CPU_LIMIT and CONTAINER_MEMORY_LIMIT, and enable NANOCLAW_EGRESS_LOCKDOWN=true (all traffic through the gateway, containers on an internal network) once your tools work through the proxy, it is off by default because it breaks non-proxy-aware tools.
• Secrets on disk: .env is created with mode 0600 and holds channel tokens only; agent API keys live in the vault. Keep store/auth/ (WhatsApp session) private too, our recommendation, not a NanoClaw claim. Setup sends diagnostics unless NANOCLAW_NO_DIAGNOSTICS=1.

# Unknown senders: drop silently (or route to an approval card) on every reachable group
ncl messaging-groups list
ncl messaging-groups update --id <mg-id> --unknown-sender-policy strict
# or: --unknown-sender-policy request_approval

# Opt-in per-container caps (passed to docker create --cpus / --memory)
echo 'CONTAINER_CPU_LIMIT=2' >> .env
echo 'CONTAINER_MEMORY_LIMIT=8g' >> .env

# Once every tool works through the OneCLI proxy: no direct internet route for containers
echo 'NANOCLAW_EGRESS_LOCKDOWN=true' >> .env
launchctl kickstart -k gui/$(id -u)/com.nanoclaw-v2-<slug>

# Mounts are deny-by-default and read-only unless the allowlist root sets allowReadWrite
ncl groups config add-mount --id <group-id> --host /path/on/mac --container /path/in/container

# Secrets on disk: .env must stay 0600 (setup creates it that way)
ls -l .env

Residual risks the sandbox does not cover: a compromised agent can still message any destination it is wired to, read or destroy its own workspace and memory, spend the credentials it was granted and poison the group's memory, so scope every agent group narrowly.

8. Troubleshooting Common Issues

# Is the Docker daemon up?
docker info

# Not running? Start Docker Desktop (first launch must be from the desktop over VNC)
open -a Docker

# Then restart NanoClaw and watch the logs
launchctl kickstart -k gui/$(id -u)/com.nanoclaw-v2-<slug>
tail -f logs/nanoclaw.error.log

# Never `git pull`. Run the supported update from the project root:
cd ~/nanoclaw && claude
/update-nanoclaw

# A staged update stuck in conflict, or a bad cutover?
pnpm exec tsx scripts/update-nanoclaw.ts resume --id "$id"
pnpm exec tsx scripts/update-nanoclaw.ts rollback --id "$id"

# The update is blocked on a dirty working tree, detached HEAD or a host not under launchd
git status

# Why were messages dropped? (no_agent_wired, no_agent_engaged, ...)
ncl dropped-messages list
ncl sessions list

# Wire the chat to an agent group
claude
/manage-channels

# Telegram: pending pairing codes live here; the message must contain only the 6 digits
cat data/telegram-pairings.json

# Register the gateway (OneCLI is the default; Iron Proxy is the alternative)
claude
/add-onecli
# or: /add-iron-proxy

# Check the provider recorded in .env (onecli | iron-proxy)
grep NANOCLAW_GATEWAY_PROVIDER .env

# OpenCode installs: re-run /add-opencode, then rebuild the image, restart the host and the groups
./container/build.sh build
launchctl kickstart -k gui/$(id -u)/com.nanoclaw-v2-<slug>
ncl groups restart --id <group-id>

# Is the LaunchAgent registered?
launchctl list | grep nanoclaw

# Not listed? Reinstall it (regenerates the plist)
pnpm run setup -- --step service

# Docker not up after login? Enable "Start Docker Desktop when you sign in" (Settings > General)
docker info

# Then reboot-test again
sudo reboot

9. Cost Analysis vs. Cloud VPS

NanoClaw itself is free (MIT). You pay for the host and for model usage on your Anthropic API key, identical on any host, because NanoClaw does not run local models in a supported way. The Mac mini is a dedicated physical machine, so the fair comparison is a dedicated or AI-tier cloud instance, not the cheapest shared VPS:

Assumptions: VPS prices are the same ranges used across our guides for dedicated AI-tier instances and are not quotes from a specific provider; a shared 4 GB Linux VPS would be cheaper than any Mac mini plan. MyRemoteMac prices are the current monthly rates in USD, excluding tax, 1 Gbps included. Model usage is extra on both sides: Opus 5.5 is $4 / $20 per million input / output tokens and Sonnet 5 is $2 / $10 (platform.claude.com, September 2026). NanoClaw publishes no RAM or CPU footprint figures for the host, the Docker Desktop VM or the per-session containers, so plan advice stays qualitative.

10. NanoClaw vs. OpenClaw

NanoClaw positions itself explicitly against OpenClaw: its README claims OpenClaw has nearly half a million lines of code, 53 config files and 70+ dependencies with security at the application level (allowlists, pairing codes) rather than OS-level isolation, figures from NanoClaw's README, not independently measured. From our OpenClaw guide, the practical differences on a Mac mini are these. OpenClaw is a global npm install (Node 26.1+ recommended), one Gateway process, a JSON5 config file, channels bundled, no Docker. NanoClaw is git clone + bash nanoclaw.sh, Node 22+ and pnpm 10, requires Docker Desktop, Homebrew and Claude Code on the host, has no config files (customisation is code in your own checkout), runs each session in a Linux container with cap-drop and no-new-privileges, blocks mounts by default and keeps API keys out of the sandbox through a credential gateway; channels are installed on demand as skills and updates go only through /update-nanoclaw. In short: NanoClaw is safer by construction but heavier to run (a Docker Desktop VM always on, a GUI login session, Docker's licence rule for large companies, a 30–60 minute interactive setup and a fork you maintain); OpenClaw is lighter to install and configure but relies on application-level permission checks. Both default to Claude; NanoClaw adds Codex and OpenCode per agent group. The Mac mini cost is identical for both.

Already on OpenClaw? NanoClaw ships /migrate-from-openclaw, a guided Claude Code conversation that maps OpenClaw agents to agent groups, chats to wired messaging groups, IDENTITY.md/SOUL.md to instructions.prepend.md plus memory/, skills to container/skills, channel tokens to .env, API keys to the OneCLI vault, cron jobs to ncl tasks, MCP servers to per-group config and allowlists to unknown_sender_policy and roles. WhatsApp must be re-authenticated; human delay and TTS have no v2 equivalent. Starting from scratch instead? Read our OpenClaw on a Mac mini guide and our Hermes Agent guide before choosing.

11. FAQ

12. Sources and Further Reading

Every command, path, variable and requirement in this guide was checked on September 28, 2026 against the official NanoClaw repository (nanocoai/nanoclaw, v2.4.0 released September 23, 2026, the old qwibitai URL redirects there) and docs.nanoclaw.dev, plus Docker's, Anthropic's and Apple's documentation for the platform facts. Version pins such as the Claude Code build inside agents drift with every release, so consult these pages for current values:

• GitHub: nanocoai/nanoclaw (README, LICENSE, package.json, nanoclaw.sh)
• docs.nanoclaw.dev: Quickstart
• docs.nanoclaw.dev: Installation
• docs.nanoclaw.dev: Security model
• docs.nanoclaw.dev: Isolation levels
• docs.nanoclaw.dev: Configuration
• docs.nanoclaw.dev: Credentials
• docs.nanoclaw.dev: Credential gateways (OneCLI, Iron Proxy)
• docs.nanoclaw.dev: Hardening
• docs.nanoclaw.dev: Upgrading
• docs.nanoclaw.dev: Troubleshooting
• docs.nanoclaw.dev: Environment variables reference
• docs.nanoclaw.dev: Channels overview
• docs.nanoclaw.dev: Telegram
• docs.nanoclaw.dev: WhatsApp
• docs.nanoclaw.dev: iMessage
• docs.nanoclaw.dev: Providers (Claude, Codex, OpenCode, Ollama status)
• docs.nanoclaw.dev: Echo hardened runtime image
• docs.nanoclaw.dev: Migrating from v1 / OpenClaw
• docs.nanoclaw.dev: Changelog (v2.4.0, 2026-09-23)
• GitHub: docs/release-2.4-update.md (default model change, pinning)
• GitHub: setup/install-docker.sh (Docker via Homebrew)
• Docker: Install Docker Desktop on Mac
• Docker: Pricing FAQ (Docker Desktop licensing)
• Docker Desktop: Settings (start at sign-in)
• Claude Code: Legal and compliance (OAuth vs API key)
• platform.claude.com: Claude models overview and pricing
• Apple Support: Automatic login and FileVault
• TechCrunch (2026-03-13): NanoClaw's creator and the Docker deal
• Docker Docs: Docker Desktop for Mac permission requirements (runs as an unprivileged user)

Related Guides