quick-start.md

Install and Quick Start

Install

Important

This README may describe features that are available first in the latest source code. 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 (latest features, experimental changes may land here first; recommended for development)

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

Install with uv (stable release, fast)

uv tool install nanobot-ai

Install from PyPI (stable release)

pip install nanobot-ai

Update to latest version

PyPI / pip

pip install -U nanobot-ai
nanobot --version

uv

uv tool upgrade nanobot-ai
nanobot --version

Using WhatsApp? Rebuild the local bridge after upgrading:

rm -rf ~/.nanobot/bridge
nanobot channels login whatsapp

Quick Start

Tip

Set your API key in ~/.nanobot/config.json. Get API keys: OpenRouter (Global)

For other LLM providers, please see configuration.md.

For web search capability setup, please see the web-search section in configuration.md.

1. Initialize

nanobot onboard

Use nanobot onboard --wizard if you want the interactive setup wizard.

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

Configure these two parts in your config (other options have defaults).

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": {
      "model": "anthropic/claude-opus-4-5",
      "provider": "openrouter"
    }
  }
}

3. Chat

nanobot agent

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