English | 简体中文 | 繁體中文 | Español | Français | Bahasa Indonesia | 日本語 | 한국어 | Русский | Tiếng Việt
Discord · X · WeChat / Feishu
nanobot
🐈 nanobot is an ultra-lightweight, open-source, self-hosted personal AI agent framework written in Python. It runs in a WebUI, terminal, or chat apps and combines tools, long-term memory, MCP integrations, model routing, multi-agent delegation, scheduled automation, and an OpenAI-compatible API in a small, readable core.
Start Here
| You want to... | Go to |
|---|---|
| Install nanobot with no terminal/config background | Start Without Technical Background |
| Install quickly and get one CLI reply | Install and Quick Start |
| Open the bundled browser UI | WebUI |
| Connect Telegram, Discord, WeChat, Slack, Email, Mattermost, or another chat app | Chat Apps |
| Configure providers, fallback models, Langfuse, MCP, web tools, or security | Docs and Configuration |
| Understand or extend the internals | Architecture and Development |
| Deploy to the cloud or keep nanobot running as a service | Deployment |
What can nanobot do?
nanobot is a self-hosted personal AI agent runtime. It can:
- run in a browser WebUI or terminal
- connect to Telegram, Discord, Slack, WeChat, Email, Mattermost, and other chat apps
- use tools such as files, shell, web search, web fetch, MCP, cron, image generation, and subagents
- keep session history and long-term memory through Dream
- run long-horizon goals and scheduled automations
- expose a Python SDK and OpenAI-compatible API for integrations
- deploy as a long-running local or server-side agent gateway
💡 Why nanobot
- Persistent workflows: goals, memory, tools, and chat context survive long-running work.
- Chat-native reach: WebUI, API, Telegram, Feishu, Slack, Discord, Teams, email, and Mattermost.
- Model freedom: OpenAI-compatible APIs, local LLMs, image generation, search, and fallbacks.
- Small core: readable internals with MCP, memory, deployment, and automation built in.
- Own your stack: inspect, customize, self-host, and extend without a giant platform.
📦 Install
[!IMPORTANT] If you want the newest features and experiments, install from source.
If you want the most stable day-to-day experience, install from PyPI or with
uv.
Pick one install method:
| Track | Install with | Update with | What runs |
|---|---|---|---|
| Stable | installer, uv, or pip |
the same package tool | one released Python/WebUI/TUI version |
| Current source | editable Git checkout | git pull --ff-only + editable dependency sync |
Python, WebUI, and TUI from that checkout |
Prerequisites: Python 3.11 or newer. Git and Bun are only needed for a source install. Published packages include the WebUI and fetch a checksummed, version-matched TUI archive—with its licenses, notices, corresponding application source, source offer, and relinking instructions—on first use.
If terminals, API keys, or config files are new to you, use the guided zero-background walkthrough in Start Without Technical Background instead of this compact README path.
One-command setup
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
The default command installs or upgrades nanobot-ai from PyPI. On a fresh local desktop, it then starts nanobot webui so you can configure the first provider and model in Settings → Models. SSH, headless, existing-config, and older-release paths keep the terminal setup wizard. The installer avoids system-wide pip installs by using an active virtual environment, uv, pipx, or a managed venv under ~/.nanobot/venv. It also prints the exact command it used to run nanobot; reuse that full command below if nanobot is not on PATH.
To preview the plan without changing your environment, pass --dry-run.
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dry-run
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dry-run
If you prefer to inspect the script first, open scripts/install.sh or scripts/install.ps1.
Install with uv
uv tool install nanobot-ai
Install from PyPI with pip
python -m pip install nanobot-ai
If pip reports externally-managed-environment on macOS or Linux, use the one-command installer, uv tool install nanobot-ai, pipx install nanobot-ai, or install inside a virtual environment.
Install from source
Clone the repository and install it in editable mode. Bun is required because the source checkout runs the matching TUI directly instead of downloading an older release binary.
git clone https://github.com/HKUDS/nanobot.git
cd nanobot
python -m venv .venv
Activate it with source .venv/bin/activate on macOS/Linux or
.venv\Scripts\Activate.ps1 in Windows PowerShell, then run:
python -m pip install -e .
After that, the normal commands are identical to a stable install. nanobot runs the TUI
from this checkout, and nanobot webui rebuilds stale frontend assets automatically. A later
git pull --ff-only updates the Python, TUI, and WebUI source together; rerun
python -m pip install -e . when Python dependencies change. Contributors should also read
CONTRIBUTING.md.
Verify the install:
nanobot --version
If nanobot is not on PATH, invoke it through the method that installed it: reuse the recommended installer's command, use uv tool run --from nanobot-ai nanobot ... or pipx run --spec nanobot-ai nanobot ..., or use the Python executable from the environment where pip installed the package.
🚀 Quick Start
Open nanobot in your browser
nanobot webui
This is the recommended first run. The launcher creates the config and workspace when needed, safely enables the local WebSocket channel after confirmation, starts or joins the shared local gateway, and opens http://127.0.0.1:8765. A fresh install can open before a model is configured, so setup continues in the browser instead of beginning in a JSON file. The first-run We