Skip to content

Your lightweight open-source personal agent.

10.8 KB
Raw Blame

Start Without Technical Background

This walkthrough is for people who have not used a terminal, API key, or JSON config file before. The goal is only to get one reply in a browser. You do not need to understand nanobot's architecture or edit its config by hand.

What You Will Need

  • A Windows, macOS, or Linux computer.
  • Python 3.11 or newer.
  • An account or endpoint that can run an AI model.
  • The API key, login, endpoint, and model name required by that service. A local model such as Ollama may not require an API key.

An API key is password-like. Do not post it in an issue, screenshot, chat, or public config file.

A Few Useful Words

Word Meaning
Terminal A text window where you paste a command and press Enter
Command One instruction typed into the terminal
Provider The service or local server that runs the AI model
Model ID The exact model name expected by that provider
API key A secret credential that lets software call the provider
Wizard A question-and-answer setup menu
WebUI The local browser page where you use nanobot

1. Install Python

Download Python from python.org if you do not already have version 3.11 or newer. On Windows, enable Add python.exe to PATH if the installer shows that option.

Open a terminal:

System How
Windows Press Win, type PowerShell, and open Windows PowerShell
macOS Press Command+Space, type Terminal, and press Enter
Linux Open your application menu and search for Terminal

Check Python:

python --version

The result should start with Python 3.11 or a newer number. If the command is not found, close and reopen the terminal. You can also try python3 --version on macOS/Linux or py --version on Windows.

2. Prepare Your Model Details

An account on a chat website does not automatically let nanobot use that service. Before you start, find out which AI service you will use, how nanobot can sign in (usually with an API key, sometimes with a supported sign-in flow), and the exact model name the service requires. Check the service's pricing and available models. Some services also require a URL; use it only if that service provides one.

If you do not have a provider yet, here is one API-based example:

  1. Create an account at OpenRouter.
  2. Open its API keys page and create a key. Keep it private; you will paste it into nanobot's provider form.
  3. Choose a model from the model catalog, check its price and account requirements, and copy its model ID. For file/tool tasks, choose a model that supports tool calling. See the official quickstart.
  4. In step 4 below, add the built-in OpenRouter provider with that key, keep its default endpoint, and select the model you chose. This is one option, not a required provider.

For a model running on your own computer, use the Ollama setup recipe instead. For a company-managed service, ask your administrator for the connection details.

If you already have a provider, have these details nearby:

  1. The provider or company endpoint name.
  2. Its API key, if it requires one.
  3. Its base URL, if its documentation gives you one.
  4. A model ID your account can use.

The provider, credential, endpoint, and model must belong together. For example, an API key from one provider usually cannot call a model name copied from a different provider.

3. Install nanobot

Copy the command for your system, paste it into the terminal, and press Enter. Copy only the text inside the code block.

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

The installer downloads the stable nanobot package into an isolated Python environment. On a fresh local desktop, it then starts the WebUI and opens your browser. This can take a few minutes on the first run. Keep the terminal open. It prints the exact command used to run nanobot; if nanobot is not found later, reuse that whole command instead of switching to a different Python command.

If your organization blocks downloaded install scripts, use the alternative install methods or ask your administrator to review the scripts first.

4. Configure Your Model in the WebUI

In the browser, open Settings → Models. Then:

  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.

Treat every API key like a password. Do not include it in screenshots or support requests.

If the installer finishes without opening the browser and nanobot is available, run:

nanobot webui

If the terminal cannot find nanobot, take the exact command printed by the installer and replace its final arguments with webui. It uses the Python executable from the persistent installation, not a temporary tool environment.

On SSH, a computer without a desktop, an existing configuration, or an older nanobot release, the installer may open the terminal wizard instead. Choose Quick Start there and follow its prompts.

5. Get the First Reply

Wait for the startup summary. If the browser did not open automatically, copy the complete login link printed in that terminal, including everything after #, into your browser. The bare http://127.0.0.1:8765 address does not sign a new browser in. Keep the login link private: it contains a credential. Fresh official-installer environments keep running in the background; if the launcher remains attached, leave that terminal open.

Send this message:

Hello!

A normal assistant reply means setup is complete. The exact reply does not matter.

The first-run address is local to your computer. It is not automatically available to other computers on your network.

6. Add One Thing at a Time

Choose one next goal and ask nanobot in your current chat. For example: "I am already using the WebUI. Help me connect Telegram and allow only my account." When the built-in nanobot-document skill is available and enabled, nanobot can use its bundled documentation to guide you. See Continue with nanobot for how to request the skill directly.

You can also follow the steps yourself using the controls and guides below. Add one capability and test it before moving on:

Goal What to do
Change the AI model Open Settings → Models
Add a provider credential Open Settings → Models → Provider → Add provider
Connect Telegram, Discord, Slack, Feishu, WeChat, or another chat app Open Channels, choose the platform, and follow its connection steps
Add a tool integration Open Apps and choose an App or MCP integration
Schedule a reminder or recurring task Ask nanobot in the target chat, then manage it in Automations
Work with project files Follow Your first file task, then see Workspace and Access

Repository docs show the current development version. If your stable package does not yet show Channels, use the Chat Apps guide or update to a release that includes it.

Some runtime changes ask you to restart nanobot. Use the restart action shown by the WebUI or nanobot gateway restart for a background gateway. For an attached on-demand launcher, press Ctrl+C and run nanobot webui again.

For a chat platform's account, bot, token, or permission prerequisites, use the Chat Apps guide. For local models and provider-specific recipes, use the Provider Cookbook.

Your First File Task

  1. Create a practice folder, for example Documents/nanobot-practice, and put a copy of a short text file in it. Keep originals elsewhere for this first task.
  2. Start a new topic in the WebUI. Open the workspace folder selector, choose that folder, and select Confirm. Choose Restricted access.
  3. Ask: "Read notes.txt and write a short summary to summary.md in this folder." Replace notes.txt with your file's name, then open summary.md in the selected folder.

The workspace selects the folder the agent works in on the machine running nanobot. Attaching a file sends that file to the conversation; it does not change the workspace. For PDF and Office files, see File tools.

Return to the saved topic to continue later. A new topic or a different project folder does not create separate long-term memory. For clients whose preferences must stay separate, use separate instances.

If Something Fails

Run these commands one at a time:

nanobot --version
nanobot status
nanobot agent -m "Hello!"
What you see What it usually means
nanobot: command not found Reuse the exact nanobot command printed by the installer; it points to the isolated environment that contains the package
401, unauthorized, or invalid API key The key is wrong, expired, or belongs to a different provider
Model not found The model ID is misspelled or unavailable to your provider account
Browser does not open Copy the complete login link printed by the launcher, including the fragment after #; keep the terminal open if the launcher is attached
Browser opens but messages fail Test nanobot agent -m "Hello!" to separate a model problem from a WebUI problem
A change was saved but nothing changed Restart nanobot so the running process reloads the config

If you ask for help, include your operating system, nanobot --version, nanobot status, the exact command, and the exact error. Remove every API key, bot token, password, OAuth token, and private account ID first.

Continue with the full Troubleshooting guide for an ordered diagnosis.

Open nanobot Later

Run:

nanobot webui

A fresh official-installer environment starts a background gateway and returns control to the terminal. Closing the browser does not stop it. Manage it with nanobot gateway status, logs, restart, and stop; use the exact commands printed for your instance. Other installation methods keep their attached on-demand launch: leave that launcher open, or explicitly use nanobot webui --detach after setup. The last attached client stops an on-demand gateway, not a background gateway. See updates and recovery for the matching installation method.