🐈 **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 | You want to... | Go to | |---|---| | Install nanobot with no terminal/config background | [Start Without Technical Background](./docs/start-without-technical-background.md) | | Install quickly and get one CLI reply | [Install](#-install) and [Quick Start](#-quick-start) | | Open the bundled browser UI | [WebUI](#-webui) | | Connect Telegram, Discord, WeChat, Slack, Email, Mattermost, or another chat app | [Chat Apps](./docs/chat-apps.md) | | Configure providers, fallback models, Langfuse, MCP, web tools, or security | [Docs](./docs/README.md) and [Configuration](./docs/configuration.md) | | Understand or extend the internals | [Architecture](./docs/architecture.md) and [Development](./docs/development.md) | | Deploy to the cloud in one click | [Deploy to Render](#deploy-to-render) | ## Deploy to Render Deploy nanobot's gateway and bundled WebUI as a single web service with persistent memory. Render reads [`render.yaml`](./render.yaml) and prompts for two secrets on deploy: `ANTHROPIC_API_KEY` and `NANOBOT_WEB_TOKEN` (the password that gates the public WebUI — generate a strong random value, e.g. `openssl rand -hex 32`). > **Note:** The blueprint attaches a persistent disk so sessions, memory, and WebUI history survive restarts. Persistent disks require a paid service (they are not available on Render's free tier). [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/HKUDS/nanobot) ## What can nanobot do? nanobot is a self-hosted personal AI agent runtime. It can: - run in a browser WebUI or terminal - connect to Telegram, Discord, Slack, WeChat, Email, Mattermost, and other chat apps - use tools such as files, shell, web search, web fetch, MCP, cron, image generation, and subagents - 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 ## Latest Release **v0.2.2 - Durability Release** Highlights: - Segmented WebUI transcripts - Python SDK runtime controls - Automation management - Search/STT provider improvements - Gateway/session/provider reliability [See full changelog](https://github.com/HKUDS/nanobot/releases/tag/v0.2.2) ## Open Source Partners

## Recent Updates - **2026-07-12** Explicit `/goal` activation, safer runtime and workspace access. - **2026-07-11** Syntax-highlighted previews and diffs, queued prompts, safer edits. - **2026-07-10** Stable model routing, multiline CLI input, new automation guide. - **2026-07-09** Live file-edit diffs, safer localhost setup, Matrix image fixes. - **2026-07-08** Safer WebUI/API setup, onboard refresh, responsive prompt rail. For older updates, see the [release archive](./docs/release-archive.md) or [GitHub releases](https://github.com/HKUDS/nanobot/releases). ## 💡 Why nanobot - **Persistent workflows**: goals, memory, tools, and chat context survive long-running work. - **Chat-native reach**: WebUI, API, Telegram, Feishu, Slack, Discord, Teams, email, and Mattermost. - **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 > [!IMPORTANT] > If you want the newest features and experiments, install from source. > > If you want the most stable day-to-day experience, install from PyPI or with `uv`. Pick **one** install method: Prerequisites: Python 3.11 or newer. Git is only needed for a source install. Published packages already include the WebUI; a current-source install needs `bun` or `npm` to build it. If terminals, API keys, or config files are new to you, use the guided zero-background walkthrough in [Start Without Technical Background](./docs/start-without-technical-background.md) instead of this compact README path. **One-command setup** macOS / Linux: ```bash curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh ``` Windows PowerShell: ```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, skip the manual initialize/configure steps below and go straight to **Open the WebUI**. The installer also prints the exact command it used to run nanobot; reuse that full command below if `nanobot` is not on `PATH`. To preview the plan without changing your environment, pass `--dry-run`; combine it with `--dev` when you want to preview the main-branch install. ```bash curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dry-run ``` ```powershell & ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dry-run ``` To install the current `main` branch instead, pass `--dev`: ```bash curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dev ``` ```powershell & ([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`](./scripts/install.sh) or [`scripts/install.ps1`](./scripts/install.ps1). **Install with `uv`** ```bash uv tool install nanobot-ai ``` **Install from PyPI with pip** ```bash 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** `bun` or `npm` must be available. From an activated virtual environment: ```bash git clone https://github.com/HKUDS/nanobot.git cd nanobot python -m pip install . ``` On Windows, if pip reports that it cannot launch `npm`, run `cd webui`, `npm.cmd install --package-lock=false`, `npm.cmd run build`, and `cd ..` in order, then retry the install. Contributors who need an editable checkout should follow [`CONTRIBUTING.md`](./CONTRIBUTING.md) and [`webui/README.md`](./webui/README.md). Verify the install: ```bash nanobot --version ``` If `nanobot` is not on `PATH`, invoke it through the method that installed it: reuse the recommended installer's command, use `uv tool run --from nanobot-ai nanobot ...` or `pipx run --spec nanobot-ai nanobot ...`, or use the Python executable from the environment where pip installed the package. ## 🚀 Quick Start **1. Initialize** Skip this step if the one-command setup already started the wizard and Quick Start finished there. ```bash nanobot onboard ``` Use `nanobot onboard --wizard` if you prefer an interactive setup. **2. Configure** (`~/.nanobot/config.json`) Skip this step if you already configured provider and model settings in the wizard. `nanobot onboard` creates `~/.nanobot/config.json` and `~/.nanobot/workspace/`. Configure these **two parts** in the config file. Add or merge the following blocks into the existing file instead of replacing the whole file. The example below uses a generic OpenAI-compatible `custom` provider so the compact path does not recommend one hosted service. Provider examples are recipes, not rankings or endorsements. For copyable provider-specific setup, see [Provider Cookbook](./docs/provider-cookbook.md). *Set your API key*: ```json { "providers": { "custom": { "apiKey": "your-api-key", "apiBase": "https://api.example.com/v1" } } } ``` *Set a model preset and make it active*: ```json { "modelPresets": { "primary": { "label": "Primary", "provider": "custom", "model": "model-id-from-your-provider", "maxTokens": 8192, "contextWindowTokens": 200000, "temperature": 0.1 } }, "agents": { "defaults": { "modelPreset": "primary" } } } ``` Direct `agents.defaults.provider` and `agents.defaults.model` still work for existing configs, but named presets are the recommended path because they also power `/model` switching and `fallbackModels`. For another provider, the same config shape still applies: | Replace | Where | |---|---| | Provider config key | `providers.` | | API key | `providers..apiKey` | | Preset provider name | `modelPresets.primary.provider` | | Model ID | `modelPresets.primary.model` | | Endpoint URL, only when needed | `providers..apiBase` | **3. Open the WebUI** The stable-compatible path is: ```bash nanobot gateway ``` Leave the terminal open and visit `http://127.0.0.1:8765`. Current source versions also provide `nanobot webui`, which prepares the local WebSocket channel if needed, starts the gateway, and opens the browser automatically. The first-run WebUI binds to `127.0.0.1` by default, so it is not exposed to your LAN. Prefer not to keep a terminal open? Use `nanobot gateway --background`, then manage it with `nanobot gateway status`, `logs`, `restart`, and `stop`. For manual or terminal-only setup, test one CLI message: ```bash nanobot status nanobot agent -m "Hello!" ``` In `nanobot status`, it is normal for most providers to say `not set`. The active preset's provider should be configured, and `Config` plus `Workspace` should show check marks. If that works, start an interactive chat: ```bash nanobot agent ``` Need help with `PATH`, API keys, provider/model matching, or JSON errors? See the fuller [Install and Quick Start](./docs/quick-start.md) and [Troubleshooting](./docs/troubleshooting.md). - Want a pasteable provider setup? See [Provider Cookbook](./docs/provider-cookbook.md) - Want to understand provider/model matching? See [Providers and Models](./docs/providers.md) - Want web search, MCP, security settings, or more config options? See [Configuration](./docs/configuration.md) - Want to run locally? See [Ollama](./docs/providers.md#ollama), [vLLM or another local OpenAI-compatible server](./docs/providers.md#vllm-or-other-local-openai-compatible-server), and the full [provider reference](./docs/configuration.md#providers). - Want to run nanobot in chat apps like Telegram, Discord, WeChat or Feishu? See [Chat Apps](./docs/chat-apps.md) - Want Docker or Linux service deployment? See [Deployment](./docs/deployment.md) ## 🌐 WebUI The WebUI ships **inside the published wheel** — no extra build step. It is the browser workbench for chat sessions, workspace controls, Apps, Skills, Automations, and settings. For the full user guide, see [`docs/webui.md`](./docs/webui.md).

nanobot webui preview

**Open it** ```bash nanobot webui ``` On current source versions, the command enables the local WebSocket channel after confirmation, starts the gateway, and opens [`http://127.0.0.1:8765`](http://127.0.0.1:8765). If your installed stable release does not include `nanobot webui`, run `nanobot gateway` and open that address manually. To open it from another device on your LAN, see [WebUI docs -> LAN access](./docs/webui.md#lan-access). The WebUI is served by the WebSocket channel on port `8765` by default. The gateway's `18790` port is for the health endpoint, not the browser UI. > [!TIP] > Working on the WebUI itself? Check out [`webui/README.md`](./webui/README.md) for the source-tree, Vite dev server, build, and test workflow. ## 🏗️ Architecture

nanobot architecture

🐈 nanobot stays lightweight by centering everything around a small agent loop: messages come in from chat apps, the LLM decides when tools are needed, and memory or skills are pulled in only as context instead of becoming a heavy orchestration layer. That keeps the core path readable and easy to extend, while still letting you add channels, tools, memory, and deployment options without turning the system into a monolith. ## ✨ Features

📈 24/7 Real-Time Market Analysis	🚀 Full-Stack Software Engineer	📅 Smart Daily Routine Manager	📚 Personal Knowledge Assistant

Discovery • Insights • Trends	Develop • Deploy • Scale	Schedule • Automate • Organize	Learn • Memory • Reasoning

## 📚 Docs Browse the [repo docs](./docs/README.md) for the latest features and GitHub development version, or visit [nanobot.wiki](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview) for the stable release documentation. - Use task-oriented guides: [Guides](./docs/guides/README.md) - Start with no technical background: [Start Without Technical Background](./docs/start-without-technical-background.md) - Start from zero with developer basics: [Install and Quick Start](./docs/quick-start.md) - Understand the runtime model: [Concepts](./docs/concepts.md) - Read the source-level map: [Architecture](./docs/architecture.md) - Choose a provider/model: [Providers and Models](./docs/providers.md) - Copy provider setup recipes: [Provider Cookbook](./docs/provider-cookbook.md) - Debug setup and runtime failures: [Troubleshooting](./docs/troubleshooting.md) - Talk to your nanobot with familiar chat apps: [Chat App AI Agent](./docs/guides/chat-app-ai-agent.md) · [Chat Apps](./docs/chat-apps.md) - Schedule or trigger agent work: [Automations](./docs/automations.md) - Configure providers, web search, MCP, and runtime behavior: [Configuration](./docs/configuration.md) - Integrate nanobot with local tools and automations: [OpenAI-Compatible API](./docs/openai-api.md) · [Python SDK](./docs/python-sdk.md) - Run nanobot with Docker or as a Linux service: [Deployment](./docs/deployment.md) ## 🤝 Contribute & Roadmap PRs welcome! The codebase is intentionally small and readable. 🤗 ### Contribution Flow See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, review, and contribution guidelines. **Roadmap** — Pick an item and [open a PR](https://github.com/HKUDS/nanobot/pulls)! - **Multi-modal** — See and hear (images, voice, video) - **Long-term memory** — Never forget important context - **Better reasoning** — Multi-step planning and reflection - **More integrations** — Calendar and more - **Self-improvement** — Learn from feedback and mistakes ## Contact Nanobot was started by [Xubin Ren](https://github.com/re-bin) as a personal open-source project and is now maintained collaboratively with contributors from the open-source community. Feel free to contact [xubinrencs@gmail.com](mailto:xubinrencs@gmail.com) for questions, ideas, or collaboration. ### Contributors

Thanks for visiting ✨ nanobot!