Install and Quick Start

This page gets one local nanobot reply working. After that, you can add the WebUI, chat apps, local models, web search, MCP, deployment, or custom plugins.

If you have never used a terminal or edited a config file before, use start-without-technical-background.md first. This page assumes you are comfortable pasting commands and editing JSON snippets.

Before You Start

You need:

• Python 3.11 or newer.
• One LLM provider, company endpoint, subscription endpoint, or local model server you can call. The examples below use a generic OpenAI-compatible custom provider so the compact path does not recommend one hosted service; any supported provider works when the key, provider name, and model ID match.
• Git only if you install from source.
• Node.js or Bun only if you are developing the WebUI itself.

[!IMPORTANT] Repository docs may describe features that are available first in source. Install from PyPI or uv for the stable day-to-day release; install from source when you want the newest repository behavior or plan to contribute.

1. Install

Pick one install method.

One-command setup:

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh

On Windows PowerShell:

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

The default command installs or upgrades nanobot-ai from PyPI, then starts nanobot onboard --wizard. It avoids system-wide pip installs by using an active virtual environment, uv, pipx, or a managed venv under ~/.nanobot/venv. If Quick Start finishes and you enabled the WebSocket channel, go straight to Open the WebUI.

To preview the plan without changing your environment, pass --dry-run; combine it with --dev when you want to preview the main-branch install.

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dry-run

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dry-run

To install the current main branch instead, pass --dev:

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dev

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dev

If curl or irm is unavailable, or GitHub raw downloads are blocked on your network, use one of the manual install methods below.

If you prefer to inspect the script first, open ../scripts/install.sh or ../scripts/install.ps1.

Stable release with uv:

uv tool install nanobot-ai
nanobot --version

Stable release with pip:

python -m pip install nanobot-ai
nanobot --version

Use pip only inside an environment you control. If pip reports externally-managed-environment on macOS or Linux, use the one-command installer, uv tool install nanobot-ai, pipx install nanobot-ai, or create a virtual environment first.

Latest source checkout:

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

If your shell cannot find nanobot after a pip install, run the module form:

python -m nanobot --version
python -m nanobot onboard

On Windows, ~ in the docs means your user profile directory, for example C:\Users\you.

The docs use python in commands. If your system exposes Python 3.11+ as python3 or py, use that command in the same place, for example python3 -m pip install nanobot-ai or py -m nanobot --version.

2. Initialize

Skip this section if the one-command setup already started the wizard and Quick Start finished there.

nanobot onboard

Use the wizard if you prefer prompts instead of editing JSON by hand:

nanobot onboard --wizard

Initialization creates:

If you already have a config, nanobot onboard can refresh missing default fields without overwriting your existing values.

3. Configure a Provider

Skip this section if you already configured provider and model settings in the wizard.

Open ~/.nanobot/config.json. Add or merge these blocks into the file created by nanobot onboard; do not replace the whole file unless you want to reset the config.

API key:

{
  "providers": {
    "custom": {
      "apiKey": "your-api-key",
      "apiBase": "https://api.example.com/v1"
    }
  }
}

Model preset:

{
  "modelPresets": {
    "primary": {
      "label": "Primary",
      "provider": "custom",
      "model": "model-id-from-your-provider",
      "maxTokens": 8192,
      "contextWindowTokens": 65536,
      "temperature": 0.1
    }
  },
  "agents": {
    "defaults": {
      "modelPreset": "primary"
    }
  }
}

The provider and model inside a preset must match. The snippet above is only an example. For another provider, replace these values together:

Direct agents.defaults.provider and agents.defaults.model still work for existing configs, but named presets are the recommended path because they also power /model switching and fallback chains. For provider-specific examples across direct, gateway, OAuth, cloud, and local setups, see providers.md.

What about apiBase / base URL?

apiBase is the HTTP base URL of the provider endpoint, not the model name. Most hosted providers in nanobot already know their default endpoint, so you usually only set apiKey and a model preset. Set apiBase when you are using:

• custom for a third-party or self-hosted OpenAI-compatible API;
• a local OpenAI-compatible server such as Ollama, vLLM, or LM Studio;
• a provider-specific alternate endpoint, regional endpoint, proxy, or subscription endpoint.

Examples:

{
  "providers": {
    "custom": {
      "apiKey": "${CUSTOM_API_KEY}",
      "apiBase": "https://api.example.com/v1"
    }
  }
}

{
  "providers": {
    "ollama": {
      "apiBase": "http://localhost:11434/v1"
    }
  }
}

If the provider's docs say the endpoint is /v1, include /v1 in apiBase. The model ID still belongs in the active modelPresets entry.

If you prefer not to store secrets in config.json, reference an environment variable and set it before starting nanobot:

{
  "providers": {
    "custom": {
      "apiKey": "${PROVIDER_API_KEY}",
      "apiBase": "https://api.example.com/v1"
    }
  }
}

4. Check the Setup

nanobot status

This should show the config path, workspace path, active model or preset, and provider summary. It does not send a message to the model, so use it as a quick config check before the first real request.

Read it like this:

5. Open the WebUI

If Quick Start enabled the WebSocket channel, start the gateway:

nanobot gateway

Leave that terminal open, then open http://127.0.0.1:8765 in your browser. Enter the WebUI password you set in the wizard, then send your first message there.

6. Test One CLI Message

Use this path if you skipped Quick Start, declined the WebSocket channel, or want a terminal-only check.

Run a one-shot CLI message:

nanobot agent -m "Hello!"

A successful first run proves that:

• the nanobot command is installed;
• ~/.nanobot/config.json can be loaded;
• the selected provider and model can answer;
• the default workspace can be created and used.

The reply text itself will vary. Any normal assistant answer means the install, config, provider, model, and workspace path are all usable.

If that works, start an interactive CLI chat:

nanobot agent

After the interactive session can answer normally, nanobot can help with its own next setup step. Ask it to read the relevant docs, inspect your current ~/.nanobot/config.json, and make one concrete change such as enabling WebUI, adding a provider preset, or configuring one chat channel. When nanobot says the config is updated, run /restart in the chat or restart the nanobot process manually so long-running processes reload config.json.

Example prompt:

Read docs/quick-start.md, docs/providers.md, and docs/configuration.md in this checkout.
Then update ~/.nanobot/config.json to add a model preset named "primary" for my provider.
Tell me exactly what changed and whether I need to run /restart.

Exit interactive mode with exit, quit, /exit, /quit, :q, or Ctrl+D.

7. Choose Your Next Step

Updating

pip:

python -m pip install -U nanobot-ai
nanobot --version

If pip reports externally-managed-environment, upgrade with the same isolated method you used to install nanobot, such as uv tool upgrade nanobot-ai, pipx upgrade nanobot-ai, or the managed venv created by the one-command installer.

uv:

uv tool upgrade nanobot-ai
nanobot --version

pipx:

pipx upgrade nanobot-ai
nanobot --version

Source checkout:

git pull
python -m pip install -e .
nanobot --version

If you use WhatsApp, rebuild the local bridge after upgrading:

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

First-Run Troubleshooting

For a fuller diagnosis flow, see troubleshooting.md.