nanobot: A Self-Hosted AI Agent Runtime with a Small, Readable Python Core

What nanobot actually solves

nanobot targets a specific gap: a personal AI agent that you can run on your own hardware without a heavy platform. The README describes it as an "ultra-lightweight, open-source, self-hosted personal AI agent framework written in Python." It is not a cloud service or a multi-tenant deployment. It is for individuals who want an agent that persists across sessions, can call tools, and connects to chat apps they already use. The core problem is that most agent frameworks are either too big to understand or too tied to a vendor. nanobot tries to be small enough to read and modify, while still offering features like long-term memory and MCP integration. If you are a developer or a tinkerer who wants to own the stack, this is the pitch. If you are an enterprise looking for a managed solution, this is not it.

How nanobot works: core architecture and data flow

The repository layout and documentation point to a modular design. The core is Python, with a WebUI and a TUI (terminal UI) that are bundled or fetched as archives. The README mentions "tools, long-term memory, MCP integrations, model routing, multi-agent delegation, scheduled automation, and an OpenAI-compatible API." The data flow appears to be: a user interacts through a chat app, the WebUI, or the terminal; the agent runtime processes the input, decides which tools to call, possibly delegates to subagents, and stores session history and long-term memory via a feature called Dream. The README links to an architecture document for the internals. What is clear is that nanobot is not a single script; it is a runtime that can run as a long-lived gateway. The OpenAI-compatible API means you can integrate it with other applications that expect an OpenAI-style endpoint. The mention of "model routing" and "fallbacks" suggests that nanobot can switch between different LLM providers based on availability. This is a practical design for a personal agent that needs to work with local models and cloud APIs.

Getting nanobot running: installation and first steps

The README offers several installation paths, which is a strength. For a stable experience, you can install from PyPI with pip or uv. The one-command installer is the fastest route on macOS and Linux: `curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh`. On Windows, you use PowerShell with `irm ... | iex`. The installer avoids system-wide pip installs by using a virtual environment, `uv`, `pipx`, or a managed venv under `~/.nanobot/venv`. It also prints the exact command it used, which helps if `nanobot` is not on your PATH. For source installs, you need Git and Bun, because the source checkout runs the matching TUI directly instead of downloading a release binary. After installation, the default command on a fresh desktop starts `nanobot webui`, and you configure your first provider and model in Settings → Models. The README also mentions a guided walkthrough for people without technical background, which is a thoughtful addition. The `--dry-run` flag lets you see the plan without changing your environment, which is useful for cautious users.

Key features: tools, memory, and chat app integration

nanobot's feature list is broad for a "lightweight" tool. It supports tools such as files, shell, web search, web fetch, MCP, cron, image generation, and subagents. That is a lot of surface area. The long-term memory feature, called Dream, is a differentiator; the README claims it keeps session history and long-term memory. The README links to a memory document for how Dream works. Chat app integration is another major pillar: Telegram, Discord, Slack, WeChat, Email, Mattermost, and others. This makes nanobot a gateway that can sit between your chat apps and your LLM providers. The README also mentions scheduled automation and long-horizon goals, which suggests it can run tasks over extended periods. The OpenAI-compatible API is a practical touch for developers who want to reuse existing tooling. The breadth is impressive, but it also raises the question of how well each feature is maintained. A small core with many integrations can lead to uneven quality.

Limitations and failure modes

The README is honest about some constraints. Python 3.11 or newer is required, which excludes older systems. The source install requires Bun, which is an extra dependency. The TUI archive is fetched on first use with checksums, which means you need network access and trust in the download. The installer has to handle `externally-managed-environment` errors on some systems, which is a real friction point. For headless or SSH setups, the README mentions a terminal setup wizard, but the default for a fresh desktop is to launch the WebUI, which might confuse users who expect a CLI-only experience. The biggest limitation is that nanobot is designed for personal use. It is not a multi-tenant platform, so if you need to serve multiple users with isolation, this is the wrong tool. Also, the documentation is extensive but not exhaustive in the README; you will need to consult the docs folder for configuration details. The Dream memory feature is a selling point, but its quality is unproven from the README. A personal agent with faulty memory can be worse than none.

Alternatives and how nanobot differs

A common alternative is a framework like AutoGen or LangChain, but those are more like libraries for building agents, not a ready-to-run agent gateway. Another alternative is something like Ollama, but Ollama is primarily a model runner, not an agent framework with tools and memory. A closer comparison is something like Open WebUI, which provides a chat interface for local models. The key difference with nanobot is that it is a self-contained runtime with a WebUI, TUI, and chat app connectors out of the box. You do not need to assemble a pipeline from different libraries. The trade-off is that you are tied to nanobot's design choices. If you prefer a more programmable approach, you might choose a library and build your own. If you want a turnkey personal agent, nanobot is more direct.

Maintenance, license, and upgrade cost

nanobot is licensed under MIT, which is permissive and allows commercial use and modification. The project is active, with a recent release v0.4.0 in October 2026, following v0.3.5 in September and v0.3.0 in July 2026. The README offers two tracks: stable from PyPI or source. The source track requires a `git pull --ff-only` and editable dependency sync, which is straightforward for developers. The stable track updates with the same package tool you used to install. The upgrade cost is moderate: since the project is evolving, breaking changes are possible between minor versions. You should read the changelog before upgrading. The bundled TUI is version-matched and checksummed, which reduces supply chain risk but adds complexity. The README also mentions that the TUI archive includes licenses and source offers, which is a nice touch for compliance. Overall, the maintenance appears healthy, but you should verify the docs for any migration guides.

Editorial conclusion

Adopt nanobot if you want a self-hosted personal AI agent that you can inspect and modify, with a small Python core and support for tools, memory, and MCP. Avoid it if you need a production-grade multi-user platform or if you are not comfortable editing config files and managing a Python environment. Before adopting, verify that your preferred chat apps and LLM providers are supported in the current version, and test the Dream memory feature with your actual workloads, since long-term memory quality is a key selling point that may vary. The project is active, with recent releases, but you should check the changelog for breaking changes between v0.3.x and v0.4.0 before upgrading.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes