Nanobot

Introduction

Nanobot is an ultra-lightweight, open-source personal AI agent designed to be small, readable, and fully ownable. First committed in February 2026 and released under the MIT license, it has climbed to 44.2k GitHub stars, 7.8k forks, and over 2,900 commits in under five months — making it the fastest-growing personal AI agent framework.

Nanobot's philosophy is deliberately contrarian. Instead of building a heavyweight orchestration layer, it centers everything on a small Python core where messages come in from chat apps, the LLM decides when tools are needed, and memory or skills are pulled in only as context. This keeps the core path readable and easy to extend. Channels, tools, memory, MCP, and deployment options are all optional plugins — not mandatory infrastructure.

You get an agent you can pip install in seconds, configure in minutes, and run across 10+ chat platforms simultaneously — all from a single codebase you can fully inspect and modify. Nanobot doesn't lock you into a proprietary cloud or a single provider. You own the stack, you choose the models (with automatic fallbacks), and you decide where it runs.

"Small core, everything else is optional." — Nanobot's design philosophy.

Key Features

Ultra-Lightweight Python Core

Nanobot's core agent loop is intentionally minimal. Messages flow in from any channel, the LLM processes them with access to tools and memory, and responses stream back. The core path is ~a few hundred lines of Python — readable enough for a single developer to understand and modify in an afternoon.

The entire package is pip-installable:

pip install nanobot-ai

No Docker required. No Node.js. No heavy framework dependencies. The WebUI ships inside the published wheel — no separate build step.

Multi-Channel Chat — "Agent as Coworker"

Nanobot's channel-first approach is its key differentiator. Instead of forcing you into a specific interface, the agent operates where you already work:

Each channel maintains unified cross-channel sessions — conversations persist and context carries over no matter which platform you're using.

Model Routing with Automatic Fallbacks

Nanobot supports 20+ LLM providers and lets you configure model presets with cascading fallbacks:

{
  "modelPresets": {
    "primary": {
      "label": "Primary",
      "provider": "openrouter",
      "model": "anthropic/claude-opus-4.5",
      "maxTokens": 8192,
      "contextWindowTokens": 65536,
      "temperature": 0.1,
      "fallbackModels": [
        {"provider": "openai", "model": "gpt-5.4"},
        {"provider": "anthropic", "model": "claude-sonnet-4.5"}
      ]
    }
  }
}

Supported providers include OpenAI, Anthropic, Google Gemini, DeepSeek, Mistral, Groq, xAI, Kimi, MiniMax, Moonshot, Hugging Face, Ollama, vLLM, Azure OpenAI, AWS Bedrock, OpenRouter, VolcEngine, StepFun, Zhipu, NVIDIA NIM, LM Studio, and more. Switch models mid-session without losing context.

If the primary model is rate-limited, down, or slow, Nanobot automatically falls through to the next available model in the cascade. This makes it resilient for production and always-on use cases.

MCP (Model Context Protocol) Support

Nanobot supports MCP (Model Context Protocol) for connecting external tools, APIs, and data sources. Configure multiple MCP servers with custom authentication, SSE support, and an extension registry:

• Connect databases, search engines, internal APIs
• Register custom tools that the agent can discover and invoke
• MCP resources and prompts are exposed as first-class tools
• Works across all chat channels, not just the CLI

The Unified CLI Apps and MCP system (introduced in v0.2.1) lets you register standalone command-line applications as agent-accessible tools, bridging the gap between traditional CLI utilities and the MCP ecosystem.

Memory, Automation & Persistent Goals

Nanobot is built for long-running, sustained workflows:

• Token-based memory — relevant context persists across conversations without bloating the prompt
• Dream two-stage memory — discovered skills and learned patterns are stored and recalled automatically
• Cron automation — schedule recurring tasks in natural language ("Remind me every morning at 8 AM to review GitHub issues")
• /goal system — set sustained objectives that the agent holds across multiple conversation turns, even across different channels and sessions
• Context compaction — long conversations are automatically summarized and compressed to stay within context windows

Built-in WebUI

The WebUI ships inside the pip wheel and requires zero build steps:

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

nanobot gateway

Open http://127.0.0.1:8765 for a full chat interface with Thought/response timelines, file-edit activity, project workspaces, and model/context controls. The WebUI is i18n-ready with locale switching and supports LAN access.

Skill Plugin System & Extensibility

Nanobot's skill plugin system lets you add capabilities as on-demand packages:

• Skill discovery — agents can find and learn new skills at runtime
• ClawHub integration — search and install public agent skills from the ClawHub registry
• Python SDK — programmatically interact with Nanobot from your own Python applications
• OpenAI-compatible API — integrate Nanobot with any tool that speaks the OpenAI API format
• Response templates — Jinja2-based templating for custom response formatting
• Lifecycle hooks — composable hooks for agent start, turn, and tool events

Architecture — The Small Core Philosophy

Nanobot's architecture follows a deliberate "small core, everything else is optional" design philosophy. The runtime is organized around a minimal agent loop:

