nanobot/docs/start-without-technical-background.md

Start Without Technical Background

This page is for you if you have never used a terminal, edited a JSON file, or configured an AI model before.

The goal is small: get one local nanobot reply. Do not connect Telegram, Discord, WebUI, Docker, local models, or deployment yet. Those are easier after the first reply works.

What You Are Setting Up

You will see these words during setup:

Word	Plain meaning
Terminal	A text window where you paste commands and press Enter.
Command	One line of text you run in the terminal.
API key	A password-like token from an AI provider. Do not share it publicly.
Provider	The service that owns the API key or local model endpoint.
Model	The AI model ID that the provider can run.
Config file	The settings file nanobot reads when it starts.
Wizard	An interactive terminal menu that edits the config file for you.
Model preset	A named model choice in the config file.
apiBase	The HTTP address of a provider endpoint. Leave it blank unless your provider, proxy, or local server tells you to set one.

1. Open a Terminal

You will paste commands into a terminal. Copy only the command text inside each code block; do not copy the ``` marks.

System	How to open it
Windows	Press Win, type PowerShell, then open Windows PowerShell.
macOS	Press Command + Space, type Terminal, then press Enter.
Linux	Open your app launcher, search for Terminal, then open it.

When the terminal opens, click inside it, paste the command, and press Enter. If a command prints text and returns to a prompt, that is usually normal.

2. Install Python

Install Python 3.11 or newer from python.org.

On Windows, enable Add python.exe to PATH during installation if the installer shows that option.

In that terminal, check Python:

python --version

If Windows says python is not found, close and reopen PowerShell. If it still does not work, try:

py --version

If py works but python does not, replace python with py in the commands below.

If macOS or Linux says python is not found, try:

python3 --version

If python3 works but python does not, replace python with python3 in the manual commands below. The one-command installer already checks both python3 and python.

3. Get a Provider API Key

nanobot does not create AI accounts or API keys for you. Use an AI provider account, company endpoint, subscription endpoint, or local model server that you already control. The steps below use OpenRouter only as a concrete example so the commands and wizard choices have real names; it is not a ranking, default choice, or endorsement.

If you use another provider, keep the same shape but replace the provider name, API key, and model ID with values from that provider. provider-cookbook.md has copyable snippets for several common patterns.

For the example path:

1. Open openrouter.ai/keys.
2. Create or copy an API key.
3. Keep the key private.

An OpenRouter key usually starts with sk-or-v1-. Other providers use different key shapes. Keep the key nearby because the setup wizard will ask you to paste it.

4. Install nanobot

The easiest path is the one-command installer. It installs or upgrades nanobot, then starts the setup wizard. On macOS and Linux it avoids system-wide pip installs by using an active virtual environment, uv, pipx, or a managed venv under ~/.nanobot/venv.

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

These commands install the stable PyPI package. To preview what the installer would do without changing your environment, pass --dry-run:

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

Use the development installer only when a maintainer asks you to test the current main branch:

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 the command says curl or irm is not found, or it cannot download from GitHub, use one of the manual install commands below.

If uv is installed, use:

uv tool install nanobot-ai

If you prefer pip, use it only inside an environment you control:

python -m pip install nanobot-ai

If pip reports externally-managed-environment on macOS or Linux, go back to the one-command installer, use uv tool install nanobot-ai, use pipx install nanobot-ai, or create a virtual environment first.

Then check that nanobot is installed:

nanobot --version

If the terminal cannot find nanobot, use the module form:

python -m nanobot --version

Use python3 -m nanobot --version or py -m nanobot --version if that is the Python command that worked in step 2.

5. Run the Setup Wizard

The one-command installer starts this for you after installation. If you installed manually, run:

nanobot onboard

If nanobot is not found, run:

python -m nanobot onboard

Use python3 -m nanobot onboard or py -m nanobot onboard if that is the Python command that worked in step 2.

The wizard is a terminal menu. It is not a graphical app, but it lets you choose options instead of hand-editing every JSON field.

You will see a menu like this:

> What would you like to configure?
  [Q] Quick Start (recommended)
  [P] LLM Provider
  [M] Model Presets
  [C] Chat Channel
  [H] Channel Common
  [A] Agent Settings
  [I] API Server
  [G] Gateway
  [T] Tools
  [V] View Configuration Summary
  [S] Save and Exit
  [X] Exit Without Saving

Move through the wizard like this:

When you see	Do this
A menu	Use the arrow keys to highlight an option, then press Enter.
A text field	Type or paste the value, then press Enter.
A field you do not need	Keep the shown default or leave it blank, then press Enter.
A back option	Choose it to return to the previous menu.

For the first setup, choose [Q] Quick Start (recommended). It asks for the model provider, API key, model ID, and optionally one chat channel. The other menu items are advanced settings.

If you are following the OpenRouter example:

1. Choose [Q] Quick Start (recommended).
2. Choose No chat channel yet unless you already want to configure WebUI, Telegram, Feishu/Lark, Slack, or Discord now.
3. Select OpenRouter.
4. Paste your OpenRouter API key.
5. Enter a model ID, for example anthropic/claude-sonnet-4.5.
6. Review the Quick Start summary.
7. Choose [S] Save and Exit.

If you choose WebUI / local browser, the wizard will open the WebSocket settings before it enables WebUI.

If OpenRouter says your account cannot use that model, use another OpenRouter model ID that your account can access.

If you are using another provider, use the same wizard choices but substitute that provider's values:

Wizard field	What to enter
Provider menu	The provider that owns your API key or endpoint.
API key	The key from that provider, or leave it blank only if the provider does not use one.
apiBase	Leave blank unless the provider docs, proxy docs, or local server docs give you a URL.
Model ID	A model ID that provider can actually serve.

Then choose [S] Save and Exit.

The wizard creates or updates:

Path	Meaning
~/.nanobot/config.json	Settings file.
~/.nanobot/workspace/	Working folder for memory, sessions, and generated files.

How to Merge JSON Snippets

Most docs examples are snippets, not whole files. Your config.json has one outer { ... }. Add new top-level sections such as providers, modelPresets, agents, or channels inside that same outer object.

Do not paste two separate JSON objects into one file:

{
  "providers": { "...": "..." }
}
{
  "channels": { "...": "..." }
}

Merge them into one object:

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-your-key-here"
    }
  },
  "channels": {
    "websocket": {
      "enabled": true
    }
  }
}

Notice the comma after the providers block. JSON needs commas between sibling sections, but not after the last section. If this feels hard, use nanobot onboard whenever possible.

6. Manual Config Fallback

Use this only if the wizard is unavailable or you prefer opening the file yourself.

Run nanobot onboard --defaults first if ~/.nanobot/config.json does not exist yet.

Use one of these commands:

Windows PowerShell

notepad "$env:USERPROFILE\.nanobot\config.json"

macOS

open -e ~/.nanobot/config.json

Linux

xdg-open ~/.nanobot/config.json

If this is a brand-new install and you have not configured anything else yet, replace the file with this minimal config:

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-your-key-here"
    }
  },
  "modelPresets": {
    "primary": {
      "label": "Primary",
      "provider": "openrouter",
      "model": "anthropic/claude-sonnet-4.5",
      "maxTokens": 4096,
      "contextWindowTokens": 65536,
      "temperature": 0.1
    }
  },
  "agents": {
    "defaults": {
      "modelPreset": "primary"
    }
  }
}

Replace sk-or-v1-your-key-here with your real OpenRouter key.

If you use another provider, replace openrouter, sk-or-v1-your-key-here, and the model value with that provider's values. If the provider needs apiBase, add it under that provider's config block.

Save the file.

7. Send the First Message

First check that nanobot can read the saved setup:

nanobot status

This should show the config file path, workspace path, and the active model or preset. If nanobot is not found, use python -m nanobot status, python3 -m nanobot status, or py -m nanobot status, matching the Python command that worked in step 2.

It is normal for most providers to say not set. Only the provider you selected for the active preset needs to look configured.

Run:

nanobot agent -m "Hello!"

If that works, nanobot is installed and can call the model.

You should see a normal assistant reply in the terminal. The exact words will differ, but it should look like this shape:

Hello! How can I help you today?

If nanobot is not found, run:

python -m nanobot agent -m "Hello!"

Use python3 -m nanobot agent -m "Hello!" or py -m nanobot agent -m "Hello!" if that is the Python command that worked in step 2.

Once this works, nanobot can help with its own next setup step. Run nanobot agent, ask it to read these docs and update your current config for one specific goal, then run /restart when nanobot tells you the config is ready. For example, ask it to enable the browser UI, add one provider preset, or configure one chat app.

8. If Something Fails

Do not change many things at once. Check the exact error:

Error or symptom	What it usually means
JSON parse error	The config file has a missing comma, extra comma, or mismatched brace. Copy the example again.
401, unauthorized, or invalid API key	The API key is wrong, expired, has extra spaces, or was pasted under the wrong provider.
model not found	The model ID is not available through the selected provider or your account cannot use it.
nanobot: command not found	The install worked in Python, but your shell cannot find the script. Use python -m nanobot ..., python3 -m nanobot ..., or py -m nanobot ..., matching the Python command that worked earlier.
No response after editing config	Restart the command. Long-running processes read config when they start.

For a fuller diagnosis path, see troubleshooting.md.

What Not to Configure Yet

Skip these until the first local message works:

• apiBase: hosted built-in providers often already have default endpoints. You only need apiBase for local models, proxies, custom OpenAI-compatible providers, or special regional/subscription endpoints.
• WebUI and chat apps: first prove nanobot agent -m "Hello!".
• fallback models: useful later, but not needed for the first reply.
• Langfuse: useful for observability, but not needed for first setup.

Next Steps

After the first reply works, choose only one next goal. Keep the terminal that runs nanobot gateway open whenever you use the WebUI or a chat app.

Open the Browser UI

1. Add this snippet to ~/.nanobot/config.json. Merge it into the existing file instead of replacing the whole file:

{ "channels": { "websocket": { "enabled": true } } }

2. Run:

nanobot gateway

3. Leave that terminal open.
4. Open http://127.0.0.1:8765 in your browser.

To stop the WebUI later, return to the gateway terminal and press Ctrl+C.

If nanobot is not found, run python -m nanobot gateway, python3 -m nanobot gateway, or py -m nanobot gateway, matching the Python command that worked earlier. More details are in webui.md.

Connect a Chat App

1. Read the section for one app in chat-apps.md.
2. Add only that app's config snippet. Merge it into the existing file instead of replacing the whole file.
3. Run:

nanobot channels status
nanobot gateway

4. Leave the gateway terminal open, then send a message from the allowed account.

Start with a private chat or a test server. Do not set allowFrom to ["*"] unless you intentionally want anyone who can reach that channel to talk to the bot.

Change Models or Add Backups

Use providers.md when a provider/model pair fails, and provider-cookbook.md when you want copyable snippets. Keep model choices in modelPresets, then select the active one with agents.defaults.modelPreset.

Ask for Help

When you ask for help, include:

• your operating system;
• the command you ran;
• nanobot --version;
• nanobot status;
• whether nanobot agent -m "Hello!" works;
• the exact error text;
• a config snippet with API keys and tokens removed.

Never paste real API keys, bot tokens, OAuth tokens, or private chat IDs into a public issue or chat.

If you find a docs mistake, outdated command, or confusing step, please open an issue: https://github.com/HKUDS/nanobot/issues.