GitHub - HKUDS/nanobot: "🐈 nanobot: The Ultra-Lightweight Clawdbot"

🐈 nanobot is an ultra-lightweight personal AI assistant inspired by Clawdbot

⚡️ Delivers core agent functionality in just ~4,000 lines of code — 99% smaller than Clawdbot's 430k+ lines.

📏 Real-time line count: 3,448 lines (run bash core_agent_lines.sh to verify anytime)

📢 News

• 2026-02-08 🔧 Refactored Providers—adding a new LLM provider now takes just 2 simple steps! Check here.
• 2026-02-07 🚀 Released v0.1.3.post5 with Qwen support & several key improvements! Check here for details.
• 2026-02-06 ✨ Added Moonshot/Kimi provider, Discord integration, and enhanced security hardening!
• 2026-02-05 ✨ Added Feishu channel, DeepSeek provider, and enhanced scheduled tasks support!
• 2026-02-04 🚀 Released v0.1.3.post4 with multi-provider & Docker support! Check here for details.
• 2026-02-03 ⚡ Integrated vLLM for local LLM support and improved natural language task scheduling!
• 2026-02-02 🎉 nanobot officially launched! Welcome to try 🐈 nanobot!

Key Features of nanobot:

🪶 Ultra-Lightweight: Just ~4,000 lines of core agent code — 99% smaller than Clawdbot.

🔬 Research-Ready: Clean, readable code that's easy to understand, modify, and extend for research.

⚡️ Lightning Fast: Minimal footprint means faster startup, lower resource usage, and quicker iterations.

💎 Easy-to-Use: One-click to deploy and you're ready to go.

🏗️ Architecture

✨ Features

📦 Install

Install from source (latest features, recommended for development)

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

Install with uv (stable, fast)

uv tool install nanobot-ai

Install from PyPI (stable)

🚀 Quick Start

1. Initialize

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

For OpenRouter - recommended for global users:

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5"
    }
  }
}

3. Chat

nanobot agent -m "What is 2+2?"

That's it! You have a working AI assistant in 2 minutes.

🖥️ Local Models (vLLM)

Run nanobot with your own local models using vLLM or any OpenAI-compatible server.

1. Start your vLLM server

vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000

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

{
  "providers": {
    "vllm": {
      "apiKey": "dummy",
      "apiBase": "http://localhost:8000/v1"
    }
  },
  "agents": {
    "defaults": {
      "model": "meta-llama/Llama-3.1-8B-Instruct"
    }
  }
}

3. Chat

nanobot agent -m "Hello from my local LLM!"

💬 Chat Apps

Talk to your nanobot through Telegram, Discord, WhatsApp, or Feishu — anytime, anywhere.

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}

nanobot channels login
# Scan QR with WhatsApp → Settings → Linked Devices

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+1234567890"]
    }
  }
}

# Terminal 1
nanobot channels login

# Terminal 2
nanobot gateway

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxx",
      "appSecret": "xxx",
      "encryptKey": "",
      "verificationToken": "",
      "allowFrom": []
    }
  }
}

{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "clientId": "YOUR_APP_KEY",
      "clientSecret": "YOUR_APP_SECRET",
      "allowFrom": []
    }
  }
}

⚙️ Configuration

Config file: ~/.nanobot/config.json

Providers

ProviderSpec(
    name="myprovider",                   # config field name
    keywords=("myprovider", "mymodel"),  # model-name keywords for auto-matching
    env_key="MYPROVIDER_API_KEY",        # env var for LiteLLM
    display_name="My Provider",          # shown in `nanobot status`
    litellm_prefix="myprovider",         # auto-prefix: model → myprovider/model
    skip_prefixes=("myprovider/",),      # don't double-prefix
)

class ProvidersConfig(BaseModel):
    ...
    myprovider: ProviderConfig = ProviderConfig()

Security

CLI Reference

# Add a job
nanobot cron add --name "daily" --message "Good morning!" --cron "0 9 * * *"
nanobot cron add --name "hourly" --message "Check status" --every 3600

# List jobs
nanobot cron list

# Remove a job
nanobot cron remove <job_id>

🐳 Docker

Build and run nanobot in a container:

# Build the image
docker build -t nanobot .

# Initialize config (first time only)
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot onboard

# Edit config on host to add API keys
vim ~/.nanobot/config.json

# Run gateway (connects to Telegram/WhatsApp)
docker run -v ~/.nanobot:/root/.nanobot -p 18790:18790 nanobot gateway

# Or run a single command
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot agent -m "Hello!"
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot status

📁 Project Structure

nanobot/
├── agent/          # 🧠 Core agent logic
│   ├── loop.py     #    Agent loop (LLM ↔ tool execution)
│   ├── context.py  #    Prompt builder
│   ├── memory.py   #    Persistent memory
│   ├── skills.py   #    Skills loader
│   ├── subagent.py #    Background task execution
│   └── tools/      #    Built-in tools (incl. spawn)
├── skills/         # 🎯 Bundled skills (github, weather, tmux...)
├── channels/       # 📱 WhatsApp integration
├── bus/            # 🚌 Message routing
├── cron/           # ⏰ Scheduled tasks
├── heartbeat/      # 💓 Proactive wake-up
├── providers/      # 🤖 LLM providers (OpenRouter, etc.)
├── session/        # 💬 Conversation sessions
├── config/         # ⚙️ Configuration
└── cli/            # 🖥️ Commands

🤝 Contribute & Roadmap

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

Roadmap — Pick an item and open a PR!

• Voice Transcription — Support for Groq Whisper (Issue #13)
• Multi-modal — See and hear (images, voice, video)
• Long-term memory — Never forget important context
• Better reasoning — Multi-step planning and reflection
• More integrations — Discord, Slack, email, calendar
• Self-improvement — Learn from feedback and mistakes

Contributors

⭐ Star History

_{nanobot is for educational, research, and technical exchange purposes only}