HKUDS/nanobot

🐈 nanobot: The Ultra-Lightweight OpenClaw

Summary

nanobot is a self-hosted, MIT-licensed Python framework for running a personal AI agent locally, with a bundled WebUI, terminal client, and connectors for chat apps. It wraps a model loop with tools (files, shell, web search, MCP, image generation), long-term memory, scheduled automations, and an OpenAI-compatible HTTP API.

What it is useful for

nanobot is a fit when you want a single Python process that acts as your agent runtime, browser workbench, and integration hub. Concrete uses include:

• Running an agent against OpenAI-compatible providers or local LLMs (Ollama, vLLM) with fallback models.
• Driving recurring work through cron-style automations that post results back to a topic or the WebUI.
• Connecting existing chat platforms — Telegram, Discord, Slack, WeChat, Email, Mattermost, Linear — so one agent serves multiple surfaces.
• Extending the agent with MCP servers and Skills, then inspecting reasoning, tool calls, and file diffs in the browser.
• Embedding the agent in other systems via the documented Python SDK and OpenAI-compatible API.

It needs Python 3.11+ and stores sessions, memory, and workspaces under a local config directory you can inspect and back up.

How engineers can use it

Three install tracks are documented. The stable one-liner on macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh

A Windows PowerShell variant and a --dry-run flag are also documented. With uv: uv tool install nanobot-ai. From source: clone the repo, create a venv, then python -m pip install -e . (Bun is required to build the bundled terminal UI on this track). Verify with nanobot --version.

First run is the WebUI — nanobot webui opens http://127.0.0.1:8765 and walks you through picking a provider and model under Settings → Models. A gateway-first workflow uses nanobot gateway (foreground) or nanobot gateway --background (persists after the terminal exits), with status, logs, restart, and stop subcommands. For terminal-only work, run nanobot; for one prompt and exit, use nanobot -m "Hello!". A Render Blueprint is documented for cloud deployment, requiring ANTHROPIC_API_KEY, a NANOBOT_WEB_TOKEN, and a paid Render plan for persistent disks.

Documented limitation: the native terminal UI ships in platform wheels for macOS 13+, glibc 2.17+ Linux, and Windows x64 (x64 needs SSE4.2). Other platforms fall back to nanobot --classic or the WebUI. Provider/model setup beyond the basic case is delegated to the in-repo provider cookbook and configuration docs.