MCP serverCautionAgent workflow & memoryAdvanced

nanobot

This self-hosted Python framework enables building personal AI agents with a WebUI, tools, memory, MCP integrations, and multi-agent workflows.

Ultra-lightweight, open-source, self-hosted personal AI agent framework in Python with WebUI, tools, memory, MCP, multi-agent workflows, automation, and chat apps

49k stars8.6kLicense: MITUpdated 3 days ago0 opens

Preview

▍

What you can do with it

Create a custom AI assistant with persistent memory and various tools.
Integrate your agent with chat platforms like Discord or Telegram.
Develop complex multi-agent workflows for automation and data processing.

Try asking your agent

“Configure nanobot to connect to my Telegram account and respond to messages.”
“Create an agent workflow that monitors a GitHub repo for new issues and summarizes them daily.”
“Set up a web scraping tool for nanobot to extract data from e-commerce sites.”

Safety check

Caution

Usable, but read the notes first.

●Installer downloads a remote script and pipes it to the shell.README.md

Automated scan of the repo files. Always review code you run.

From the README

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 t

View source on GitHub