English | 简体中文 | 繁體中文 | Español | Français | Bahasa Indonesia | 日本語 | 한국어 | Русский | Tiếng Việt
Discord · X · WeChat 微信交流群 · Feishu
nanobot
🐈 nanobot is a lightweight, open-source, self-hosted personal AI agent written in Python. Chat with it from your browser, terminal, or favorite chat app to work with files, remember preferences, use tools, and run scheduled tasks—powered by any supported cloud or local AI model.
💡 Why nanobot
- Lightweight & low footprint: Small Python core with fast startup and low memory usage—runs comfortably on a personal laptop or a modest VPS without heavyweight infrastructure.
- Polished WebUI & native TUI out of the box: Includes a clean, responsive browser workbench (multi-pane topics, live tool activity, inline file diffs, context usage, themes, and custom backgrounds) plus a matching terminal UI—no separate frontend build needed.
- Works where you already chat: Connect seamlessly to 15+ chat apps including Telegram, Discord, Slack, Feishu, WeChat, WhatsApp, Email, Mattermost, and Linear.
- Real tools, memory & automations: Reads images, PDFs, and Office files (
.docx,.xlsx,.pptx), edits files, connects to MCP servers and plugins, builds long-term memory with Dream, and runs scheduled tasks, local triggers, and sustained goals. - Model freedom & full control: Use any cloud API (OpenRouter, Anthropic, OpenAI, Gemini, DeepSeek), OAuth subscription (OpenAI Codex, GitHub Copilot, xAI Grok), or local server (Ollama, vLLM, LM Studio)—self-hosted on your own machine.
Start Here
| What you want to do | Where to go |
|---|---|
| Install nanobot with no terminal or config experience | Start Without Technical Background |
| Install quickly and get your first reply | Install → Quick Start |
| Explore the browser workbench | WebUI |
| Connect Telegram, Discord, Slack, Feishu, WeChat, Email, Linear, or others | Chat Apps Guide |
| Configure models, MCP tools, memory, or security | Documentation · Configuration |
| Run nanobot continuously or on a server | Deploy · Deployment Guide |
| Embed nanobot in Python | Python SDK |
| Contribute or extend nanobot | Architecture · Contributing |
📦 Install
Requires Python 3.11 or newer and an account on a supported AI provider or local model server. Packaged installs include both the WebUI and terminal UI—no frontend build tools required.
Recommended: one-command installer (installs into an isolated environment and opens the WebUI automatically on desktop)
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
Preview the installer or inspect the scripts first
Preview what the installer will do without changing anything:
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dry-run
# Windows PowerShell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dry-run
Or read scripts/install.sh and scripts/install.ps1 directly.
Other install methods: uv, pip, or from source
uv
uv tool install nanobot-ai
nanobot webui
pip (inside a virtual environment)
python -m pip install nanobot-ai
nanobot webui
From source (latest main, requires Git)
git clone https://github.com/HKUDS/nanobot.git
cd nanobot
python3 -m venv .venv
source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -e .
nanobot webui
For full install options, troubleshooting nanobot: command not found, or updating an existing install, see Install and Quick Start and Updating nanobot.
🚀 Quick Start
If the installer already opened the WebUI in your browser, continue right there. Otherwise run:
nanobot webui
Your first three steps:
- Open Settings → Models, create a preset, and add your provider API key (or sign in with OAuth). See Configure Your Model.
- Start a new topic and send
Hello!to verify your model connection. - Try a file task: pick a practice folder with Restricted access and ask "Read notes.txt and write a short summary to summary.md." See Your first file task.
Once that works, you can ask nanobot right in chat to help configure your next feature—for example: "I am using the WebUI. Help me connect Telegram and allow only my account." (See Continue with nanobot.)
Terminal-only setup and interactive TUI
Configure a model without a browser:
nanobot onboard --wizard
Send a single test message or launch the interactive terminal UI (shares history and gateway with the WebUI):
nanobot agent -m "Hello!"
nanobot
Useful TUI shortcuts: type / for commands, @ for apps/topics, $ for skills, Ctrl+V / Alt+V to paste images, /diff to view edits, /context to inspect usage, and /detach to keep the gateway running in the background after closing the TUI. See CLI Reference.
Open a remote server's WebUI over SSH
On the remote server:
nanobot webui --no-open
On your computer, forward port 8765:
ssh -N -L 127.0.0.1:8765:127.0.0.1:8765 user@SERVER
Then open the complete login link printed on the server (including everything after #) in your local browser. You can also connect to existing remote servers directly from your local WebUI via Manage connections…—see Connect to an Existing Remote nanobot.
Keep nanobot running in the background
With the official installer, nanobot already stays running in the background after you close the browser or terminal. For other installs, run:
nanobot gateway --background
Manage the background gateway anytime:
nanobot gateway status
nanobot gateway logs
nanobot gateway restart
nanobot gateway stop
For automatic startup across reboots, see Deployment.
If nanobot is helpful to you, giving the repo a star on GitHub is the simplest way to support the project!
☁️ Deploy
One-click on Render
Deploy the gateway and bundled WebUI with persistent storage (requires a paid Render Starter plan for the persistent disk):
Self-host
See the Deployment Guide for Docker Compose, Docker, Linux systemd, and macOS LaunchAgent setup.
🌐 WebUI
The WebUI is included out of the box—just run nanobot webui.
Mobile WebUI · dark theme
Keep related work side by side
Group up to four topics in resizable panes, fork any conversation from an earlier reply, or mention another topic with @ to pull in its context. Pick a project folder and access mode per topic—and use Temporary chats for throwaway questions outside saved history and memory. Explore topics and panes →
Inspect every step and token
Expand agent activity to inspect reasoning, tool calls, inline file diffs, and read-only file previews. Click the context indicator to review token usage, cache reuse, and the file graph across turns.
Explore activity and context →
Connect tools, skills, and chat apps
Use Apps to add MCP servers (with built-in OAuth and keyless presets), Agent Plugins, and CLI Apps, then attach them in chat with @. Manage built-in and marketplace skills in Skills, and connect chat platforms with guided setup in Channels.
Explore Apps → · Discover Skills → · Connect chat apps →
Automate recurring work
Ask nanobot in any topic to schedule reminders or recurring reports, or create local triggers (/trigger) for scripts and CI jobs. Manage everything from Automations with list and calendar views.
Explore Automations → · Full WebUI Guide →
Architecture
A single Python gateway powers the WebUI, terminal UI, and all chat apps—handling sessions, tools, memory, automations, and security policy in one place. Use the Python SDK to embed nanobot in your own Python applications, or read Architecture for source-level details.
Docs
Browse the documentation index (or nanobot.wiki for the latest stable release):
- Get started: Beginner walkthrough · Install and Quick Start
- Models & providers: Providers and Models · Provider Cookbook
- Chat apps & tools: Chat Apps Guide · MCP Presets · Image Generation
- Memory & automations: Memory · Automations · Deployment
- Reference & help: Concepts · Configuration · Troubleshooting · Task Guides
Releases
Latest release: v0.4.1 — improves workspace permissions, sandboxed commands, connection recovery, file-context previews, and navigation. See release notes, Updating nanobot, and the release archive.
Open Source Partners
🤝 Contribute
Everyone is welcome to open an issue with a bug, reproduction, use case, or suggestion. Discuss the problem first; pull requests are currently limited to repository collaborators. See CONTRIBUTING.md for the contribution process and recognition.
Maintainers
Xubin Ren |
Yongru Cheng |
Community Contributors
Thanks for visiting ✨ nanobot!
Metadata
Release files for nanobot-ai 0.4.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nanobot_ai-0.4.2.tar.gz | 12.5 MB | With provenance | Details for nanobot_ai-0.4.2.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| nanobot_ai-0.4.2-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details for nanobot_ai-0.4.2-py3-none-win_amd64.whl |
| nanobot_ai-0.4.2-py3-none-manylinux_2_17_x86_64.whl | Python 3 | none | Linux glibc 2.17+ x86-64 | Details for nanobot_ai-0.4.2-py3-none-manylinux_2_17_x86_64.whl |
| nanobot_ai-0.4.2-py3-none-manylinux_2_17_aarch64.whl | Python 3 | none | Linux glibc 2.17+ ARM64 | Details for nanobot_ai-0.4.2-py3-none-manylinux_2_17_aarch64.whl |
| nanobot_ai-0.4.2-py3-none-macosx_13_0_x86_64.whl | Python 3 | none | macOS 13.0+ x86-64 | Details for nanobot_ai-0.4.2-py3-none-macosx_13_0_x86_64.whl |
| nanobot_ai-0.4.2-py3-none-macosx_13_0_arm64.whl | Python 3 | none | macOS 13.0+ ARM64 | Details for nanobot_ai-0.4.2-py3-none-macosx_13_0_arm64.whl |
Total release size: 277.7 MB
Release files / nanobot_ai-0.4.2.tar.gz
| Download URL | nanobot_ai-0.4.2.tar.gz |
|---|---|
| Size | 12.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a2ca0ab20e3604debfc01c783dc17155cbe58ce85e8064864a1e2f79ffabad33
|
|
BLAKE2b-256 checksum How to use checksums |
5282ffdd97c35fe26bef04e87b30c848b85afbd83ea8a2926dc2133bc6a10997
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / nanobot_ai-0.4.2-py3-none-win_amd64.whl
| Download URL | nanobot_ai-0.4.2-py3-none-win_amd64.whl |
|---|---|
| Size | 59.9 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
bfe9488ec0703ea624cbcba9a916e09bdc63b98831e19a912c94a2be652dd3f0
|
|
BLAKE2b-256 checksum How to use checksums |
1f689e5d34645d3f95dcbfac4e45c769b5a5dd2afc289c32a6ec08ac335e9db1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / nanobot_ai-0.4.2-py3-none-manylinux_2_17_x86_64.whl
| Download URL | nanobot_ai-0.4.2-py3-none-manylinux_2_17_x86_64.whl |
|---|---|
| Size | 60.8 MB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
5c43d4d884840d3fe2ead1ae4ff9364962d1be50827b40cca1bcd09ce4fe96c8
|
|
BLAKE2b-256 checksum How to use checksums |
3e82f670b4ab734a8b7821c7b18dc750c4278fe31ce421f814c5fe80e0b493c2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / nanobot_ai-0.4.2-py3-none-manylinux_2_17_aarch64.whl
| Download URL | nanobot_ai-0.4.2-py3-none-manylinux_2_17_aarch64.whl |
|---|---|
| Size | 60.3 MB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
4589c0b7a5aa4e4341898420235f52a4616f87019ce10580b3b10cd5e74722f9
|
|
BLAKE2b-256 checksum How to use checksums |
f461e5189af5e78adfe96a51979727a4f6b7a5e769669868fb591939352e5c17
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / nanobot_ai-0.4.2-py3-none-macosx_13_0_x86_64.whl
| Download URL | nanobot_ai-0.4.2-py3-none-macosx_13_0_x86_64.whl |
|---|---|
| Size | 43.4 MB |
| Tags | Python 3 macOS 13.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
2e96e13662c835481387a2521824d53f12c94aded9d5460ea8a0cef7232a34f8
|
|
BLAKE2b-256 checksum How to use checksums |
13902592e58c0e07eee7c2b9367723124a28f42fd380cd984dc40218b3e1678e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / nanobot_ai-0.4.2-py3-none-macosx_13_0_arm64.whl
| Download URL | nanobot_ai-0.4.2-py3-none-macosx_13_0_arm64.whl |
|---|---|
| Size | 40.8 MB |
| Tags | Python 3 macOS 13.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
e41ce2bb607485ee37c57716576929f15cf04d455d34b9480be8a30cd347bff9
|
|
BLAKE2b-256 checksum How to use checksums |
e096d17a07453f49ab446f391bfb06b3d12901f4220ba7ec2375df776febc4d5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logSecurity for nanobot-ai 0.4.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 6 files in this release have been uploaded with provenance metadata.
Attestation for nanobot_ai-0.4.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.