birdxs/nanobot repository overview

🐈 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.

⁠Start Here

⁠Open Source Partners

⁠

⁠📢 News

• 2026-06-22 🚀 Released v0.2.2 — The Durability Release makes nanobot sturdier for daily agent work: segmented WebUI transcripts, first-class Python SDK runtime controls, automation management, richer search/STT providers, and stronger gateway/session/provider reliability. Please see release notes⁠ for details.
• 2026-06-21 🧰 Python SDK runtime controls, optional Keenable key, cleaner run hooks.
• 2026-06-20 💬 Telegram rich messages, safer SDK concurrency, smoother Quick Start.
• 2026-06-19 🔎 Firecrawl app, OpenAI image edits, safer session deletion.
• 2026-06-18 💬 Feishu recovery, Keenable search, Mistral polish, workspace-aware git.
• 2026-06-17 🧠 Default idle auto-compact, clearer /dream, macOS installer fixes.
• 2026-06-16 🎯 Fresher goal context, Kimi K2.7 thinking, cleaner API retries.
• 2026-06-15 📱 Mobile WebUI polish, optional file tools, real API usage.
• 2026-06-14 🖼️ Themed cover, partner links, stronger Codex image streaming.
• 2026-06-13 🗓️ Session-bound automations, sturdier WhatsApp, faster WebUI startup.

⁠💡 Why nanobot

• Persistent workflows: goals, memory, tools, and chat context survive long-running work.
• Chat-native reach: WebUI, API, Telegram, Feishu, Slack, Discord, Teams, and email.
• 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

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

⁠🚀 Quick Start

1. Initialize

Skip this step if the one-command setup already started the wizard and Quick Start finished there.

nanobot onboard