Nanobot hands-on: run a 4,000-line personal agent on your own machine

A personal agent you can install with pip, point at a local model, and trust with your files — nanobot packs a browser workbench, scheduled automations, and file-backed memory into a core small enough to read. This guide installs 0.4.0, wires it to Ollama, and proves every step, including the two that did not work as expected.

• Who: Nanobot (HKUDS/nanobot, MIT), a self-hosted personal AI agent written in Python.
• What: pip install, JSON config, a one-shot terminal agent, file tools, Dream memory, scheduled automations, and a browser WebUI.
• When: verified October 30, 2026: nanobot-ai 0.4.0, Ollama 0.40.11, qwen3:0.6b.
• Requirement: Python 3.11 or newer, plus a model — local Ollama or a provider key. No account for the local path; chat channels need bot tokens and were not tested here.

Why this matters now

Nanobot is a self-hosted personal AI agent small enough to read and cheap enough to run anywhere. It comes from the HKUDS research group, it is MIT-licensed, and on October 30, 2026 its GitHub page showed 49,676 stars, 8,699 forks, and 5,170 commits behind it. The immediate trigger is a release: v0.4.0 landed on October 28, 2026, adding durable conversation history, a richer browser workbench, and terminal diagrams — and the project has been gaining hundreds of stars a week since (FindaRepo's October 30 local-AI ranking credits it with +372 stars in seven days). Community write-ups put the agent core at roughly 4,000 lines of Python, a deliberate contrast with agent platforms whose cores run to hundreds of thousands of lines. That smallness is the point: you can install it with pip, point it at a model, and have an agent that reads files, runs shell commands, keeps memory, and runs on a schedule — without handing your notes to someone else's cloud.

What you get for that smallness is a complete loop, not a demo. One command installs it. A short config file chooses the model. A one-shot command sends a single message and prints the reply. The same agent can work in a browser workbench, over Telegram or Discord, or from the terminal, and it keeps long-term memory through a consolidation job called Dream. This guide works through that loop in order, and every command and output below was run in a sandbox on October 30, 2026, against nanobot-ai 0.4.0 and a local Ollama model. Where the sandbox limited what could be proven — and it did, twice — the article says so plainly instead of smoothing it over.

What you'll need

• Python 3.11 or newer. The README requires it; this guide used Python 3.12 inside a virtual environment. No Node build, no Docker, no compiler.
• A model. Either a provider key (OpenAI, Anthropic, DeepSeek, OpenRouter, and many more are supported) or a local model server. This guide uses Ollama with qwen3:0.6b, a 522 MB model, because it costs nothing and keeps everything on the machine — with one honest caveat, covered in Step 5, about what a 0.6 billion-parameter model can and cannot do.
• About 300 MB of disk for nanobot and its dependencies, plus whatever your model weighs. The pip install here pulled the usual Python web stack (httpx, pydantic, typer, and the MCP client) and nothing heavier.
• No account and no API key for the local path. Ollama needs neither. A provider key is only needed if you choose a hosted model instead.
• One sandbox note before you start. If you run behind a proxy that intercepts loopback traffic — this sandbox does — export NO_PROXY="localhost,127.0.0.1" before starting nanobot, or its calls to 127.0.0.1:11434 will be routed to the proxy and fail. On a normal home machine you can skip this line.

Step 1 — Install it and verify the version

Install the stable package into a virtual environment and confirm the version string. The version matters: this guide was written against 0.4.0, the release current on October 30, 2026, and the CLI surface below matches it.

python3 -m venv .venv
source .venv/bin/activate
pip install nanobot-ai
nanobot --version

Expected output:

🐈 nanobot v0.4.0

Run nanobot --help at any point to see the command set: onboard, agent, webui, gateway, serve, channels, provider, status, and a few more. The three you need for this guide are onboard, agent, and status. A global --home flag selects the instance directory; without it, nanobot uses ~/.nanobot. This guide passes --home explicitly so the test instance stays separate from any other install — replace it with nothing on your own machine and the defaults apply.

Step 2 — Scaffold the instance with onboard

onboard without --wizard creates the configuration and workspace non-interactively. The wizard is the interactive route; the plain command is the scriptable one.

nanobot --home ./home onboard

Expected output:

✓ Created config at /home/you/nanobot-home/config.json
  Created AGENTS.md
  Created HEARTBEAT.md
  Created SOUL.md
  Created USER.md
  Created memory/MEMORY.md
  Created prompts/README.md
  Created memory/history.jsonl

✓ nanobot is ready. Run: nanobot webui

Two things are worth knowing about what just landed. The config file is plain JSON, so every setting in the rest of this guide is a file edit, not a hidden database write. And the workspace ships with its own AGENTS.md, SOUL.md, USER.md, and memory/MEMORY.md — the agent's profile and long-term memory live in files you can read, back up, and correct by hand.

Step 3 — Point it at a local model

Start Ollama and make sure the model is present. The Ollama binary used here is 0.40.11, and qwen3:0.6b was already in the local model cache from earlier testing, so no fresh download was measured for this step; on a clean machine, ollama pull qwen3:0.6b fetches the 522 MB model first.

ollama serve
ollama list

Expected output (abridged):

NAME                    SIZE      MODIFIED
nomic-embed-text:latest 274 MB    4 weeks ago
qwen3:0.6b              522 MB    4 weeks ago

Ollama's own metadata lists qwen3:0.6b as supporting tools, which is what the file task in Step 5 needs. Now edit the three fields that matter in home/config.json: the default model, the default provider, and the Ollama endpoint. The provider entry already exists with empty values; only these fields change.

{
  "agents": {
    "defaults": {
      "model": "qwen3:0.6b",
      "provider": "ollama"
    }
  },
  "providers": {
    "ollama": {
      "apiBase": "http://127.0.0.1:11434/v1"
    }
  }
}

The /v1 suffix matters: nanobot's Ollama provider speaks the OpenAI-compatible API, and its default base is http://localhost:11434/v1. Using 127.0.0.1 instead of localhost here pairs with the NO_PROXY note above. Verify the configuration before sending anything:

nanobot --home ./home status

Expected output (abridged):

🐈 nanobot Status

Config: /home/you/nanobot-home/config.json ✓
Workspace: /home/you/nanobot-home/workspace ✓
Model: qwen3:0.6b
Agent: ✓ provider/model configuration is ready

If status does not say the configuration is ready, fix the config before continuing — every later step fails downstream of a bad model setting, and the error messages will not point back here.

Step 4 — Get a first reply with one command

The fastest check is a one-shot message. It exercises the whole chain — config, provider, model, reply rendering — without opening any interactive UI:

nanobot --home ./home agent -m "Reply with exactly: HELLO-NANOBOT" --no-markdown --no-logs

Expected output (abridged):

🐈 nanobot
✻ Okay, the user wants me to reply with exactly "HELLO-NANOBOT".
✻ Let me check the tools available.
✻ ...
HELLO-NANOBOT

The final line is correct, and the chatter above it is the lesson: a 0.6 billion-parameter model narrates its own reasoning out loud, including wrong turns about tools it never calls. For a smoke test that is fine — the reply arrived. For real work it is a warning, and Step 5 shows exactly where the warning bites.

Step 5 — Give it a real file task (and learn the small-model limit)

Put a notes file in the workspace and ask for a summary. This is the README's own first file task, and it is the smallest job that proves tool use rather than chat:

cat > home/workspace/notes.txt <<'EOF'
Project Mercury field notes, October 2026
- The riverside sensor array recorded 41.2 mm of rain on Oct 12, the wettest day of the month.
- Battery pack B failed its load test on Oct 19 and was replaced the same day.
- The team agreed to move the weekly sync from Friday to Thursday, starting Nov 6.
EOF
nanobot --home ./home agent -m "Read notes.txt and write a short summary to summary.md. Reply with only the word DONE when the file is written." --no-markdown --no-logs

With qwen3:0.6b, the tool loop itself worked — the transcript shows the agent calling the write tool, and summary.md was created. But the content was two characters long: 13. The model executed the plumbing and failed the job. That is the honest result for this model size, and it matches what other agent projects report for sub-billion-parameter models: they can prove the loop, they cannot be trusted with the work. Do not run real file tasks on qwen3:0.6b. Use a tool-capable 7 billion-parameter-or-larger local model, or a hosted provider model, for anything you care about.

To prove the loop end to end with correct output, the same task was re-run against a tiny scripted stand-in: a local HTTP server speaking the OpenAI chat-completions API that answers in three turns — first a read_file call for notes.txt, then a write_file call for summary.md with the correct summary, then DONE. The transcript shows both tool calls landing, and the resulting file reads:

Project Mercury field notes — summary
- Wettest day: 41.2 mm of rain on Oct 12 (riverside sensor array).
- Battery pack B failed its load test on Oct 19 and was replaced the same day.
- Weekly sync moves from Friday to Thursday, starting Nov 6.

Two details from that stand-in are worth keeping if you ever build a test double for an agent. First, nanobot requests stream: true, so the stand-in must answer with server-sent-events chunks ending in a finish reason; a plain JSON reply fails with "Model stream ended before a finish reason was received." Second, the tool names are read_file (arguments: path) and write_file (arguments: path, content) — those are the names in nanobot 0.4.0's tool registry, and the write result reports the character count it wrote.

Step 6 — Open the browser workbench (and one sandbox failure, honestly reported)

The WebUI is the browser workbench for topics, workspace controls, skills, and automations, and it ships inside the published wheel — no separate frontend build. Launch it without opening a browser on a headless machine:

nanobot --home ./home webui --no-open --yes

The --yes flag is not optional decoration. The first attempt without it stopped with: "WebUI setup needs confirmation. Re-run with --yes or use nanobot onboard --wizard." With --yes, the gateway starts and the log shows what it registers: 22 tools (including read_file, write_file, exec, web_fetch, and web_search), a websocket channel, the Dream consolidation job every 2 hours, and a heartbeat job every 1,800 seconds, with a health endpoint on port 18790.

Then, in this sandbox, it crashed. The gateway's config watcher hit the machine's file-watch ceiling — OSError: OS file watch limit reached from the watchfiles library — and the launcher reported "WebUI did not become ready." The cause is environmental, not a nanobot defect: this shared VM's inotify budget is exhausted by other processes, and its /proc/sys is read-only, so the limit cannot be raised from here. On a typical single-user machine this step should proceed to the login link on port 8765; here it is the one step that could not be completed, and it is reported as such rather than claimed. If you hit the same error on your own machine, check how many watchers your other tools are holding before blaming the agent.

Step 7 — Keep the agent running after you close the terminal

Interactive clients are not the long-running part; the gateway is. Once a model is configured, promote it to background mode and manage it with the gateway commands, all verified from --help and the gateway log above:

nanobot gateway --background
nanobot gateway status
nanobot gateway logs
nanobot gateway restart
nanobot gateway stop

Background mode keeps channels and automations alive after clients exit, but it does not survive a reboot and does not replay missed schedules after a restart — use the install-service subcommand for a systemd user service or macOS LaunchAgent if you want startup supervision. Dream consolidation runs every 2 hours by default; the README's own advice stands: a conversational acknowledgement that a preference was saved is not proof. Send /compact and then /dream, wait for each to finish, and check the actual changes to USER.md or memory/MEMORY.md in the workspace.

When to use this vs alternatives

Use nanobot when you want a self-hosted agent you can fully inspect: the config is JSON, the memory is files, the install is pip, and the whole thing runs on hardware you already own. It fits a personal assistant that files notes, watches a folder, answers from your documents, or runs scheduled checks — especially where sending those documents to a hosted provider is the thing you are trying to avoid.

Use something else when the job needs frontier-model judgment on every turn: a tiny local model will not supply it, and at that point you are paying a provider either way, so pick the agent whose tooling fits your editor rather than the one with the smallest core. And use plain scheduled scripts, not an agent, when the task is fully specified — an agent that can browse and write files is the wrong tool for a job a cron entry and an API call already describe. Nanobot's own OpenClaw-adjacent history is visible in the blog's earlier OpenClaw tutorial; the difference here is scale and language — a small Python core you can read in an afternoon versus a platform you operate.

The takeaway

Nanobot delivers what its star count promises, with the limits stated on the tin. Install is one pip command, configuration is one JSON file, the one-shot reply works against a free local model, and the tool loop provably reads and writes files. The two things to carry away are the model caveat — a 0.6 billion-parameter model proves the loop and fails the job, so bring a capable model for real work — and the operating caveat — the gateway is a real background service with real system dependencies, including file watchers, and a crowded machine can starve it. Neither caveat diminishes the core result: a personal agent you own, in about ten minutes of setup, that answers in your terminal and keeps its memory in files you can read.

Verification notes

Every command above was run on October 30, 2026, in a Linux sandbox: pip install of nanobot-ai 0.4.0, onboard, status, the one-shot reply, the file task against both qwen3:0.6b and the scripted stand-in, and the WebUI launch. The gateway's 22-tool registry, Dream interval, and heartbeat interval come from its own startup log. The star, fork, and commit counts come from the project's GitHub page on the same day; the +372-stars-in-seven-days figure comes from FindaRepo's October 30 local-AI ranking; the roughly-4,000-line core figure comes from community write-ups, not from a measurement here. Connecting a chat channel (Telegram, Discord, Slack, WeChat, Email, Mattermost, or Linear) is documented in the README but was not exercised — it needs a bot token — and the serve command's OpenAI-compatible API server was not run either. The Ollama binary and model were already present from earlier testing, so no fresh Ollama download was measured.

Sources

• HKUDS/nanobot on GitHub — README, install instructions, Quick Start, WebUI and deployment sections (read October 30, 2026).
• nanobot-ai on PyPI — stable package, version 0.4.0.
• Run open models on your own machine: the complete Ollama hands-on guide — AI Frontier Post's own Ollama setup reference.