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](https://www.python.org/downloads/).

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

In that terminal, check Python:

```bash
python --version
```

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

```bash
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:

```bash
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`](./provider-cookbook.md) has copyable snippets for several common patterns.

For the example path:

1. Open [openrouter.ai/keys](https://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**

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

**Windows PowerShell**

```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`:

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

```powershell
& ([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:

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

```powershell
& ([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:

```bash
uv tool install nanobot-ai
```

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

```bash
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:

```bash
nanobot --version
```

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

```bash
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:

```bash
nanobot onboard
```

If `nanobot` is not found, run:

```bash
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:

```text
> 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, WeChat, WhatsApp, 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:

```text
{
  "providers": { "...": "..." }
}
{
  "channels": { "...": "..." }
}
```

Merge them into one object:

```json
{
  "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**

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

**macOS**

```bash
open -e ~/.nanobot/config.json
```

**Linux**

```bash
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:

```json
{
  "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:

```bash
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:

```bash
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:

```text
Hello! How can I help you today?
```

If `nanobot` is not found, run:

```bash
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`](./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:

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

2. Run:

```bash
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`](./webui.md).

### Connect a Chat App

1. Read the section for one app in [`chat-apps.md`](./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:

```bash
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`](./providers.md) when a provider/model pair fails, and [`provider-cookbook.md`](./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>.