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 personal AI agent you can truly own. It keeps the agent core small and readable while giving you the practical pieces for real long-running work: WebUI, chat channels, tools, memory, MCP, model routing, automation, and deployment.
| 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 after the CLI works | WebUI |
| Connect Telegram, Discord, WeChat, Slack, Email, 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 |
/dream, macOS installer fixes./skill, steadier pairing.uv pip install fallback, QQ pairing./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.
Pick one install method:
Prerequisites: Python 3.11 or newer. Git is only needed for a source install; Node.js/Bun are only needed if you are developing the WebUI itself.
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, then starts nanobot onboard --wizard. It avoids system-wide pip installs by using an active virtual environment, uv, pipx, or a managed venv under ~/.nanobot/venv. If Quick Start finishes and you enabled the WebSocket channel, skip the manual initialize/configure steps below and go straight to Open the WebUI.
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
git clone https://github.com/HKUDS/nanobot.git
cd nanobot
python -m pip install -e .
Verify the install:
nanobot --version
1. Initialize
Skip this step if the one-command setup already started the wizard and Quick Start finished there.
nanobot onboard
Use nanobot onboard --wizard if you prefer an interactive setup.
2. Configure (~/.nanobot/config.json)
Skip this step if you already configured provider and model settings in the wizard.
nanobot onboard creates ~/.nanobot/config.json and ~/.nanobot/workspace/. Configure these two parts in the config file. Add or merge the following blocks into the existing file instead of replacing the whole file.
The example below uses a generic OpenAI-compatible custom provider so the compact path does not recommend one hosted service. Provider examples are recipes, not rankings or endorsements. For copyable provider-specific setup, see Provider Cookbook.
Set your API key:
{
"providers": {
"custom": {
"apiKey": "your-api-key",
"apiBase": "https://api.example.com/v1"
}
}
}
Set a model preset and make it active:
{
"modelPresets": {
"primary": {
"label": "Primary",
"provider": "custom",
"model": "model-id-from-your-provider",
"maxTokens": 8192,
"contextWindowTokens": 200000,
"temperature": 0.1
}
},
"agents": {
"defaults": {
"modelPreset": "primary"
}
}
}
Direct agents.defaults.provider and agents.defaults.model still work for existing configs, but named presets are the recommended path because they also power /model switching and fallbackModels.
For another provider, the same config shape still applies:
| Replace | Where |
|---|---|
| Provider config key | providers.<provider> |
| API key | providers.<provider>.apiKey |
| Preset provider name | modelPresets.primary.provider |
| Model ID | modelPresets.primary.model |
| Endpoint URL, only when needed | providers.<provider>.apiBase |
3. Open the WebUI
If Quick Start enabled the WebSocket channel, start the gateway:
nanobot gateway
Leave that terminal open, then open http://127.0.0.1:8765 in your browser. Enter the WebUI password you set in the wizard, then send your first message there.
Prefer not to keep a terminal open? Use nanobot gateway --background, then manage it with nanobot gateway status, logs, restart, and stop.
For manual or terminal-only setup, test one CLI message:
nanobot status
nanobot agent -m "Hello!"
In nanobot status, it is normal for most providers to say not set. The active preset's provider should be configured, and Config plus Workspace should show check marks.
If that works, start an interactive chat:
nanobot agent
Need help with PATH, API keys, provider/model matching, or JSON errors? See the fuller Install and Quick Start and Troubleshooting.
The WebUI ships inside the published wheel โ no extra build step. It is the browser workbench for chat sessions, workspace controls, Apps, Skills, Automations, and settings. For the full user guide, see docs/webui.md.
1. Enable the WebSocket channel in ~/.nanobot/config.json
Merge this block into your existing config:
{
"channels": {
"websocket": {
"enabled": true,
"tokenIssueSecret": "your-webui-password",
"websocketRequiresToken": true
}
}
}
2. Start the gateway
nanobot gateway
Use nanobot gateway --background for a local background process you can manage later with nanobot gateway status, logs, restart, and stop.
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.
The WebUI is served by the WebSocket channel on port 8765 by default. The gateway's 18790 port is for the health endpoint, not the browser UI.
[!TIP] Working on the WebUI itself? Check out
webui/README.mdfor the source-tree, Vite dev server, build, and test 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. ๐ค
See CONTRIBUTING.md for setup, review, and contribution guidelines.
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>