nanobot: An Ultra-Lightweight, Self-Hosted Personal AI Agent Framework With One Gateway for Browser, Terminal and Chat Apps

The first sentence of HKUDS/nanobot's README says it plainly: it is an ultra-lightweight, open-source, self-hosted personal AI agent framework written in Python. You can use it in a browser, terminal or chat app to work with files, remember preferences and schedule tasks. You connect a supported model provider or local model server yourself, because nanobot does not supply a model. As of October 13, 2026 the repository has about 48,978 stars and 8,626 forks, an MIT license, Python code, a creation date of February 1, 2026, and a last push on October 12. The README gives five reasons to choose it: persistent workflows, chat-native reach, model freedom, a small readable core, and owning your stack.

The capability list is broad. It connects to Telegram, Discord, Slack, WeChat, email, Mattermost, Linear and other channels; reads PDF, Word (.docx), Excel (.xlsx) and PowerPoint (.pptx) with built-in file tools, for tasks such as summarizing reports; uses shell, web search and fetch, MCP integrations, cron, image generation and multi-agent delegation; keeps session history and long-term memory through a mechanism called Dream; runs long-horizon goals and scheduled automations; exposes a Python SDK and an OpenAI-compatible API; and can be deployed as a long-running local or server-side gateway. The latest release is v0.3.5, which brings the workbench to the terminal and makes conversations easier to continue across browser, terminal and chat apps, with up to four conversations arranged side by side in the WebUI and per-round context usage and compaction progress.

The install path is clear. You need Python 3.11 or newer. The recommended route is the installer script: curl install.sh on Linux and macOS, install.ps1 in PowerShell on Windows. It installs or upgrades nanobot-ai in an active virtual environment, uv, pipx or a managed venv under ~/.nanobot/venv, opens the WebUI on a local desktop and the terminal wizard on SSH or headless hosts, and supports --dry-run to preview the plan. If you prefer your own toolchain, use uv tool install nanobot-ai or pip. Then run nanobot webui, pick a model in Settings, save credentials and send "Hello!" to verify the connection. Choose a practice folder with Restricted access, ask it to read notes.txt and write summary.md, and check that file permissions behave as expected. Platform wheels include both the WebUI and the native terminal UI on macOS 13+, glibc 2.17+ Linux (ARM64 and x64) and Windows x64, with x64 needing SSE4.2. For the newest features, install from source, which requires Git and Bun.

The architectural trade-off is what it calls a small core. The Python gateway owns agent execution, sessions, tools, memory and security policy, and the WebUI, TUI and chat apps 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 runtime in your own application process, while the OpenAI-compatible API starts a separate HTTP service for /v1/chat/completions, where each request contains one user message, history is managed by the server and the model comes from configuration. The WebUI keeps separate topics for different tasks and offers temporary chats that are not saved to history or memory. But the README warns that topics separate conversation history and project folders select where file work happens; neither creates separate long-term memory. One instance shares its agent profile, memory and skills across projects, so use separate instances when client data or preferences must stay isolated.

For anyone self-hosting, the security notes come first. The README says WebUI access grants administration of the same agent instance, so share it only with trusted operators. Before connecting chat apps, check each platform's DM pairing, allowlist and group-access policies separately, because approving a private sender does not restrict group access on every platform. Scheduled work needs the gateway running and the host awake, and missed times are not replayed after a restart. Also, temporary chats still send requests to the configured model provider, and files created by tools remain after the chat closes, so "temporary" does not mean "not sent out".

Our reading is that nanobot's value is making a personal agent a small readable system rather than a product tied to one cloud: you can see the core loop, decide which model to connect, and decide where the data lives. The cautions are just as clear. First, stars and update frequency show an active community, not stability; the README itself separates the stable release from current source, and daily use should pick stable. Second, the agent holds file, shell and chat-channel permissions, so mistakes in settings are as large as its capabilities; start with Restricted access and one practice folder. Third, model fees or local hardware requirements depend on your choice, and nanobot will not solve them for you. Deploy first on an isolated machine or container, connect only your own chat account with an allowlist, and judge after a week of real tasks whether it deserves a long-running spot.