Skip to content
HUIAHUB

HKUDS/nanobot

nanobot

Ultra-lightweight, open-source, self-hosted personal AI agent framework in Python with WebUI, tools, memory, MCP, multi-agent workflows, automation, and chat apps

Metrics updated Established+0.5% 7d
View on GitHub (opens in a new tab)Homepage / demo

GitHub metrics

Stars
49K
+229 this week
Forks
8.6K
30-day growth
—
Open issues
215
49K49K49KOct 4, 2026Oct 13, 2026
GitHub stars from the official GitHub API, recorded each time the repository was checked (3 days).
GitHub stars by day
DayGitHub stars
2026-10-0448762
2026-10-1048920
2026-10-1348991

What it does

nanobot is a self-hosted personal AI agent framework in Python from HKUDS. You run it on your own computer or server and talk to it through a browser WebUI, the terminal, or chat apps such as Telegram, Discord, Slack, WeChat, email and Mattermost.

The agent can read and write files, run shell commands, search and fetch web pages, call MCP servers, schedule jobs with cron, generate images and hand work to subagents. Session history and long-term memory are handled by a component the project calls Dream. Models come from OpenAI-compatible APIs or local servers such as Ollama and vLLM, with fallback models configurable. nanobot can also expose its own OpenAI-compatible API, and it has a Python SDK for integrations.

The stable track is the nanobot-ai package on PyPI, installed with a one-line script, uv or pip; the latest release is v0.3.5. Newer and experimental features land on the main branch first and need a source install. Documentation is at nanobot.wiki in ten languages.

Why it matters

nanobot is for people who want an always-on assistant they control. It runs on hardware you choose, reaches you through chat apps you already use, and works with hosted or local models. The authors keep the core small and readable, which helps if you plan to inspect the code or extend it. Deployment guides cover Docker, Linux services and macOS LaunchAgent.

Main features

  • Browser WebUI, terminal UI and chat app channels
  • Tools for files, shell, web search and fetch, MCP, cron and image generation
  • Subagent delegation and long-horizon goals
  • Long-term memory through the Dream component
  • OpenAI-compatible providers, local models and fallback models
  • OpenAI-compatible API and Python SDK for integrations
  • Deployment as a long-running local or server-side gateway

Who it's for

  • Developers who want a personal agent running on their own machine or server
  • People who want to reach an assistant from Telegram, Discord, Slack, WeChat or email
  • Builders who need an agent backend with an OpenAI-compatible API or Python SDK
  • Users of local models through Ollama or vLLM

Strengths

  • Fully self-hosted under the MIT licence
  • Many chat channels plus a WebUI and terminal from one agent
  • Works with hosted and local models, with fallbacks
  • Guided setup for readers new to terminals and API keys

Limitations

  • The README says the newest features require a source install, while PyPI releases trade those for stability
  • Only two releases in the last 90 days, so the stable package can lag the main branch
  • You supply and configure model providers and keys yourself
  • Exposing the WebUI beyond localhost or deploying to the cloud needs extra setup

Getting started

The install script sets up nanobot-ai from PyPI in a virtual environment and, on a desktop, opens the WebUI to configure a model. Pass --dry-run to see the plan first, or install with uv.

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

Requirements: Python 3.11 or newer; Git and Bun only for a source install; an API key for a model provider or a local model server.

Always follow the official instructions in the README on GitHub. This overview is our summary, not a copy.

Sources