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
Install / Use
claude mcp add HKUDS -- npx -y github:HKUDS/nanobotIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AutomationSupported Platforms
Skill content
View source on GitHubnanobot
🐈 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:
Prerequisites: Python 3.11 or newer. Git is only needed for a source install. Published packages already include the WebUI; a current-source install needs bun or npm to build it.
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; combine it with --dev when you want to preview the main-branch install.
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
To install the current main branch instead, pass --dev:
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dev
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dev
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
bun or npm must be available. From an activated virtual environment:
git clone https://github.com/HKUDS/nanobot.git
cd nanobot
python -m pip install .
On Windows, if pip reports that it cannot launch npm, run cd webui, npm.cmd install --package-lock=false, npm.cmd run build, and cd .. in order, then retry the install. Contributors who need an editable checkout should follow CONTRIBUTING.md and webui/README.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 the 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 WebUI binds to localhost by default and is not exposed to your LAN.
Your first three steps
- Open Settings → Models and choose a provider, credential, and model.
- Start a new topic and send
Hello!to verify the connection. - Before project work, choose the intended workspace and access mode from the composer.
Any normal reply means the provider, model, workspace, and browser gateway are working together.
Keep nanobot running after you close the terminal
nanobot webui --background
This starts the same full gateway as nanobot webui, opens the browser, and leaves channels and automations running after the launcher exits. Complete first-time model setup with foreground nanobot webui before switching to background mode.
nanobot gateway status
nanobot gateway logs
nanobot gateway restart
nanobot gateway stop
Prefer a gateway-first workflow?
nanobot gateway
This skips WebUI setup and browser opening, then runs the same complete gateway in the current terminal. It is the familiar entry point if you are coming from OpenClaw or already operate agents as long-lived services. The WebUI remains available when its channel is configured; open it manually when needed.
Use nanobot gateway --background for the same direct entry point without keeping the terminal attached. For automatic startup and supervision by the operating system, see Deployment.
Prefer to work entirely in the terminal?
nanobot agent
This opens an interactive terminal chat with the same configured model, workspace, and tools while keeping its own CLI session history. It does not open a browser or keep chat channels and automations running after you exit. Type exit or press Ctrl+C when you are done.
For one request and an immediate exit, use:
nanobot agent -m "Hello!"
The one-shot form is useful for a quick provider check, shell scripts, and local automation. If you have not configured a model yet, run nanobot webui and open Settings → Models first.
Need manual JSON, another device on your LAN, or help with provider/model matching? Continue with Install and Quick Start, WebUI, or Troubleshooting.
If nanobot worked for you, a star on GitHub is the simplest way to support the project.
- Want a pasteable provider setup? See Provider Cookbook
- Want to understand provider/model matching? See Providers and Models
- Want web search, MCP, security settings, or more config options? See Configuration
- Want to run locally? See Ollama, vLLM or another local OpenAI-compatible server, and the full provider reference.
- Want to run nanobot in chat apps like Telegram, Discord, WeChat or Feishu? See Chat Apps
- Want Docker or Linux service deployment? See Deployment
<a id="deploy-to-render"></a>
☁️ Deploy
Render — one click
Deploy nanobot's gateway and bundled WebUI from the repository's ready-to-use Blueprint:
[
](https://render.com/deploy?repo=https://github.com/HKUDS/n
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
84.2kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
73.4kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
ruflo
73.0k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
CowAgent
47.1kOpen-source super AI assistant & Agent Harness. Plans tasks, runs tools and skills, self-evolves with memory and knowledge. Multi-agent, multi-model, multi-channel. Lightweight, extensible, one-line install.
