Install Nanobot v0.3.0 Lightweight AI Agent

Ever type pip install nanobot, get a CLI that dies after the next upgrade, and assume the agent is broken? Wrong package name. Fix that first.

Nanobot v0.3.0 (The Agency Release, July 2026) is HKUDS’s open-source, self-hosted personal agent runtime in Python. WebUI, terminal chat, tools, memory, MCP, and chat-app gateways sit in a small core. This guide installs v0.3.0, configures it, and verifies it – using the failure order people actually hit.

System requirements before you touch pip

Hard floor from the PyPI project page and the repo README: Python 3.11+. 3.10 and earlier are out.

You still need an API key – or a local OpenAI-compatible server (Ollama, vLLM, etc.). The software itself is free (MIT). Model spend is yours.

Official download source (use these URLs only)

Code and releases: github.com/HKUDS/nanobot. Docs hub: nanobot.wiki.

The installable name on PyPI is nanobot-ai. Not nanobot. Turns out a separate PyPI project also ships something under that import path – GitHub issue #846 is full of ModuleNotFoundError / wrong-CLI reports after upgrades. Install nanobot-ai only.

Install Nanobot v0.3.0 step by step

Pick one method. Mixing system pip with random global installs is how PATH ghosts start.

Method A – one-command installer (fresh desktop)

macOS / Linux:

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

Windows PowerShell:

irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex

README path: pulls/upgrades nanobot-ai from PyPI through an active venv, uv, pipx, or a managed venv under ~/.nanobot/venv. On a fresh local desktop it tends to hand you the WebUI path so provider setup finishes in the browser.

Method B – uv or pip (day-to-day)

# isolated tool install (clean PATH)
uv tool install nanobot-ai

# or inside a venv you control
python -m venv .venv
source .venv/bin/activate # Windows: .venvScriptsactivate
python -m pip install nanobot-ai

nanobot --version

You want a v0.3.0-line string when PyPI matches the Jul 25, 2026 wheel. Shell can’t find nanobot? Try uv tool run --from nanobot-ai nanobot --version or python -m nanobot --version.

Method C – Docker Compose (servers)

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
docker compose run --rm nanobot-cli onboard
# edit ~/.nanobot/config.json on the host - add provider keys
docker compose up -d nanobot-gateway
docker compose logs -f nanobot-gateway

From official deployment docs: mount host state at ~/.nanobot:/home/nanobot/.nanobot (UID 1000). Build from the repo Dockerfile when you care who built the image.

Pro tip:externally-managed-environment on macOS/Linux? Skip --break-system-packages. One-command installer, uv tool install nanobot-ai, pipx install nanobot-ai, or a real venv. That’s what the official troubleshooting guide tells you to do.

First-time configuration that actually boots

Installer already opened guided setup? Jump to Settings → Models. Otherwise do this:

1. nanobot onboard – creates ~/.nanobot/config.json and ~/.nanobot/workspace/.
2. Set a provider + model preset. Merge into the existing file. Don’t paste a partial snippet over the whole JSON.
3. nanobot webui (current releases) or nanobot gateway, then open http://127.0.0.1:8765.

{
 "providers": {
 "custom": {
 "apiKey": "your-api-key",
 "apiBase": "https://api.example.com/v1"
 }
 },
 "modelPresets": {
 "primary": {
 "label": "Primary",
 "provider": "custom",
 "model": "model-id-from-your-provider",
 "maxTokens": 8192,
 "contextWindowTokens": 200000,
 "temperature": 0.1
 }
 },
 "agents": {
 "defaults": {
 "modelPreset": "primary"
 }
 }
}

Named presets power in-session model switching in v0.3.0. Put secrets in env vars when you can – the project’s security notes lean that way.

Ever notice how half the “agent stacks” feel like furniture without the Allen key? Nanobot’s split – small core, one config tree, explicit gateway – is the Allen key. Still your job to put the shelves up.

Verify the lightweight AI agent actually works

Official diagnosis order. Stop at the first red layer:

nanobot --version
nanobot status
nanobot agent -m "Hello!"
# only if CLI works:
nanobot gateway
# health (not the UI):
curl -s http://127.0.0.1:18790/health

