nanobot

🐈 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

Open Source Partners

📢 News

• 2026-06-01 🚀 Released v0.2.1 — The Workbench Release turns the packaged WebUI into a daily agent workbench: clearer Thought/response timelines, live file-edit activity, project workspaces, model and context controls, steadier sustained goals, CLI Apps + MCP extensions, and broader provider/channel support. Please see release notes for details.
• 2026-05-30 🔐 Safer Matrix verification, bounded media downloads, clearer WebUI model timeline.
• 2026-05-29 🧩 Extension registry, context-window tuning, document extraction controls.
• 2026-05-28 🗂️ Project workspaces, access controls, steadier goals and streaming.
• 2026-05-27 ⏱️ Codex streams respect idle timeouts during long runs.
• 2026-05-26 📡 Telegram webhooks, refreshed Kagi search, cleaner transport errors.
• 2026-05-25 🔌 Unified CLI Apps and MCP, Step Plan support, steadier sustained goals.
• 2026-05-24 🧰 MCP presets, richer slash actions, configurable OpenAI-compatible requests.
• 2026-05-23 🖼️ Zhipu image generation, longer exec windows, cleaner transcription config.
• 2026-05-22 🛠️ CLI Apps, more image providers, safer web redirects and edits.

💡 Why nanobot

• Persistent workflows: goals, memory, tools, and chat context survive long-running work.
• Chat-native reach: WebUI, API, Telegram, Feishu, Slack, Discord, Teams, and email.
• 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; Node.js/Bun are only needed if you are developing the WebUI itself.

If terminals, API keys, or config files are new to you, use the guided zero-background walkthrough in Start Without Technical Background instead of this compact README path.

One-command setup

macOS / Linux:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh)"

Windows 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. If you finish the wizard and save the config, skip the manual initialize/configure steps below and go straight to Test one message.

To preview the plan without changing your environment, pass --dry-run; combine it with --dev when you want to preview the main-branch install.

sh -c "$(curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh)" -- --dry-run

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dry-run

To install the current main branch instead, pass --dev:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh)" -- --dev

& ([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 or scripts/install.ps1.

Install from PyPI

python -m pip install nanobot-ai

Install with uv

uv tool install nanobot-ai

Install from source

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
python -m pip install -e .

Verify the install:

nanobot --version

🚀 Quick Start

1. Initialize

Skip this step if the one-command setup already started the wizard and you saved the config there.

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 OpenRouter only so the JSON has concrete names. Provider examples are recipes, not rankings or endorsements. If you use another provider, replace the provider config key, API key, preset provider name, and model ID together.

Set your API key:

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  }
}

Set a model preset and make it active:

{
  "modelPresets": {
    "primary": {
      "label": "Primary",
      "provider": "openrouter",
      "model": "anthropic/claude-opus-4.5",
      "maxTokens": 8192,
      "contextWindowTokens": 65536,
      "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:

3. Test one message

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:

nanobot agent

Need help with PATH, API keys, provider/model matching, or JSON errors? See the fuller Install and Quick Start and Troubleshooting.

• Want a pasteable provider setup? See Provider Cookbook
• Want to understand provider/model matching? See Providers and Models
• Want web search, MCP, security settings, or more config options? See Configuration
• Want to run locally? See Ollama, vLLM or another local OpenAI-compatible server, and the full provider reference.
• Want to run nanobot in chat apps like Telegram, Discord, WeChat or Feishu? See Chat Apps
• Want Docker or Linux service deployment? See Deployment

🌐 WebUI

The WebUI ships inside the published wheel — no extra build step. Just enable the WebSocket channel and open it in your browser.

1. Enable the WebSocket channel in ~/.nanobot/config.json

Merge this block into your existing config:

{ "channels": { "websocket": { "enabled": true } } }

2. Start the gateway

nanobot gateway

3. Open the WebUI

Visit http://127.0.0.1:8765 in your browser. To open it from another device on your LAN, see WebUI docs → 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 for the Vite dev server (HMR) workflow.

🏗️ 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

📚 Docs

Browse the repo docs for the latest features and GitHub development version, or visit nanobot.wiki for the stable release documentation.

• Start with no technical background: Start Without Technical Background
• Start from zero with developer basics: Install and Quick Start
• Understand the runtime model: Concepts
• Read the source-level map: Architecture
• Choose a provider/model: Providers and Models
• Copy provider setup recipes: Provider Cookbook
• Debug setup and runtime failures: Troubleshooting
• Talk to your nanobot with familiar chat apps: Chat Apps
• Configure providers, web search, MCP, and runtime behavior: Configuration
• Integrate nanobot with local tools and automations: OpenAI-Compatible API · Python SDK
• Run nanobot with Docker or as a Linux service: Deployment

🤝 Contribute & Roadmap

PRs welcome! The codebase is intentionally small and readable. 🤗

Contribution Flow

See CONTRIBUTING.md for setup, review, and contribution guidelines.

Roadmap — Pick an item and open a PR!

• 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

This project was started by Xubin Ren as a personal open-source project and continues to be maintained in an individual capacity using personal resources, with contributions from the open-source community. Feel free to contact xubinrencs@gmail.com for questions, ideas, or collaboration.

Contributors

⭐ Star History

Thanks for visiting ✨ nanobot!