HKUDS/nanobot
HKUDS/nanobot — 49.1k★ on GitHub (Python). Ultra-lightweight, open-source, self-hosted personal AI agent framework in Python with WebUI, tools, memory, MCP, multi-agent workflows, automation, and chat apps
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
Snapshot
Top contributors
Show top contributors
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. Use it in a browser, terminal, or chat app to work with files, remember preferences, and schedule tasks. Connect a supported model provider or local model server to supply the AI.
Start Here
| You want to... | Go to |
|---|---|
| Install nanobot with no terminal/config background | Start Without Technical Background |
| Install quickly and get your first reply | Install and Quick Start |
| Open the bundled browser UI | WebUI |
| Connect Telegram, Discord, WeChat, Slack, Email, Mattermost, Linear, or another channel | Chat app guide |
| Configure providers, fallback models, Langfuse, MCP, web tools, or security | Docs and Configuration |
| Develop the browser UI | Install current source, then WebUI development and Contributing |
| Integrate from Python or HTTP | Python SDK or Agent API |
| Understand or extend the internals | Architecture, Contributing, and Provider extensions |
| Deploy to the cloud or keep nanobot running as a service | Deployment |
What can nanobot do?
nanobot can:
- run in a browser WebUI or terminal
- connect to Telegram, Discord, Slack, WeChat, Email, Mattermost, Linear, and other channels
- read PDF, Word (
.docx), Excel (.xlsx), and PowerPoint (.pptx) files with built-in file tools, for tasks such as summarizing reports - use shell, web search/fetch, MCP integrations, cron, image generation, and multi-agent delegation
- 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: keep saved conversations, long-term memory, and task results for later work.
- Chat-native reach: WebUI, API, Telegram, Feishu, Slack, Discord, Teams, email, Mattermost, and Linear.
- 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
You need Python 3.11 or newer and access to a supported model provider or local model server. Model fees or local hardware requirements depend on the service you choose; nanobot does not supply a model account.
Choose the stable release for everyday use or current source for development and the latest features. This README describes current source; published documentation covers the released version.
New to terminals or model credentials? Follow Start Without Technical Background. Updating an existing instance? Back up its config directory and workspace, stop every old nanobot process using that workspace, then update and restart through the original launcher or service. See session storage and version changes.
Stable release: automatic setup (recommended)
The installer chooses an isolated Python environment and opens setup for you. The two commands below are the same installation method for different operating systems; run only the one for your system.
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
Installer details, preview, and script review
The installer installs or upgrades nanobot-ai using an active virtual environment, uv, pipx, or a managed venv under ~/.nanobot/venv. Fresh local desktops open the WebUI; SSH, headless, existing-config, and older-release paths use the terminal setup wizard. Keep the printed command: it identifies the environment that owns the installation.
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.
Already use uv or pip? Install the stable package yourself
Use this instead of the recommended installer when you already manage your own Python environment. These commands install the same stable nanobot-ai package; they do not launch setup.
uv: isolated CLI installation
uv tool install nanobot-ai
pip: activate your virtual environment first
python -m pip install nanobot-ai
Then run nanobot webui for browser setup, or nanobot onboard --wizard for terminal-only setup. For the Python SDK, install nanobot-ai in your application's virtual environment so the application can import it; a separate uv tool environment does not make the SDK importable there.
If pip reports externally-managed-environment, use the recommended installer, uv tool install nanobot-ai, pipx install nanobot-ai, or an activated virtual environment. Upgrade with the same method; for uv use uv tool upgrade nanobot-ai, and for pip use python -m pip install -U nanobot-ai.
Current source: development checkout
Install current source with Git and Bun
Clone the repository and install it in editable mode. A source install requires Git and Bun; Bun runs the matching TUI directly from the checkout 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. After stopping the old instance, git pull --ff-only updates the Python, TUI, and WebUI source together; rerun python -m pip install -e . when Python dependencies change, then restart the instance. Contributors should also read CONTRIBUTING.md.
Supported platforms, bundled UIs, and release tracks
Published packages include the WebUI, and supported platform wheels also include the native TUI. A source-distribution install can fetch a checksummed, version-matched TUI archive—with its licenses, notices, corresponding application source, source offer, and relinking instructions—on first use.
Platform wheels include both the WebUI and the native terminal UI: macOS 13+ (Apple Silicon and Intel), glibc 2.17+ Linux (ARM64 and x64), and Windows x64. The x64 runtime requires SSE4.2. Pip selects the matching wheel; opening the TUI does not need a separate GitHub download or Bun installation. A source-distribution install on a supported target can use the matching checksummed GitHub release archive. On other platforms, use nanobot --classic or the WebUI.
[!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 | same installation method | 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 |
Verify the installation or locate the nanobot command
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.
After installation, continue with Quick Start. Use the exact command printed by the installer if nanobot is not on PATH.
🚀 Quick Start
Open nanobot in your browser
If the installer already opened the WebUI, continue there. Otherwise run:
nanobot webui
Keep the launcher terminal open while using the browser. It starts or joins the shared local gateway and binds the first-run WebUI to localhost. If the browser does not open, copy the complete login link printed in the terminal, including everything after #; keep this credential private. For SSH or a headless host, use the remote-browser or terminal-only instructions below.
Your first three steps
- Open Settings → Models and save a provider/model preset with your credential or supported sign-in. See model setup if you need the full steps.
- Start a new topic and send
Hello!to verify the model connection. - To try file work, put a copy of
notes.txtin a practice folder, select that folder and Restricted access, and ask: "Read notes.txt and write a short summary to summary.md." Opensummary.mdin that folder to check the result. See Your first file task.
A normal reply verifies the provider/model and browser connection. The file task separately checks the selected project and its file permissions. Attaching a file sends it to the conversation; it does not change the selected project folder.
Then describe your next goal in the same chat, for example: "I am already using the WebUI. Help me connect Telegram and allow only my account." An enabled nanobot-document skill can consult the documentation bundled with your installation; see Continue with nanobot for examples, explicit invocation, and availability.
Open the WebUI on a remote server through SSH
After installing nanobot on the server, start its WebUI without opening a server-side browser:
nanobot webui --no-open
Keep that server terminal running. In a second terminal on your own computer, forward the default WebUI port through SSH:
ssh -N -L 127.0.0.1:8765:127.0.0.1:8765 user@SERVER
Replace user@SERVER with your SSH login and leave the tunnel open. In your local browser, open the complete login link printed by the server launcher, preserving its # fragment. It uses http://127.0.0.1:8765, which now reaches the server through the tunnel. Complete Settings → Models and send Hello!. If local port 8765 is occupied, use another local port in the tunnel and change only the port in the browser link. Keep the server listener on localhost. For Docker, public endpoints, or service management, see Deployment.
Terminal-only setup, one-shot checks, and the TUI
If a model is not configured yet, use the terminal wizard:
nanobot onboard --wizard
Check one reply without opening the browser:
nanobot -m "Hello!"
For interactive work, open the terminal client:
nanobot
The native TUI uses the launch directory as its project workspace and shares saved conversations and the local gateway with the WebUI. The explicit nanobot agent form remains available for compatibility.
- Type
/to discover commands,/sessionsto switch conversations, or@to mention an app, MCP server, or saved session. - Paste clipboard images with
Ctrl+VorAlt+V, and use$to complete skill references. - Use
/diffto inspect file changes,/contextto inspect session context, or/branchto continue from a completed reply in a new session. - Press
Enterto send. While nanobot is working,Entersends now andTabsends after the current response. PressShift+Enterto add a newline (Ctrl+Jworks in terminals that cannot distinguish modified Enter keys). - Use
/detachto promote the gateway to background mode and close the TUI while work continues.
Each launch starts a new session by default. Use --session to resume one and --workspace to choose another project workspace. See the CLI reference for session branching, diffs, history, shortcuts, gateway lifecycle, and compatibility options.
Save and check a preference
State a specific preference in your chat, for example: "For release notes, use concise bullet points." To consolidate it now, send /compact and then /dream, waiting for each to finish, and review /dream-log. Check the actual changes to USER.md or memory/MEMORY.md in the configured agent workspace, then test reuse in a new topic in the same instance. Dream may decide that no durable change is needed; a conversational acknowledgement alone does not prove the preference was saved. See Save and Check a Preference for file access, correction, and restoration steps.
Start and stop a sustained goal
Use a regular topic for a bounded objective with a clear completion condition, for example:
/goal Review this project's tests and list the smallest missing test case.
The goal lets nanobot continue work across model turns while the gateway runs; a scheduled automation instead starts a turn at specified times. Use /stop to interrupt the current work, and ask nanobot to cancel the goal if you want to abandon it. Keep the gateway running for unattended work using the background or service options below.
After a gateway restart, reopen the original topic and review saved results before explicitly continuing any interrupted work. Recovery does not blindly replay uncertain tool actions. See the long-running agent guide for starting conditions and related automation options.
Keep the gateway running after closing interactive clients
After model setup, keep channels and automations running when interactive launchers close:
nanobot gateway --background
This starts or promotes the shared gateway to a detached process. From the TUI, /detach does the same before closing that client. Background mode does not configure startup after a machine reboot or restart after a crash; use an OS-managed service for that. Interrupted subagent tasks are not automatically relaunched after a restart, and missed scheduled times are not replayed; see subagent recovery and automation delivery.
Manage the background gateway with:
nanobot gateway status
nanobot gateway logs
nanobot gateway restart
nanobot gateway stop
To reopen the browser, run nanobot webui against the same instance and use its complete printed login link.
Run a configured gateway directly
Use this once a model is configured and you want to run the gateway directly in the current terminal:
nanobot gateway
It skips guided WebUI setup and browser opening. The WebUI remains available when its channel is configured. Use nanobot gateway --background for a detached process, or follow Deployment for startup and supervision by the operating system.
Read task guides or look up configuration details
- Model/provider recipes: Provider Cookbook and Providers and Models.
- Local models: Ollama, vLLM or another OpenAI-compatible server.
- Chat platforms: Chat app guide, then the full channel reference.
- Exact settings for web search, MCP, voice, image generation, and security: Configuration.
- Manual JSON and other setup paths: Install and Quick Start.
- Failures after setup: Troubleshooting.
If nanobot worked for you, a star on GitHub is the simplest way to support the project.
☁️ Deploy
Render — one click
Deploy nanobot's gateway and bundled WebUI from the repository's ready-to-use Blueprint:
Render will ask for ANTHROPIC_API_KEY and a private NANOBOT_WEB_TOKEN, then provision persistent storage for sessions, memory, and WebUI history. Persistent disks require a paid Render service.
Self-host
Prefer your own infrastructure? Follow the deployment guide for Docker, Docker Compose, Linux services, and macOS LaunchAgent setup.
🌐 WebUI
The WebUI ships inside the published wheel with no separate frontend build. It is the browser workbench for persistent topics, temporary chats, visible agent activity, workspace controls, Apps, Skills, Automations, and settings. Start it with nanobot webui. WebUI access grants administration of the same agent instance; share it only with trusted operators. See Sharing access.
The screenshots below use example conversations, illustrative token counts, and paused schedules.
Use it to:
- keep separate topics for different tasks and projects;
- use temporary chats when a conversation should not be saved to history or memory;
- inspect reasoning, tool calls, file edits, diffs, command output, and generated artifacts;
- switch models and workspaces without leaving the conversation;
- configure models in Settings, connect chat platforms in Channels, and manage Apps, Skills, and Automations.
Keep related work side by side
Group up to four conversations and arrange them in columns, rows, a grid, or a main pane with supporting panes. Each topic keeps its own history. Select another topic from the @ menu, or drag it into the composer, to let the agent read its context and coordinate work across sessions.
Choose a project, access mode, and model for each task. Topics separate conversation history; project folders select where file work happens. Neither creates separate long-term memory: one instance shares its agent profile, memory, and skills across projects. Use separate instances when client data or preferences must stay isolated. Explore topics and panes →
Inspect the work and its context
Expand agent activity to see reasoning, tool calls, and file changes. Switch Settings → Appearance → File edit display to Diff for inline patches. The composer's context indicator shows the current context size, input tokens by round, and cache reuse when the provider reports it.
Context compaction also appears in the conversation timeline. Explore activity and context →
Bring your tools into the conversation
Use Apps to connect MCP servers, enable Agent Plugins, and manage local CLI App adapters. Add a preset or a custom server, then attach an available tool with @. Skills provide reusable instructions. Settings holds model, voice, image, and web setup; Channels handles chat-platform connections.
Explore Apps → · Discover Skills → · Connect chat apps →
Before connecting a personal bot to shared channels, check the platform's DM pairing/allowlist and group-access policies separately. Approving a private sender does not restrict group access on every platform; see the channel reference.
Let recurring work run on a schedule
Ask for an automation from the topic that should receive its results. Use Tasks to review and manage schedules, or Calendar to scan completed and upcoming runs by date. Local triggers let a script start a saved task on demand.
Keep the gateway running and the host awake for scheduled delivery. Missed scheduled times are not replayed after a gateway restart. See delivery and recovery rules. Explore Automations →
For a conversation that should stay out of saved topic history and long-term memory, use Temporary chat from the header. Temporary chats end when the connection closes and use the default workspace in Restricted mode. Requests still go to the configured model provider, and files created by tools remain after the chat closes.
See the WebUI guide for LAN access, background operation, workspace controls, and the full feature tour. Working on the frontend itself? Use webui/README.md.
Architecture
The Python gateway owns agent execution, sessions, tools, memory, and security policy for the WebUI, TUI, and chat apps. The clients share that runtime; the core agent loop builds context, calls the model, executes requested tools, and returns the result. Memory, skills, channels, and MCP integrations extend that loop.
The Python SDK embeds the agent runtime in your application process. The OpenAI-compatible API starts a separate HTTP service for /v1/chat/completions: each request contains one user message, history is managed by the server, and the model comes from configuration. Responses return to the HTTP client; that service does not deliver tool messages to chat apps.
See Architecture for source ownership and extension points.
Docs
Browse the repo docs for current source documentation, or visit nanobot.wiki for the stable release. The task guide index groups walkthroughs by outcome.
- Get started: Beginner walkthrough or Install and Quick Start.
- Choose and configure a model: Providers and Models and Provider Cookbook.
- Connect a chat app: Chat App AI Agent and channel reference.
- Schedule or deploy work: Automations and Deployment.
- Integrate from code: Python SDK and OpenAI-Compatible API.
- Look up runtime concepts or exact settings: Concepts and Configuration.
- Diagnose a failure: Troubleshooting.
- Extend the core: Architecture and contribution workflow.
Releases
Latest release: v0.3.5
v0.3.5 brings the workbench to the terminal and makes conversations easier to continue across the browser, terminal, and chat apps.
- Use the native terminal workbench with the same gateway and saved conversations as the WebUI.
- Arrange up to four browser conversations side by side, mention saved sessions, or open a temporary chat.
- Inspect per-round context usage and compaction progress, with more durable history and recovery.
- Discover Skills, connect Apps, and manage scheduled work through expanded WebUI flows.
Read the v0.3.5 release notes and upgrade notes
Recent Updates
- 2026-09-19 🔎 Searchable provider setup, consistent provider identities, and smoother Linear onboarding.
- 2026-09-18 ♻️ Clearer recovery for interrupted work and Discord reply-context support.
- 2026-09-16 📦 Platform wheels bundle the version-matched native terminal UI.
- 2026-09-15 🚀 Released v0.3.5 with a shared terminal workbench, multi-pane WebUI, and visible context continuity.
- 2026-09-07 🔌 WeCom media uploads use the SDK API, and CI skips unrelated jobs.
For earlier updates, see the release archive or GitHub releases.
Open Source Partners
🤝 Contribute
Use nanobot for a real task, report what broke, and then pick a focused improvement.
- Read CONTRIBUTING.md for the development workflow.
- Browse open issues for problems to investigate.
- Open a pull request for a focused fix or integration.
Maintainers
 Xubin Ren  |  Yongru Chen  |
Community Contributors
Thanks for visiting ✨ nanobot!
Related repositories
Paperclip is a self-hosted Node.js server and React dashboard that orchestrates a team of AI agents — human and bot — under one org chart, complete with goals, budgets, approval gates, and an audit trail, so a company built out of agents runs like a business instead of a pile of disconnected scripts.
Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.
ToolJet is an open-source low-code platform for building internal tools, dashboards, and workflows. You drag components onto a canvas, wire them to databases and APIs, and self-host the result with Docker or Kubernetes. It's the community foundation under the paid ToolJet AI product.
CloakBrowser is a stealth Chromium binary with 73 source-level C++ patches that modify browser fingerprints at the compiler level — not through JavaScript injection or flag tweaking. The README claims it passes 30+ detection services including Cloudflare Turnstile and achieves a 0.9 reCAPTCHA v3 score, compared to 0.1 with stock Playwright. It ships as a drop-in Playwright and Puppeteer replacement for Python and JavaScript, requiring only a 3-line import swap to adopt. A `humanize=True` flag adds human-like mouse curves, keyboard timing, and scroll patterns to pass behavioral detection. Free tier gives one concurrent session with the latest build; Pro scales to thousands of sessions. MIT licensed.
Quick answers
How active is development on HKUDS/nanobot?
The most recent commit recorded on HKUDS/nanobot was 8 days ago, based on the GitHub push timestamp. The repository has 8.6k forks — one of the better signals of community interest.
How many stars does HKUDS/nanobot have?
HKUDS/nanobot has 49.1k GitHub stars — refresh the page for the live number, or check github.com/HKUDS/nanobot. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
What language is HKUDS/nanobot written in?
HKUDS/nanobot is written primarily in Python. GitHub's language field is based on the largest share of bytes in the default branch.
What license does HKUDS/nanobot use?
HKUDS/nanobot is released under the MIT license. Always verify the LICENSE file directly on GitHub for the authoritative terms — license strings can be edited out of sync with a project's actual stance.
What topics is HKUDS/nanobot associated with?
GitHub's repository topics for HKUDS/nanobot: "agent-framework", "ai-agent", "ai-agents", "chatbot", "chatops", "discord-bot", "llm-agents", "llms", "local-llm", "mcp", "model-context-protocol", "multi-agent", "openai-compatible", "openclaw", "personal-ai-assistant", "python", "self-hosted", "telegram-bot-ai-assistant", "webui", "workflow-automation". TopGit's editorial category is Automation.
Where can I see HKUDS/nanobot in action?
The project maintains a homepage at https://nanobot.wiki. The README tab on this page also usually contains screenshots and a quickstart.
Where do I read more about HKUDS/nanobot?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/HKUDS/nanobot is the definitive source.
Read full README in the tab above.
Curious whether nanobot is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about nanobot.