Skip to content

Your lightweight open-source personal agent.

11.4 KB
Raw Blame

Install and Quick Start

This guide has one goal: get a normal nanobot reply in your browser. Do not add chat apps, MCP servers, fallback models, or deployment until this path works.

If terminals, Python, or API keys are unfamiliar, use the beginner walkthrough, which explains each term and screen.

These repository docs describe main, which can be newer than the released package. The installer below installs the latest stable release. Check nanobot --version and use the matching stable guide if its setup screens differ from this page.

What You Need

  • Python 3.11 or newer.
  • Access to one supported AI provider, company endpoint, or local model server.
  • The credential, endpoint URL, and model ID required by that service. Local providers such as Ollama may not require a key.

Official platform packages include the WebUI and matching native TUI for macOS 13+ (Apple Silicon and Intel), glibc 2.17+ Linux (ARM64 and x64), and Windows x64; no frontend build tools are needed. Other platforms can use the WebUI or nanobot --classic; see terminal requirements. Source installs need Git and use Bun, which nanobot downloads when needed.

1. Install nanobot

The recommended installer keeps nanobot out of the system Python environment. On a fresh local desktop, it starts the WebUI when installation finishes.

macOS / Linux

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

Windows PowerShell

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

A fresh install uses a dedicated environment under ~/.nanobot/venv, even if uv or pipx is on PATH. Existing installations keep their original manager; an active ordinary virtual environment remains an explicit target and is not adopted. The installer installs the stable PyPI release and prints the exact command it used to run nanobot. If nanobot is not on PATH, reuse that full command below.

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

2. Configure Your Model

Wait for installation and startup to finish. The browser opens the local WebUI; go to Settings → Models and:

  1. Choose New preset and give it a name. If Convert to presets appears, choose it first.
  2. Open Provider and select your provider. To add one, choose Add provider from the same menu, then enter and save its connection details or complete sign-in.
  3. Choose a model from the list or enter a model ID available to your account.
  4. Choose Save.

The WebUI launcher creates or updates:

Path Purpose
~/.nanobot/config.json Provider, model, WebUI, channel, tool, and runtime settings
~/.nanobot/workspace/ Memory, skills, automations, and generated files
~/.nanobot/sessions/<workspace-id>/ Recent session history stored outside the workspace; the ID remains stable across workspace moves

If the installer did not open the browser, run:

nanobot webui

SSH, headless, existing-config, and older-release installs retain the terminal setup path:

nanobot onboard --wizard

3. Check the Setup

nanobot status

You want:

  • a check mark for Config and Workspace;
  • the model or preset you selected;
  • a configured state for the provider used by that model.

Most other providers can say not set. This command validates local setup but does not call the model.

4. Get the First Reply

If the installer-started WebUI is no longer running, run nanobot webui again. The first-run WebUI is bound to localhost, so other devices on your network cannot reach it.

Send:

Hello!

Any normal assistant answer is success. It proves that nanobot can load the config, reach the selected model, use the workspace, and serve the browser UI.

Fresh official-installer environments start a persistent gateway: closing the browser or terminal does not stop it. Other installations keep their on-demand lifetime unless you explicitly use nanobot webui --detach or the gateway command below. An attached on-demand launcher must stay open; closing its last local client stops that gateway.

To start or inspect a persistent gateway:

nanobot gateway --background
nanobot gateway status

Use nanobot gateway logs, restart, and stop to manage that background gateway.

Terminal-Only Check

If you do not want the browser or need to isolate a WebUI problem, send one message directly:

nanobot -m "Hello!"

Then start an interactive terminal chat with:

nanobot

In interactive mode, Enter sends and Shift+Enter inserts a newline (Ctrl+J is the universal fallback). While nanobot is working, Enter sends immediately, Tab waits until the current response is finished, and Option+Up on macOS (Alt+Up on Windows/Linux) edits the latest waiting message. Exit with exit, /exit, :q, or Ctrl+D.

Continue with nanobot

After the first reply works, describe one next goal in the same chat. With the built-in nanobot-document skill, nanobot can consult documentation bundled with your installation to explain features, guide configuration, and troubleshoot. Include where you are using nanobot and what already works, for example:

  • "I am already using the WebUI. Help me connect Telegram and allow only my account."
  • "Explain what is shared when I start a new topic or choose a different project."
  • "A second model preset returns an authentication error. Help me find which setting to check."

