Your lightweight open-source personal agent.
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:
- Choose New preset and give it a name. If Convert to presets appears, choose it first.
- 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.
- Choose a model from the list or enter a model ID available to your account.
- 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.