README.md
<a href="https://github.com/HKUDS/nanobot/graphs/commit-activity" target="_blank">
</a>
<a href="https://github.com/HKUDS/nanobot/issues?q=is%3Aissue%20is%3Aclosed" target="_blank">
</a>
<a href="https://twitter.com/intent/follow?screen_name=nanobot_project" target="_blank">
</a>
<a href="https://nanobot.wiki/docs/latest/getting-started/nanobot-overview"></a>
<a href="./COMMUNICATION.md"></a>
<a href="./COMMUNICATION.md"></a>
<a href="https://discord.gg/MnCvHqpUGB"></a>
๐ nanobot is an open-source, ultra-lightweight agent runtime for people who want to own their AI agent stack. It gives you a small, readable core plus the practical pieces for real long-running agents: WebUI, chat channels, tools, memory, MCP, model routing, and deployment.
/goal holds sustained objectives across turns, WebUI now ships inside the wheel, image generation end to end, 5 new providers with fallback_models, and a real agent-loop refactor. Please see release notes for details./goal for long-term objectives, visible multi-step progress, long-horizon missions in chat./history, and steadier long chats. Please see release notes for details./history command, smarter session replay caps, smoother Discord / Slack threads.ask_user choices, macOS LaunchAgent deployment, MSTeams stale-reference cleanup.disabled_skills config./status command.litellm with native openai + anthropic SDKs. Please see commit./restart, and sturdier memory.[!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.
Install from source
git clone https://github.com/HKUDS/nanobot.git
cd nanobot
pip install -e .
Install with uv
uv tool install nanobot-ai
Install from PyPI
pip install nanobot-ai
1. Initialize
nanobot onboard
2. Configure (~/.nanobot/config.json)
Configure these two parts in your config (other options have defaults). Add or merge the following blocks into your existing config instead of replacing the whole file.
Set your API key (e.g. OpenRouter, recommended for global users):
{
"providers": {
"openrouter": {
"apiKey": "sk-or-v1-xxx"
}
}
}
Set your model (optionally pin a provider โ defaults to auto-detection):
{
"agents": {
"defaults": {
"provider": "openrouter",
"model": "anthropic/claude-opus-4-6"
}
}
}
3. Chat
nanobot agent
The WebUI ships inside the published wheel โ no extra build step. Just enable the WebSocket channel and open it in your browser.
<p align="center"> </p>1. Enable the WebSocket channel in ~/.nanobot/config.json
{ "channels": { "websocket": { "enabled": true } } }
2. Start the gateway
nanobot gateway
3. Open the WebUI
Visit http://127.0.0.1:8765 in your browser. To open it from another device on your LAN, see WebUI docs โ LAN access.
[!TIP] Working on the WebUI itself? Check out
webui/README.mdfor the Vite dev server (HMR) workflow.
๐ nanobot stays lightweight by centering everything around a small agent loop: messages come in from chat apps, the LLM decides when tools are needed, and memory or skills are pulled in only as context instead of becoming a heavy orchestration layer. That keeps the core path readable and easy to extend, while still letting you add channels, tools, memory, and deployment options without turning the system into a monolith.
Browse the repo docs for the latest features and GitHub development version, or visit nanobot.wiki for the stable release documentation.
PRs welcome! The codebase is intentionally small and readable. ๐ค
| Branch | Purpose |
|---|---|
main | Stable releases โ bug fixes and minor improvements |
nightly | Experimental features โ new features and breaking changes |
Unsure which branch to target? See CONTRIBUTING.md for details.
Roadmap โ Pick an item and open a PR!
This project was started by Xubin Ren as a personal open-source project and continues to be maintained in an individual capacity using personal resources, with contributions from the open-source community. Feel free to contact [email protected] for questions, ideas, or collaboration.
</picture>