Chat Channel (Telegram, Discord, WebUI, etc.)
       │
       ▼
  ┌──────────┐
  │ Gateway  │  Unified entry point, routes messages to the agent loop
  └────┬─────┘
       │
       ▼
  ┌──────────┐     ┌──────────┐
  │  Agent   │────▶│   LLM    │  Model routing + fallbacks
  │  Loop    │◀────│ Provider │
  └────┬─────┘     └──────────┘
       │
       ├──────────────────┬──────────────────┐
       ▼                  ▼                  ▼
  ┌────────┐     ┌────────────┐     ┌────────────┐
  │ Tools  │     │ Memory     │     │  Skills    │
  │ (MCP,  │     │ (Token/    │     │ (Plugins,  │
  │  CLI)  │     │  Dream)    │     │  ClawHub)  │
  └────────┘     └────────────┘     └────────────┘
       │
       ▼
  ┌──────────┐
  │ Channel  │  Response streamed back to the originating channel
  │ Output   │
  └──────────┘

Key architectural principles:

1. Minimal core — the agent loop is deliberately small and readable. Messages arrive, the LLM processes them with tools, and responses are streamed out.

2. Everything is optional — channels, memory, MCP, skills, the WebUI. Each is a plug-in module that the core discovers and loads. You add only what you need.

3. No heavy orchestration — unlike multi-agent frameworks with complex coordinator hierarchies, Nanobot keeps one agent loop with tool access. Latency stays low and code stays readable.

4. Stateless gateway — the gateway streams requests to LLM providers over standard protocols. Your data stays local; only relevant context is sent to APIs.

5. Unified channel sessions — cross-channel context means you can start a conversation in Telegram, continue it in the WebUI, and check results via email.

The project structure reflects this philosophy: the nanobot/ core package is small, while bridge/ contains channel adapters, webui/ contains the frontend, and docs/ contains documentation. Each major subsystem is independently testable and replaceable.

Use Cases

Always-On Personal Assistant

Deploy Nanobot on a VPS or Raspberry Pi and connect it to Telegram, Discord, and Slack. Use it as your always-on personal assistant — researching topics, managing schedules, monitoring GitHub issues, and answering questions across all your chat platforms simultaneously.

Multi-Platform Engineering Companion

Software teams run Nanobot connected to Slack and email, configured with GitHub and MCP tools. Developers ask questions about codebases, trigger CI/CD pipelines, and get code reviews — all from within their existing chat channels without switching context.

Automated News & Research Monitor

Configure Nanobot with web search tools, RSS-reading skills, and cron automation for daily digests. The agent fetches, summarizes, and delivers personalized news briefings to your preferred channel every morning — and can dive deeper on request.

Personal Knowledge Base

With Dream memory and persistent sessions, Nanobot functions as an extensible knowledge base. Feed it documents, have conversations about them, and revisit insights weeks later. The memory system preserves context without manual tagging or folder management.

Home Automation Hub

Run Nanobot alongside local LLMs via Ollama or vLLM . Connect it to home automation MCP servers, schedule reminders, control smart devices through natural language, and manage your daily routine — all from a single agent runtime.

Pricing

Nanobot is 100% free and open source under the MIT license. There are no paid tiers, no feature gates, no usage quotas, no cloud subscription, and no enterprise upsell.

The only cost is the infrastructure you choose:

• LLM API costs — you pay for the models you use (your own API keys for OpenAI, Anthropic, Google, etc., or run local models via Ollama for free)
• Hosting — run on your own machine, a $5/mo VPS, or a Raspberry Pi
• No hidden costs — no per-seat pricing, no message quotas, no premium features

This is a genuinely open-source project started by Xubin Ren as a personal endeavor and sustained by community contributions. The MIT license means you can use, modify, and distribute Nanobot for any purpose — personal, commercial, or otherwise.

Getting Started

Prerequisites

• Python 3.11 or newer
• An API key from your preferred LLM provider ( OpenRouter recommended for easy multi-model access)
• Git (only needed for source install)

One-Command Setup (macOS/Linux)

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

One-Command Setup (Windows PowerShell)

irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex

Install from PyPI

pip install nanobot-ai

Initialize and Configure

# Run the interactive setup wizard
nanobot onboard --wizard

# Or initialize manually
nanobot onboard

The wizard walks you through selecting a provider, entering your API key, and choosing a model. Configuration is saved to ~/.nanobot/config.json.

Test the Agent

# Check status
nanobot status

# Send a single message
nanobot agent -m "Hello! What can you do?"

# Start an interactive CLI session
nanobot agent

Enable the WebUI

Add this to ~/.nanobot/config.json:

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

Then start the gateway:

nanobot gateway

Open http://127.0.0.1:8765 in your browser.

Connect a Chat Channel

Each channel has specific configuration. For example, to connect Telegram:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "your-bot-token-from-BotFather"
    }
  }
}

See the Chat Apps documentation for full channel setup guides.

Upgrade

pip install --upgrade nanobot-ai

Or use the one-command installer again for automatic upgrades.

Further Reading

• Nanobot GitHub Repository — Source code, issues, discussions, and community contributions
• Nanobot Documentation — Official docs with guides, concepts, and configuration reference
• Install and Quick Start — Detailed setup walkthrough for developers
• Start Without Technical Background — Guided setup for non-developers
• Chat Apps Documentation — Full channel integration guides
• Configuration Reference — Providers, MCP, web search, security, and runtime settings
• Architecture Overview — Source-level map of the codebase
• Provider Cookbook — Pasteable provider setup recipes
• Python SDK Documentation — Programmatic integration for Python applications
• Nanobot on X (Twitter) — Project announcements and updates
• Nanobot Discord Community — Community discussions and support