nanobot

🐈 nanobot is an open-source and ultra-lightweight AI agent in the spirit of OpenClaw, Claude Code, and Codex. It keeps the core agent loop small and readable while still supporting chat channels, memory, MCP and practical deployment paths, so you can go from local setup to a long-running personal agent with minimal overhead.

📢 News

• 2026-05-15 🚀 Released v0.2.0 — /goal holds sustained objectives across turns, WebUI now ships inside the wheel, image generation end to end, 5 new providers with fallback_models, and a real agent-loop refactor. Please see release notes for details.
• 2026-05-14 🎯 /goal for long-term objectives, visible multi-step progress, long-horizon missions in chat.
• 2026-05-13 🧠 Streaming reasoning before answers, automatic backup models, smoother plug-in reconnects.
• 2026-05-12 🎛️ Saved model presets with WebUI badge, simpler plug-in tools, quieter Feishu topic threads.
• 2026-05-11 🖥️ NVIDIA NIM support, terminal bot name and icon, streamed reasoning and MiMo toggle clarity.
• 2026-05-09 🖼️ Sharper image replay, BYO web-search keys in Settings, Feishu threads routed cleanly.
• 2026-05-08 ✨ Inline chat image, redesigned Settings and keys, Dream memory aligned with visible history.
• 2026-05-07 📜 Locale-aware slash palette in WebUI, LAN login, faithful HTTP streaming responses.
• 2026-05-06 🧩 Tunable tool hint, steadier voice and plug-in startups, schedules and reminders that stick.
• 2026-05-05 🛡️ Quiet deny for unknown Telegram chats, Dream cleanup, fuller automation summaries.

💡 Key Features of nanobot

• Ultra-lightweight: stable long-running agent behavior with a small, readable core.
• Research-ready: the codebase is intentionally simple enough to study, modify, and extend.
• Practical: chat channels, API, memory, MCP, and deployment paths are already built in.
• Hackable: you can start fast, then go deeper through repo docs instead of a monolithic landing page.

📦 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.

Install from source

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

Install with uv

uv tool install nanobot-ai

Install from PyPI

pip install nanobot-ai

🚀 Quick Start

1. Initialize

nanobot onboard

2. Configure (~/.nanobot/config.json)

Configure these two parts in your config (other options have defaults). Add or merge the following blocks into your existing config instead of replacing the whole file.

Set your API key (e.g. OpenRouter, recommended for global users):

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

Set your model (optionally pin a provider — defaults to auto-detection):

{
  "agents": {
    "defaults": {
      "provider": "openrouter",
      "model": "anthropic/claude-opus-4-6"
    }
  }
}

3. Chat

nanobot agent

• Want different LLM providers, web search, MCP, security settings, or more config options? See Configuration
• Want to run locally? Use Atomic Chat, vLLM, Ollama, and others.
• 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

{ "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.

[!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.

• 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. 🤗

Branching Strategy

Unsure which branch to target? See CONTRIBUTING.md for details.

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 [email protected] for questions, ideas, or collaboration.

Contributors

⭐ Star History

Thanks for visiting ✨ nanobot!

🚀 Quick Start

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