Skip to main content
nanobot README cover

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:

  1. Open Settings → Models, create a preset, and add your provider API key (or sign in with OAuth). See Configure Your Model.
  2. Start a new topic and send Hello! to verify your model connection.
  3. 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):

Deploy to Render

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.

Three conversations in one WebUI workbench

Mobile WebUI · dark theme

Mobile WebUI in dark theme

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.

Expanded file-edit diff and context usage chart

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.

The Apps MCP catalog with searchable integration presets

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.

The Automations calendar view

Explore Automations → · Full WebUI Guide →

Architecture

nanobot 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):

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

Kimi Open Source Friends MiniMax

🤝 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
Xubin Ren

Xubin Ren on X
Yongru Cheng
Yongru Cheng

Yongru Cheng on X

Community Contributors

Athemis axelray-dev yorkhellen yu-xin-c 04cb santhreal xcosmosbox KDB-Wind kunalk16 chaohuang-ai zayfod nikolasdehor JiajunBernoulli flobo3 hamb1y SergioSV96 morandot michaelxer coldxiangyu163 boogieLing aiguozhi123456 pinhua33 pixan-ai hussein1362 alekwo haosenwang1018 IlyaGusev T3chC0wb0y VITOHJL KailBug macroadster Hinotoi-agent kingassune goodtiding5 kiplangatkorir elkaix KimGLee m11y LingaoM DaryeDev CJWTRUST xzq-xu pikaxinge arcdrake22 JackLuguibin HaisamAbbas anunay999 flaviovs dajiaohuang C-Li Ho1yShif pjhoberman nghiahsgs Bahtya ZhouJ-sh bingqilinweimaotai Shizoqua tangtaizong666 XJPeng12 yanghan-cyber Yuxin-Lou LeoFYH claude chris-alexander benlenarts wzrayyy outlook84 Mrart ramonpaolo huhu-tiger tangjiabin yeyitech Flinn-X Qinnnnnn HengWeiBin waelantar tanishra olgagaga masterlyj xgzlucario dzydzydzy7 concertypin WangCheng0116 yarikoptic lukemilby gongpx20069 tobrien Shiniese zpljd258 FanouZeng-TT shawnWXN sbyinin nne998 lahuman hlgone franciscomaestre fat-operator shixi-li who96 cyzlmh zhuzhh cms19859230182-lang amplifierplus LZDQ wb213 shaun0927 LHMQ878 Michael-lhh Mizarka rick2047 kuchazi-yy Protocol-zero-0 subalkum vystartasv ZJUCQR ZegWe ZhangYuanhan-AI chtangwin dxtime ethanclaw Naster17 L4XB Oxygen56 WufeiHalf stutiredboy stupidloud asif786ka robbyczgw-cla cypggs web-flow eliumusk mikaku9944 mamamiyear jr551 invictus-z imfondof hyoukadev hata33 fengxiaohu vivganes themavik flyzstu pikaqqqqqq wyjBot pblocz niradler longle325 primit1v0 honjiaxuan DeeJ4yNg danielphang zhouzhuojie zerone0x yrk111222 Xerxes-cn suger-m mengyhang Liwx1014 19emtuck tsubasakong wseng 3927o FloRainRJY agbocsardi JilunSun7274 dvejmz ddadaal jiehaoZ Lbin91 Alex-yang00 xek Harvey-Mackie chenyahui angleyanalbedo adabarbulescu yoheinishikubo WormW WhalerO thomya Tejas1Koli Seeratul SJK-py RongLei-intel QQQ300kuai MiguelPF mterhar Pringlas pjbakker luojiaaoo NearlCrews Krislu1221 beemines Wsp030914 pengpengyi92 LuckTerence yankeguo nolanchic yanalialiuk yongPhone ZXGERIC erikmackinnon rickererer ferkans-amir for13to1 futurist Maaannnn rubychilds init-new-world Idealist17 gola greyishsong h4nz4 hoaresky hcanyz himax12 Zeknes ZhihaoZhang97 linziyanleo akinolur alairjt noki1928 barreler126 bllackhu brendanlevy-clarahealth cdkey85 ducheng121 SamZhu19921116 justforyoudear choiking cocolato luomaohao codedragoncom d1ago daliu858 danielyangfei dingyanyi2019 djmaze dulltackle samyzhh shen0122 shenchengtsi sidkang skiyo sontianye spartan077 tercerapersona tlguszz1010 vandazia vincentchen0x2-dev tianrking wcmolin dynames0098 knightconnorp wymcmh weijun-xia yaotutu yeounhyeok Endeavour-Yuan ziuus dsxyy azhengzz jhkim43 kimkitsuragi26 kinchahoy A11Might kronk307 lailoo lang07123 tetratorus spinvettel li-yazhou ALIZE126 Rheasilvia mru4913 mt-huerta mytechdream nikube npodbielski oriengy popcell qixinbo qulllee rav-melisono razzh7 rise2689 hlibr gthieleb Rafa-Ross korruz hyudryu breitburg IlyaSemenov Tevkanbot JakeRowe19 JamesWrigley La-Volpe JavisPeng Jefsky letzdoo-js 95256155o joel611 NiceLargeHuo kamalakarrao KEEPSLAMDUNK krisLu kyya rreben ATECHPCS adrianhoehne Aisht669 AlbertWang688 AlexanderMerkel khmylov karimluna Bayern4ever-dot abhinavaditya811 bjoshuanoah hanouticelina quanmou ClaytonWWilson kaseru danielemden dmarkey desmondsow intelliot eugenechae ehs208 Felix8568 GabrielWithTina georgeatparallel SHLE1 lzmjlrt saimonventura SIDD-KIDD sihyeonn Seym0n fyhertz sohamb117 Solaris-star Syoc tedyyan xuayan-nokia TheAutomatic TomLisankie tamvicky MVS-source wingkwong wenjielei1990 Wenzhang-Chen wesleyzhangwq XiaoHuo888-hue Lyt060814 limdingwen luc-nguyen-cake maciejwojcik86 mvanhorn twiddles maxmilian mrbob-git MuataSr Neutralmilkzzz nblondiau omdv rbankole orrinwitt pjperez pve PeterDaveHello Molunerfinn power88 srajasimman groudas RohitDayanand katafractari rudy-of-the-corner fszcd kkkhoo chrischen-coder cleverLucky n1uz1 shakewingo Kuang-xianxin 0717lee loseintwilight AlfredChaos BenWituka gary23w tilladam DannyYTL yaoruiquan GUTYL ZedingZhang

Thanks for visiting ✨ nanobot!

Views

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)

Source distribution for nanobot-ai 0.4.2
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)

Table of built distributions (wheels) for nanobot-ai 0.4.2
File Actions
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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

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

Select from 6 files

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 log

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

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page