To explicitly request the documentation skill, send:

$nanobot-document Explain how sessions, workspaces, and memory relate in this installation.

This requires a model that supports tools and an enabled nanobot-document skill under Skills → Installed. Enter credentials in the relevant settings forms when needed. If your installed release does not include the skill, or you prefer to read the steps yourself, choose a guide below. Add one capability and test it before moving on:

Goal Recommended path
Learn sessions, workspaces, tools, and access modes WebUI guide
Connect a chat platform Open Channels, then use Chat Apps for platform prerequisites
Change or add a model Open Settings → Models; use the Provider Cookbook for a recipe
Add web search, voice, or image generation Use the matching WebUI Settings page, then consult Configuration for advanced fields
Add an App or MCP integration Open Apps or follow Configure MCP Tools
Schedule agent work Read Automations
Run continuously or remotely Read Deployment
Integrate from code Use the Python SDK or OpenAI-Compatible API

Other Install Methods

Use one method, then continue at Configure Your Model.

uv

uv tool install nanobot-ai
nanobot webui

pip in a virtual environment

python -m pip install nanobot-ai
nanobot webui

If pip reports externally-managed-environment, use the recommended installer, uv tool install nanobot-ai, pipx install nanobot-ai, or create a virtual environment. Do not force a system-wide install.

Current source

Clone the repository and install it in editable mode. nanobot downloads the pinned Bun runtime to run the checkout's matching TUI; Node is not required.

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
python -m venv .venv

Activate it with source .venv/bin/activate on macOS/Linux or .venv\Scripts\Activate.ps1 in Windows PowerShell, then run:

python -m pip install -e .
nanobot webui

The source path follows current main and can be newer than the published package. The editable install keeps Python pointed at the checkout; nanobot runs tui/ with Bun, and nanobot webui automatically rebuilds webui/ when its bundled assets are stale. All normal commands remain the same as a stable install. For development details, follow ../CONTRIBUTING.md.

If the shell cannot find nanobot, reuse the installer's printed command or run Python from the existing installation. For uv or pipx, locate that environment with the original manager; do not start a temporary tool environment to manage it. The official installer's default paths are:

~/.nanobot/venv/bin/python -I -m nanobot --version

Windows PowerShell:

& "$HOME\.nanobot\venv\Scripts\python.exe" -I -m nanobot --version

Replace --version with webui, onboard --wizard, or the arguments you need. Use plain python -m nanobot only when that Python belongs to the installed environment.

Manual Configuration Fallback

Manual configuration

Use this only when the wizard is unavailable or you intentionally manage JSON. First run nanobot onboard, then merge a provider and a named model preset into ~/.nanobot/config.json.

A generic OpenAI-compatible setup has this shape:

{
  "providers": {
    "custom": {
      "apiKey": "${PROVIDER_API_KEY}",
      "apiBase": "https://api.example.com/v1"
    }
  },
  "modelPresets": {
    "primary": {
      "provider": "custom",
      "model": "model-id-from-your-provider"
    }
  },
  "agents": {
    "defaults": {
      "modelPreset": "primary"
    }
  }
}

Replace the provider, endpoint, and model together. Do not pair a credential from one service with a model ID from another. See Provider Cookbook for hosted, OAuth, company, and local examples, and Configuration for exact fields.

Updating

Open Settings → About → Update. Supported installations can update and restart there; others show instructions for their original package manager or deployment. Follow Updating nanobot for Preview selection, backups and recovery. Do not switch installation methods to work around an error.

For an ordinary Python virtual environment, the CLI updater is also available:

nanobot update --check
nanobot update

Stop affected processes and back up configuration and data first; restart and verify the running version afterward. Source checkouts should preserve local changes and follow the development instructions.

If the First Reply Fails

Do not change several settings at once. Start with:

nanobot --version
nanobot status
nanobot agent -m "Hello!"
Symptom First check
nanobot: command not found Reuse the installer command or method-specific runner described under Other Install Methods
JSON parse error Check commas and braces; remember that docs examples are usually snippets
401 or invalid API key Verify the selected provider owns that key and remove accidental spaces
Model not found Use a model ID available from the provider selected in the active preset
CLI works but WebUI does not open Use port 8765, not gateway health port 18790
WebUI works but a chat app does not Check Channels, then run nanobot channels status

Continue with the ordered Troubleshooting guide if the cause is still unclear.