# nanobot **Repository Path**: lance123123/nanobot ## Basic Information - **Project Name**: nanobot - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-02-05 - **Last Updated**: 2026-02-05 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
nanobot

nanobot: Ultra-Lightweight Personal AI Assistant

PyPI Downloads Python License Feishu WeChat Discord

🐈 **nanobot** is an **ultra-lightweight** personal AI assistant inspired by [Clawdbot](https://github.com/openclaw/openclaw) ⚑️ Delivers core agent functionality in just **~4,000** lines of code β€” **99% smaller** than Clawdbot's 430k+ lines. ## πŸ“’ News - **2026-02-04** πŸš€ v0.1.3.post4 released with multi-provider & Docker support! Check [release notes](https://github.com/HKUDS/nanobot/releases/tag/v0.1.3.post4) for details. - **2026-02-01** πŸŽ‰ nanobot launched! Welcome to try 🐈 nanobot! ## Key Features of nanobot: πŸͺΆ **Ultra-Lightweight**: Just ~4,000 lines of code β€” 99% smaller than Clawdbot - core functionality. πŸ”¬ **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 depoly and you're ready to go. ## πŸ—οΈ Architecture

nanobot architecture

## ✨ 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
## πŸ“¦ Install **Install from source** (latest features, recommended for development) ```bash git clone https://github.com/HKUDS/nanobot.git cd nanobot pip install -e . ``` **Install with [uv](https://github.com/astral-sh/uv)** (stable, fast) ```bash uv tool install nanobot-ai ``` **Install from PyPI** (stable) ```bash pip install nanobot-ai ``` ## πŸš€ Quick Start > [!TIP] > Set your API key in `~/.nanobot/config.json`. > Get API keys: [OpenRouter](https://openrouter.ai/keys) (LLM) Β· [Brave Search](https://brave.com/search/api/) (optional, for web search) > You can also change the model to `minimax/minimax-m2` for lower cost. **1. Initialize** ```bash nanobot onboard ``` **2. Configure** (`~/.nanobot/config.json`) ```json { "providers": { "openrouter": { "apiKey": "sk-or-v1-xxx" } }, "agents": { "defaults": { "model": "anthropic/claude-opus-4-5" } }, "tools": { "web": { "search": { "apiKey": "BSA-xxx" } } } } ``` **3. Chat** ```bash 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** ```bash vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 ``` **2. Configure** (`~/.nanobot/config.json`) ```json { "providers": { "vllm": { "apiKey": "dummy", "apiBase": "http://localhost:8000/v1" } }, "agents": { "defaults": { "model": "meta-llama/Llama-3.1-8B-Instruct" } } } ``` **3. Chat** ```bash nanobot agent -m "Hello from my local LLM!" ``` > [!TIP] > The `apiKey` can be any non-empty string for local servers that don't require authentication. ## πŸ’¬ Chat Apps Talk to your nanobot through Telegram, WhatsApp, or Feishu β€” anytime, anywhere. | Channel | Setup | |---------|-------| | **Telegram** | Easy (just a token) | | **WhatsApp** | Medium (scan QR) | | **Feishu** | Medium (app credentials) |
Telegram (Recommended) **1. Create a bot** - Open Telegram, search `@BotFather` - Send `/newbot`, follow prompts - Copy the token **2. Configure** ```json { "channels": { "telegram": { "enabled": true, "token": "YOUR_BOT_TOKEN", "allowFrom": ["YOUR_USER_ID"] } } } ``` > Get your user ID from `@userinfobot` on Telegram. **3. Run** ```bash nanobot gateway ```
WhatsApp Requires **Node.js β‰₯18**. **1. Link device** ```bash nanobot channels login # Scan QR with WhatsApp β†’ Settings β†’ Linked Devices ``` **2. Configure** ```json { "channels": { "whatsapp": { "enabled": true, "allowFrom": ["+1234567890"] } } } ``` **3. Run** (two terminals) ```bash # Terminal 1 nanobot channels login # Terminal 2 nanobot gateway ```
Feishu (飞书) Uses **WebSocket** long connection β€” no public IP required. ```bash pip install nanobot-ai[feishu] ``` **1. Create a Feishu bot** - Visit [Feishu Open Platform](https://open.feishu.cn/app) - Create a new app β†’ Enable **Bot** capability - **Permissions**: Add `im:message` (send messages) - **Events**: Add `im.message.receive_v1` (receive messages) - Select **Long Connection** mode (requires running nanobot first to establish connection) - Get **App ID** and **App Secret** from "Credentials & Basic Info" - Publish the app **2. Configure** ```json { "channels": { "feishu": { "enabled": true, "appId": "cli_xxx", "appSecret": "xxx", "encryptKey": "", "verificationToken": "", "allowFrom": [] } } } ``` > `encryptKey` and `verificationToken` are optional for Long Connection mode. > `allowFrom`: Leave empty to allow all users, or add `["ou_xxx"]` to restrict access. **3. Run** ```bash nanobot gateway ``` > [!TIP] > Feishu uses WebSocket to receive messages β€” no webhook or public IP needed!
## βš™οΈ Configuration Config file: `~/.nanobot/config.json` ### Providers > [!NOTE] > Groq provides free voice transcription via Whisper. If configured, Telegram voice messages will be automatically transcribed. | Provider | Purpose | Get API Key | |----------|---------|-------------| | `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) | | `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) | | `openai` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) | | `deepseek` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) | | `groq` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) | | `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) |
Full config example ```json { "agents": { "defaults": { "model": "anthropic/claude-opus-4-5" } }, "providers": { "openrouter": { "apiKey": "sk-or-v1-xxx" }, "groq": { "apiKey": "gsk_xxx" } }, "channels": { "telegram": { "enabled": true, "token": "123456:ABC...", "allowFrom": ["123456789"] }, "whatsapp": { "enabled": false }, "feishu": { "enabled": false, "appId": "cli_xxx", "appSecret": "xxx", "encryptKey": "", "verificationToken": "", "allowFrom": [] } }, "tools": { "web": { "search": { "apiKey": "BSA..." } } } } ```
## CLI Reference | Command | Description | |---------|-------------| | `nanobot onboard` | Initialize config & workspace | | `nanobot agent -m "..."` | Chat with the agent | | `nanobot agent` | Interactive chat mode | | `nanobot gateway` | Start the gateway | | `nanobot status` | Show status | | `nanobot channels login` | Link WhatsApp (scan QR) | | `nanobot channels status` | Show channel status |
Scheduled Tasks (Cron) ```bash # 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 ```
## 🐳 Docker > [!TIP] > The `-v ~/.nanobot:/root/.nanobot` flag mounts your local config directory into the container, so your config and workspace persist across container restarts. Build and run nanobot in a container: ```bash # 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](https://github.com/HKUDS/nanobot/pulls)! - [x] **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
Star History Chart

Thanks for visiting ✨ nanobot!

Views

nanobot is for educational, research, and technical exchange purposes only