status never calls the model. Want Config ✓, Workspace ✓, active preset’s provider ready. Unused providers saying not set is normal. A real reply from agent -m "Hello!" means install + keys + workspace writes are good.

WebUI lives on 8765. Port 18790 is health only – don’t debug a blank tab there.

The catch is most “install failed” threads are still on layer 1 or 2.

Common install errors and fixes

• nanobot: command not found – Scripts dir off PATH, or a different Python than the install. Use python -m nanobot ..., or reinstall with the same interpreter. Reuse the full command the installer printed.
• No module named nanobot after upgrade – Wrong/extra package or mixed envs. python -m pip show nanobot-ai, uninstall stray nanobot if present, reinstall nanobot-ai into one env.
• externally-managed-environment – System Python lock. uv / pipx / venv / installer only.
• Browser blank on :18790 – Open http://127.0.0.1:8765. Health ≠ WebUI (troubleshooting default-ports table).
• Docker ports published, nothing connects – Loopback default inside the container. deployment.md is blunt: set gateway.host and channels.websocket.host to 0.0.0.0 and set tokenIssueSecret (auth is required once you leave loopback). Mount /home/nanobot/.nanobot, not /root/.nanobot. Permission errors: sudo chown -R 1000:1000 ~/.nanobot.
• Gateway stuck on “Installing optional feature” – Channel deps reinstalling after upgrade or a fresh uv/pipx env. Wait it out, or bake channels at image build time per deployment guidance.
• 401 / model not found – Wrong provider block, whitespace in the secret, or a model ID from another gateway. Fix config, then prove with nanobot agent -m "Hello!" before any chat app.

Upgrade from previous versions and uninstall

Upgrade the same way you installed:

python -m pip install -U nanobot-ai
# or
uv tool upgrade nanobot-ai
# or re-run the one-command installer (upgrades from PyPI)

Restart any long-running gateway after that.

v0.3.0 upgrade notes matter if you used WhatsApp before: Neonize replaced the old Node/Baileys bridge. Drop bridgeUrl/bridgeToken, run nanobot plugins enable whatsapp, log in again. Sustained work is explicit via /goal. Remote API/WebUI binds need auth tokens – loopback defaults stay intentional.

# stop runtime
nanobot gateway stop 2>/dev/null || true
nanobot gateway uninstall-service --manager systemd # Linux user service, if installed
nanobot gateway uninstall-service --manager launchd # macOS, if installed

# remove package
python -m pip uninstall nanobot-ai
# or: uv tool uninstall nanobot-ai

# optional full wipe (sessions, memory, config)
rm -rf ~/.nanobot

Docker: docker compose down, remove the image you built, delete the host ~/.nanobot mount if you want zero residual data.

Curious how much of “agent reliability” is just refusing to debug WebUI before agent -m works? That ordering saves more evenings than any new model preset.

FAQ

Is Nanobot free, and what does v0.3.0 cost to run?

MIT-licensed. Free software. You pay the LLM provider – or the electricity for a local model. No Nanobot SaaS fee on the self-hosted path.

pip works but nanobot webui isn’t found – am I on an old build?

Probably. Older docs push nanobot gateway plus a manual browse to 8765. Current README treats nanobot webui as the desktop front door. Check nanobot --version; if you’re below Agency-era builds, upgrade nanobot-ai. Or stick with nanobot gateway and open http://127.0.0.1:8765 yourself.

Can I expose this on a VPS safely?

Localhost defaults exist on purpose. v0.3.0 expects auth tokens once API/WebUI leave loopback. Same rule as the Docker bind trap above: 0.0.0.0 only with tokenIssueSecret (or equivalent), TLS in front, and tight allowFrom/pairing on chat channels before a public bot token can reach shell tools. Don’t start by publishing health wide-open and calling it done.

Next: python -m pip install nanobot-ai && nanobot --version && nanobot webui. One provider under Settings → Models. Send Hello! in a new topic. If that replies, park the process in the background the way your deploy docs prefer (desktop WebUI background mode or the systemd/LaunchAgent path) – and leave Telegram for after agent -m is boringly reliable.