How to install nanobot on a Mac mini

What nanobot is

nanobot is an open source personal AI agent from the HKUDS group on GitHub. It is written in Python under the MIT license. Like OpenClaw, it keeps memory, runs tools and answers you from chat apps. Its core is kept small and readable (github.com/HKUDS/nanobot, read October 2, 2026). The latest release on PyPI was 0.3.5, on September 15, 2026.

You can use it in a browser WebUI, in the terminal, or from Telegram, Discord, Slack, Email and other channels. It can work with files, run shell commands, search the web, use MCP servers and run scheduled jobs. One more note on the name. This is not obot-platform/nanobot, which is a Go framework for building MCP agents.

Requirements

• Python 3.11 or newer. Check with python3 --version. The installer stops if it cannot find one, so install Python first if needed.
• macOS 13 or newer. The prebuilt packages for Apple silicon and Intel Macs include the WebUI and the terminal UI.
• A model provider. Anthropic, OpenAI, OpenRouter and local servers such as Ollama are all covered in the provider docs. Use an API key from the provider you pick.
• Git and Bun, but only if you install from source. The normal install does not need them.

Install it

Run the official one command installer from the README.

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh

It installs the nanobot-ai package from PyPI. It avoids system wide pip installs. It uses an active virtual environment, uv, pipx, or its own environment in the .nanobot folder of your home. It then prints the exact command it used. To see the plan without changing anything, add the dry run flag.

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dry-run

If you already use uv, this does the same job. Then check the version.

uv tool install nanobot-ai
nanobot --version

First run and a model

The README recommends the WebUI for the first run. It opens on 127.0.0.1 port 8765 and listens on this Mac only.

nanobot webui

Open Settings, then Models. Pick a provider, paste its API key, and choose a model. Then start a new topic and send Hello. Any normal reply means the provider, model and gateway work together. From the terminal, a one shot message does the same check.

nanobot -m "Hello!"

Settings are saved to config.json in the .nanobot folder of your home. We have not run this install on our own test machine yet. The commands here are copied from the nanobot README and docs as of October 2, 2026.

Keep it running 24/7

The gateway is the part that stays online. It keeps chat apps, scheduled jobs and memory work going. This command keeps it running after you close the terminal.

nanobot gateway --background

That does not survive a reboot. For that, the deployment docs install a LaunchAgent. Finish model setup in the WebUI first. Then preview the service file and install it.

nanobot gateway install-service --manager launchd --dry-run
nanobot gateway install-service --manager launchd

It writes ai.nanobot.gateway.plist to the LaunchAgents folder of your home Library. It starts the gateway with the same Python that installed nanobot. Logs go to the logs folder inside .nanobot. If it fails with address already in use, stop the gateway you started by hand first.

launchctl list | grep ai.nanobot.gateway
launchctl kickstart -k gui/$(id -u)/ai.nanobot.gateway
nanobot gateway uninstall-service --manager launchd

The gateway reads config.json only at startup. Restart it after every config change.

A LaunchAgent only runs while a user is logged in. On an unattended Mac, turn on automatic login for the account that runs nanobot. Then stop the Mac from sleeping, since sleep pauses the gateway and its scheduled jobs.

sudo pmset -a sleep 0
sudo pmset -a disksleep 0
sudo pmset -a displaysleep 10

More detail is in what happens when a Mac sleeps and the always-on Mac guide.

Security notes

• For production, the docs advise two settings together. Set restrictToWorkspace to true, and set tools.exec.sandbox to seatbelt on macOS. Seatbelt limits shell commands to the workspace folder.
• Neither setting limits network access. Keep secrets outside the workspace.
• The WebUI and the gateway health check listen on 127.0.0.1 by default. Leave them on this Mac only.
• Unknown senders on chat apps get a pairing code, not an answer. You approve them with /pairing approve and their code.
• The docs suggest environment variable references for API keys instead of raw keys in config.json. Either way, treat the .nanobot folder like a password file.

The simplest protection is a Mac that holds nothing else of yours. If the agent does something odd, the damage stops at that machine.

Running it on a MacRun Mac

Our agent plan is a dedicated Mac mini that never sleeps. It sits in our own private facility in New Jersey. Its login session comes back on its own after a reboot, so the nanobot LaunchAgent starts again. Claude Code and Codex come preinstalled. nanobot does not. You install it yourself, along with Python if needed, because you have full admin rights.

You can open the WebUI in the Mac's own browser through our browser desktop. The agent plan is $169 a month. MacRun sells no API keys. Use an API key from your model provider, which bills you for usage under its own terms.

When you do not need MacRun

nanobot is small and runs almost anywhere. The docs cover Linux services, Docker and a one click Render deploy. If you need nothing from macOS, any of those costs less than a Mac. And if you already have a Mac that stays on and logged in, use that.

MacRun is for developer work under our acceptable use policy. A nanobot that triages issues or runs nightly repo chores fits. One that runs your personal inbox does not. To compare plans, see the agent Mac page.