Skip to content

Your lightweight open-source personal agent.

feat(skills): explain nanobot usage from bundled documentation (#6176)

chengyongrucd2a863710ed
diff --git a/.gitignore b/.gitignore
index e8aace56e..2b04d2db6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -107,3 +107,6 @@ webui/.verify-*
# Generated source revision for wheels and sdists
nanobot/_build_commit.txt
+
+# Generated from docs/ by the Hatch build hook (including editable installs)
+nanobot/skills/nanobot-document/references/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6d7860e66..b791e054e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -49,6 +49,8 @@ Keep unrelated local changes out of the topic branch. If your checkout already h
## Development Setup
+For React/TypeScript work, follow the [WebUI development guide](webui/README.md) for HMR, source layout, and frontend checks. Channel-owned frontend code lives beside its channel; the guide covers those tests too.
+
Keep setup boring and reliable. The goal is to get you into the code quickly:
```bash
diff --git a/Dockerfile b/Dockerfile
index 87ba7212e..4b64e9692 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -22,26 +22,23 @@ ENV VIRTUAL_ENV=/app/.venv
ENV PATH="/app/.venv/bin:$PATH"
RUN uv venv --seed "$VIRTUAL_ENV"
-# Install Python dependencies first (cached layer). Hatch reads the custom build
-# hook and its revision helper even for this metadata-only install.
+# Install Python dependencies without building the project (cached layer).
+# Source and documentation changes only invalidate the final package install.
ARG NANOBOT_EXTRAS=
-COPY pyproject.toml README.md LICENSE THIRD_PARTY_NOTICES.md hatch_build.py ./
-COPY nanobot/build_info.py nanobot/
-RUN mkdir -p nanobot && touch nanobot/__init__.py && \
- if [ -n "$NANOBOT_EXTRAS" ]; then \
- NANOBOT_SKIP_WEBUI_BUILD=1 uv pip install \
- --python "$VIRTUAL_ENV/bin/python" --no-cache ".[${NANOBOT_EXTRAS}]"; \
- else \
- NANOBOT_SKIP_WEBUI_BUILD=1 uv pip install \
- --python "$VIRTUAL_ENV/bin/python" --no-cache .; \
- fi && \
- rm -rf nanobot
+COPY pyproject.toml ./
+RUN set -- && \
+ for extra in $(printf '%s' "$NANOBOT_EXTRAS" | tr ',' ' '); do \
+ set -- "$@" --extra "$extra"; \
+ done && \
+ uv pip install --python "$VIRTUAL_ENV/bin/python" --no-cache -r pyproject.toml "$@"
# Copy the full source and install
+COPY README.md LICENSE THIRD_PARTY_NOTICES.md hatch_build.py ./
+COPY docs/ docs/
COPY nanobot/ nanobot/
COPY scripts/install_channel_dependencies.py scripts/
COPY --from=webui-builder /app/nanobot/web/dist/ nanobot/web/dist/
-RUN NANOBOT_SKIP_WEBUI_BUILD=1 uv pip install --python "$VIRTUAL_ENV/bin/python" --no-cache .
+RUN NANOBOT_SKIP_WEBUI_BUILD=1 uv pip install --python "$VIRTUAL_ENV/bin/python" --no-cache --no-deps .
# Preinstall selected channel dependencies from their manifests. A comma-separated
# list keeps the image configurable while preserving WhatsApp in the default image.
diff --git a/README.md b/README.md
index d8d0d53ef..b6c064dfd 100644
--- a/README.md
+++ b/README.md
@@ -34,35 +34,38 @@
# nanobot
-🐈 **nanobot** is an ultra-lightweight, open-source, self-hosted personal AI agent framework written in Python. It runs in a WebUI, terminal, or chat apps and combines tools, long-term memory, MCP integrations, model routing, multi-agent delegation, scheduled automation, and an OpenAI-compatible API in a small, readable core.
+🐈 **nanobot** is an ultra-lightweight, open-source, self-hosted personal AI agent framework written in Python. Use it in a browser, terminal, or chat app to work with files, remember preferences, and schedule tasks. Connect a supported model provider or local model server to supply the AI.
## Start Here
| You want to... | Go to |
|---|---|
| Install nanobot with no terminal/config background | [Start Without Technical Background](./docs/start-without-technical-background.md) |
-| Install quickly and get one CLI reply | [Install](#-install) and [Quick Start](#-quick-start) |
+| Install quickly and get your first reply | [Install](#-install) and [Quick Start](#-quick-start) |
| Open the bundled browser UI | [WebUI](#-webui) |
-| Connect Telegram, Discord, WeChat, Slack, Email, Mattermost, Linear, or another channel | [Chat Apps](./docs/chat-apps.md) |
+| Connect Telegram, Discord, WeChat, Slack, Email, Mattermost, Linear, or another channel | [Chat app guide](./docs/guides/chat-app-ai-agent.md) |
| Configure providers, fallback models, Langfuse, MCP, web tools, or security | [Docs](./docs/README.md) and [Configuration](./docs/configuration.md) |
-| Understand or extend the internals | [Architecture](./docs/architecture.md) and [Development](./docs/development.md) |
+| Develop the browser UI | [Install current source](#-install), then [WebUI development](./webui/README.md) and [Contributing](./CONTRIBUTING.md) |
+| Integrate from Python or HTTP | [Python SDK](./docs/python-sdk.md) or [Agent API](./docs/openai-api.md) |
+| Understand or extend the internals | [Architecture](./docs/architecture.md), [Contributing](./CONTRIBUTING.md), and [Provider extensions](./docs/development.md) |
| Deploy to the cloud or keep nanobot running as a service | [Deployment](./docs/deployment.md) |
## What can nanobot do?
-nanobot is a self-hosted personal AI agent runtime. It can:
+nanobot can:
- run in a browser WebUI or terminal
- connect to Telegram, Discord, Slack, WeChat, Email, Mattermost, Linear, and other channels
-- use tools such as files, shell, web search, web fetch, MCP, cron, image generation, and subagents
-- keep session history and long-term memory through Dream
-- run long-horizon goals and scheduled automations
+- read PDF, Word (`.docx`), Excel (`.xlsx`), and PowerPoint (`.pptx`) files with built-in file tools, for tasks such as summarizing reports
+- use shell, web search/fetch, MCP integrations, cron, image generation, and multi-agent delegation
+- keep session history and long-term memory through [Dream](./docs/memory.md#save-and-check-a-preference)
+- run [long-horizon goals](./docs/guides/long-running-ai-agent.md) and [scheduled automations](./docs/automations.md)
- expose a Python SDK and OpenAI-compatible API for integrations
- deploy as a long-running local or server-side agent gateway
## 💡 Why nanobot
-- **Persistent workflows**: goals, memory, tools, and chat context survive long-running work.
+- **Persistent workflows**: keep saved conversations, long-term memory, and task results for later work.
- **Chat-native reach**: WebUI, API, Telegram, Feishu, Slack, Discord, Teams, email, Mattermost, and Linear.
- **Model freedom**: OpenAI-compatible APIs, local LLMs, image generation, search, and fallbacks.
- **Small core**: readable internals with MCP, memory, deployment, and automation built in.
@@ -70,37 +73,38 @@ nanobot is a self-hosted personal AI agent runtime. It can:
## 📦 Install
-> [!IMPORTANT]
-> If you want the newest features and experiments, install from source.
->
-> If you want the most stable day-to-day experience, install from PyPI or with `uv`.
-
-Pick **one** install method:
+You need **Python 3.11 or newer** and access to a [supported model provider or local model server](./docs/providers.md). Model fees or local hardware requirements depend on the service you choose; nanobot does not supply a model account.
-| Track | Install with | Update with | What runs |
-|---|---|---|---|
-| Stable | installer, `uv`, or pip | the same package tool | one released Python/WebUI/TUI version |
-| Current source | editable Git checkout | `git pull --ff-only` + editable dependency sync | Python, WebUI, and TUI from that checkout |
+Choose the **stable release** for everyday use or **current source** for development and the latest features. This README describes current source; [published documentation](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview) covers the released version.
-Prerequisites: Python 3.11 or newer. Git and [Bun](https://bun.sh/) are only needed for a source install. Published packages include the WebUI, and supported platform wheels also include the native TUI. A source-distribution install can fetch a checksummed, version-matched TUI archive—with its licenses, notices, corresponding application source, source offer, and relinking instructions—on first use.
+New to terminals or model credentials? Follow [Start Without Technical Background](./docs/start-without-technical-background.md). Updating an existing instance? Back up its config directory and workspace, stop every old nanobot process using that workspace, then update and restart through the original launcher or service. See [session storage and version changes](./docs/cli-reference.md#session-storage-and-rollback).
-If terminals, API keys, or config files are new to you, use the guided zero-background walkthrough in [Start Without Technical Background](./docs/start-without-technical-background.md) instead of this compact README path.
+**Stable release: automatic setup (recommended)**
-**One-command setup**
+The installer chooses an isolated Python environment and opens setup for you. The two commands below are the same installation method for different operating systems; run only the one for your system.
-macOS / Linux:
+<details>
+<summary>macOS / Linux</summary>
```bash
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh
```
-Windows PowerShell:
+</details>
+
+<details>
+<summary>Windows PowerShell</summary>
```powershell
irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex
```
-The default command installs or upgrades `nanobot-ai` from PyPI. On a fresh local desktop, it then starts `nanobot webui` so you can configure the first provider and model in **Settings → Models**. SSH, headless, existing-config, and older-release paths keep the terminal setup wizard. The installer avoids system-wide pip installs by using an active virtual environment, `uv`, `pipx`, or a managed venv under `~/.nanobot/venv`. It also prints the exact command it used to run nanobot; reuse that full command below if `nanobot` is not on `PATH`.
+</details>
+
+<details>
+<summary>Installer details, preview, and script review</summary>
+
+The installer installs or upgrades `nanobot-ai` using an active virtual environment, `uv`, `pipx`, or a managed venv under `~/.nanobot/venv`. Fresh local desktops open the WebUI; SSH, headless, existing-config, and older-release paths use the terminal setup wizard. Keep the printed command: it identifies the environment that owns the installation.
To preview the plan without changing your environment, pass `--dry-run`.
@@ -114,25 +118,37 @@ curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.
If you prefer to inspect the script first, open [`scripts/install.sh`](./scripts/install.sh) or [`scripts/install.ps1`](./scripts/install.ps1).
-**Install with `uv`**
+</details>
+
+<details>
+<summary>Already use uv or pip? Install the stable package yourself</summary>
+
+Use this instead of the recommended installer when you already manage your own Python environment. These commands install the same stable `nanobot-ai` package; they do not launch setup.
+
+**uv: isolated CLI installation**
```bash
uv tool install nanobot-ai
```
-**Install from PyPI with pip**
+**pip: activate your virtual environment first**
```bash
python -m pip install nanobot-ai
```
-If pip reports `externally-managed-environment` on macOS or Linux, use the one-command installer, `uv tool install nanobot-ai`, `pipx install nanobot-ai`, or install inside a virtual environment.
+Then run `nanobot webui` for browser setup, or `nanobot onboard --wizard` for terminal-only setup. For the [Python SDK](./docs/python-sdk.md), install `nanobot-ai` in your application's virtual environment so the application can import it; a separate `uv tool` environment does not make the SDK importable there.
-Platform wheels include both the WebUI and the native terminal UI: macOS 13+ (Apple Silicon and Intel), glibc 2.17+ Linux (ARM64 and x64), and Windows x64. The x64 runtime requires SSE4.2. Pip selects the matching wheel; opening the TUI does not need a separate GitHub download or Bun installation. A source-distribution install on a supported target can use the matching checksummed GitHub release archive. On other platforms, use `nanobot --classic` or the WebUI.
+If pip reports `externally-managed-environment`, use the recommended installer, `uv tool install nanobot-ai`, `pipx install nanobot-ai`, or an activated virtual environment. Upgrade with the same method; for uv use `uv tool upgrade nanobot-ai`, and for pip use `python -m pip install -U nanobot-ai`.
+
+</details>
+
+**Current source: development checkout**
-**Install from source**
+<details>
+<summary>Install current source with Git and Bun</summary>
-Clone the repository and install it in editable mode. Bun is required because the source checkout runs the matching TUI directly instead of downloading an older release binary.
+Clone the repository and install it in editable mode. A source install requires Git and [Bun](https://bun.sh/); Bun runs the matching TUI directly from the checkout instead of downloading an older release binary.
```bash
git clone https://github.com/HKUDS/nanobot.git
@@ -146,7 +162,34 @@ Activate it with `source .venv/bin/activate` on macOS/Linux or `.venv\Scripts\Ac
python -m pip install -e .
```
-After that, the normal commands are identical to a stable install. `nanobot` runs the TUI from this checkout, and `nanobot webui` rebuilds stale frontend assets automatically. A later `git pull --ff-only` updates the Python, TUI, and WebUI source together; rerun `python -m pip install -e .` when Python dependencies change. Contributors should also read [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+After that, the normal commands are identical to a stable install. `nanobot` runs the TUI from this checkout, and `nanobot webui` rebuilds stale frontend assets automatically. After stopping the old instance, `git pull --ff-only` updates the Python, TUI, and WebUI source together; rerun `python -m pip install -e .` when Python dependencies change, then restart the instance. Contributors should also read [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+
+</details>
+
+<details>
+<summary>Supported platforms, bundled UIs, and release tracks</summary>
+
+Published packages include the WebUI, and supported platform wheels also include the native TUI. A source-distribution install can fetch a checksummed, version-matched TUI archive—with its licenses, notices, corresponding application source, source offer, and relinking instructions—on first use.
+
+Platform wheels include both the WebUI and the native terminal UI: macOS 13+ (Apple Silicon and Intel), glibc 2.17+ Linux (ARM64 and x64), and Windows x64. The x64 runtime requires SSE4.2. Pip selects the matching wheel; opening the TUI does not need a separate GitHub download or Bun installation. A source-distribution install on a supported target can use the matching checksummed GitHub release archive. On other platforms, use `nanobot --classic` or the WebUI.
+
+> [!IMPORTANT]
+>
+> If you want the newest features and experiments, install from source.
+>
+> If you want the most stable day-to-day experience, install from PyPI or with `uv`.
+
+Pick **one** install method:
+
+| Track | Install with | Update with | What runs |
+|---|---|---|---|
+| Stable | installer, `uv`, or pip | [same installation method](./docs/quick-start.md#updating) | one released Python/WebUI/TUI version |
+| Current source | editable Git checkout | `git pull --ff-only` + editable dependency sync | Python, WebUI, and TUI from that checkout |
+
+</details>
+
+<details>
+<summary>Verify the installation or locate the nanobot command</summary>
Verify the install:
@@ -156,83 +199,156 @@ nanobot --version
If `nanobot` is not on `PATH`, invoke it through the method that installed it: reuse the recommended installer's command, use `uv tool run --from nanobot-ai nanobot ...` or `pipx run --spec nanobot-ai nanobot ...`, or use the Python executable from the environment where pip installed the package.
+</details>
+
+After installation, continue with [Quick Start](#-quick-start). Use the exact command printed by the installer if `nanobot` is not on `PATH`.
+
## 🚀 Quick Start
**Open nanobot in your browser**
+If the installer already opened the WebUI, continue there. Otherwise run:
+
```bash
nanobot webui
```
-This is the recommended first run. The launcher creates the config and workspace when needed, safely enables the local WebSocket channel after confirmation, starts or joins the shared local gateway, and opens [`http://127.0.0.1:8765`](http://127.0.0.1:8765). A fresh install can open before a model is configured, so setup continues in the browser instead of beginning in a JSON file. The first-run WebUI binds to localhost by default and is not exposed to your LAN.
+Keep the launcher terminal open while using the browser. It starts or joins the shared local gateway and binds the first-run WebUI to localhost. If the browser does not open, copy the complete login link printed in the terminal, including everything after `#`; keep this credential private. For SSH or a headless host, use the remote-browser or terminal-only instructions below.
**Your first three steps**
-1. Open **Settings → Models** and choose a provider, credential, and model.
-2. Start a new topic and send `Hello!` to verify the connection.
-3. Before project work, choose the intended workspace and access mode from the composer.
+1. Open **Settings → Models** and save a provider/model preset with your credential or supported sign-in. See [model setup](./docs/quick-start.md#2-configure-your-model) if you need the full steps.
+2. Start a new topic and send `Hello!` to verify the model connection.
+3. To try file work, put a copy of `notes.txt` in a practice folder, select that folder and **Restricted** access, and ask: "Read notes.txt and write a short summary to summary.md." Open `summary.md` in that folder to check the result. See [Your first file task](./docs/start-without-technical-background.md#your-first-file-task).
+
+A normal reply verifies the provider/model and browser connection. The file task separately checks the selected project and its file permissions. Attaching a file sends it to the conversation; it does not change the selected project folder.
+
+Then describe your next goal in the same chat, for example: "I am already using the WebUI. Help me connect Telegram and allow only my account." An enabled `nanobot-document` skill can consult the documentation bundled with your installation; see [Continue with nanobot](./docs/quick-start.md#continue-with-nanobot) for examples, explicit invocation, and availability.
-Any normal reply means the provider, model, workspace, and browser gateway are working together.
+<details>
+<summary>Open the WebUI on a remote server through SSH</summary>
-**Keep nanobot running after you close the terminal**
+After installing nanobot on the server, start its WebUI without opening a server-side browser:
```bash
-nanobot gateway --background
+nanobot webui --no-open
```
-This is the only command that promotes the shared gateway to persistent background mode. It leaves channels and automations running after every local TUI and WebUI launcher exits. Complete first-time model setup with `nanobot webui` before switching to background mode; open the same localhost WebUI again afterward.
+Keep that server terminal running. In a second terminal on your own computer, forward the default WebUI port through SSH:
```bash
-nanobot gateway status
-nanobot gateway logs
-nanobot gateway restart
-nanobot gateway stop
+ssh -N -L 127.0.0.1:8765:127.0.0.1:8765 user@SERVER
```
-**Prefer a gateway-first workflow?**
+Replace `user@SERVER` with your SSH login and leave the tunnel open. In your local browser, open the complete login link printed by the server launcher, preserving its `#` fragment. It uses `http://127.0.0.1:8765`, which now reaches the server through the tunnel. Complete **Settings → Models** and send `Hello!`. If local port `8765` is occupied, use another local port in the tunnel and change only the port in the browser link. Keep the server listener on localhost. For Docker, public endpoints, or service management, see [Deployment](./docs/deployment.md).
+
+</details>
+
+<details>
+<summary>Terminal-only setup, one-shot checks, and the TUI</summary>
+
+If a model is not configured yet, use the terminal wizard:
```bash
-nanobot gateway
+nanobot onboard --wizard
```
-This skips WebUI setup and browser opening, then runs the same complete gateway in the current terminal. It is the familiar entry point if you are coming from OpenClaw or already operate agents as long-lived services. The WebUI remains available when its channel is configured; open it manually when needed.
+Check one reply without opening the browser:
-Use `nanobot gateway --background` for the same direct entry point without keeping the terminal attached. For automatic startup and supervision by the operating system, see [Deployment](./docs/deployment.md).
+```bash
+nanobot -m "Hello!"
+```
-**Prefer to work entirely in the terminal?**
+For interactive work, open the terminal client:
```bash
nanobot
```
-This opens the native terminal client with the launch directory as its workspace. It shares saved conversations and the local gateway with the WebUI. The explicit `nanobot agent` form remains available for compatibility.
+The native TUI uses the launch directory as its project workspace and shares saved conversations and the local gateway with the WebUI. The explicit `nanobot agent` form remains available for compatibility.
- Type `/` to discover commands, `/sessions` to switch conversations, or `@` to mention an app, MCP server, or saved session.
- Paste clipboard images with `Ctrl+V` or `Alt+V`, and use `$` to complete skill references.
- Use `/diff` to inspect file changes, `/context` to inspect session context, or `/branch` to continue from a completed reply in a new session.
- Press `Enter` to send. While nanobot is working, `Enter` sends now and `Tab` sends after the current response. Press `Shift+Enter` to add a newline (`Ctrl+J` works in terminals that cannot distinguish modified Enter keys).
-- Use `/detach` to leave the current task running, or start with `nanobot gateway --background` when nanobot should stay online after all local clients exit.
+- Use `/detach` to promote the gateway to background mode and close the TUI while work continues.
+
+Each launch starts a new session by default. Use `--session` to resume one and `--workspace` to choose another project workspace. See the [CLI reference](./docs/cli-reference.md#agent-cli) for session branching, diffs, history, shortcuts, gateway lifecycle, and compatibility options.
+
+</details>
+
+<details>
+<summary>Save and check a preference</summary>
+
+State a specific preference in your chat, for example: "For release notes, use concise bullet points." To consolidate it now, send `/compact` and then `/dream`, waiting for each to finish, and review `/dream-log`. Check the actual changes to `USER.md` or `memory/MEMORY.md` in the configured agent workspace, then test reuse in a new topic in the same instance. Dream may decide that no durable change is needed; a conversational acknowledgement alone does not prove the preference was saved. See [Save and Check a Preference](./docs/memory.md#save-and-check-a-preference) for file access, correction, and restoration steps.
+
+</details>
-Each launch starts a new session by default. Use `--session` to resume one and `--workspace` to choose another workspace. See the [CLI reference](./docs/cli-reference.md#agent-cli) for session branching, diffs, history, shortcuts, gateway lifecycle, and compatibility options.
+<details>
+<summary>Start and stop a sustained goal</summary>
-For one request and an immediate exit, use:
+Use a regular topic for a bounded objective with a clear completion condition, for example:
+
+```text
+/goal Review this project's tests and list the smallest missing test case.
+```
+
+The goal lets nanobot continue work across model turns while the gateway runs; a scheduled automation instead starts a turn at specified times. Use `/stop` to interrupt the current work, and ask nanobot to cancel the goal if you want to abandon it. Keep the gateway running for unattended work using the background or service options below.
+
+After a gateway restart, reopen the original topic and review saved results before explicitly continuing any interrupted work. Recovery does not blindly replay uncertain tool actions. See the [long-running agent guide](./docs/guides/long-running-ai-agent.md) for starting conditions and related automation options.
+
+</details>
+
+<details>
+<summary>Keep the gateway running after closing interactive clients</summary>
+
+After model setup, keep channels and automations running when interactive launchers close:
```bash
-nanobot -m "Hello!"
+nanobot gateway --background
```
-The one-shot form is useful for a quick provider check, shell scripts, and local automation. If you have not configured a model yet, run `nanobot webui` and open **Settings → Models** first.
+This starts or promotes the shared gateway to a detached process. From the TUI, `/detach` does the same before closing that client. Background mode does not configure startup after a machine reboot or restart after a crash; use an [OS-managed service](./docs/deployment.md#switch-an-existing-gateway-to-a-service) for that. Interrupted subagent tasks are not automatically relaunched after a restart, and missed scheduled times are not replayed; see [subagent recovery](./docs/concepts.md#subagents) and [automation delivery](./docs/automations.md#delivery-and-reliability).
-Need manual JSON, another device on your LAN, or help with provider/model matching? Continue with [Install and Quick Start](./docs/quick-start.md), [WebUI](./docs/webui.md), or [Troubleshooting](./docs/troubleshooting.md).
+Manage the background gateway with:
-If nanobot worked for you, a star on GitHub is the simplest way to support the project.
+```bash
+nanobot gateway status
+nanobot gateway logs
+nanobot gateway restart
+nanobot gateway stop
+```
+
+To reopen the browser, run `nanobot webui` against the same instance and use its complete printed login link.
-- Want a pasteable provider setup? See [Provider Cookbook](./docs/provider-cookbook.md)
-- Want to understand provider/model matching? See [Providers and Models](./docs/providers.md)
-- Want web search, MCP, security settings, or more config options? See [Configuration](./docs/configuration.md)
-- Want to run locally? See [Ollama](./docs/providers.md#ollama), [vLLM or another local OpenAI-compatible server](./docs/providers.md#vllm-or-other-local-openai-compatible-server), and the full [provider reference](./docs/configuration.md#providers).
-- Want to run nanobot in chat apps like Telegram, Discord, WeChat or Feishu? See [Chat Apps](./docs/chat-apps.md)
-- Want Docker or Linux service deployment? See [Deployment](./docs/deployment.md)
+</details>
+
+<details>
+<summary>Run a configured gateway directly</summary>
+
+Use this once a model is configured and you want to run the gateway directly in the current terminal:
+
+```bash
+nanobot gateway
+```
+
+It skips guided WebUI setup and browser opening. The WebUI remains available when its channel is configured. Use `nanobot gateway --background` for a detached process, or follow [Deployment](./docs/deployment.md) for startup and supervision by the operating system.
+
+</details>
+
+<details>
+<summary>Read task guides or look up configuration details</summary>
+
+- Model/provider recipes: [Provider Cookbook](./docs/provider-cookbook.md) and [Providers and Models](./docs/providers.md).
+- Local models: [Ollama](./docs/providers.md#ollama), [vLLM or another OpenAI-compatible server](./docs/providers.md#vllm-or-other-local-openai-compatible-server).
+- Chat platforms: [Chat app guide](./docs/guides/chat-app-ai-agent.md), then the [full channel reference](./docs/chat-apps.md).
+- Exact settings for web search, MCP, voice, image generation, and security: [Configuration](./docs/configuration.md).
+- Manual JSON and other setup paths: [Install and Quick Start](./docs/quick-start.md).
+- Failures after setup: [Troubleshooting](./docs/troubleshooting.md).
+
+</details>
+
+If nanobot worked for you, a star on GitHub is the simplest way to support the project.
<a id="deploy-to-render"></a>
@@ -252,7 +368,7 @@ Prefer your own infrastructure? Follow the [deployment guide](./docs/deployment.
## 🌐 WebUI
-The WebUI ships **inside the published wheel** with no separate frontend build. It is the browser workbench for persistent topics, temporary chats, visible agent activity, workspace controls, Apps, Skills, Automations, and settings. Start it with `nanobot webui`.
+The WebUI ships **inside the published wheel** with no separate frontend build. It is the browser workbench for persistent topics, temporary chats, visible agent activity, workspace controls, Apps, Skills, Automations, and settings. Start it with `nanobot webui`. WebUI access grants administration of the same agent instance; share it only with trusted operators. See [Sharing access](./docs/webui.md#sharing-access).
The screenshots below use example conversations, illustrative token counts, and paused schedules.
@@ -268,7 +384,7 @@ Use it to:
- use temporary chats when a conversation should not be saved to history or memory;
- inspect reasoning, tool calls, file edits, diffs, command output, and generated artifacts;
- switch models and workspaces without leaving the conversation;
-- configure providers and chat channels, connect Apps, discover Skills, and manage Automations from one place.
+- configure models in **Settings**, connect chat platforms in **Channels**, and manage Apps, Skills, and Automations.
### Keep related work side by side
@@ -278,7 +394,7 @@ Group up to four conversations and arrange them in columns, rows, a grid, or a m
<img src="./images/nanobot-workbench.png" alt="Three conversations in one workbench: a release plan beside quick-start work and documentation review" width="900">
</p>
-Choose a project, access mode, and model for each task. Attach documents or images, then send follow-ups immediately or queue them for the next response. [Explore topics and panes →](./docs/webui.md#conversation-groups-and-panes)
+Choose a project, access mode, and model for each task. Topics separate conversation history; project folders select where file work happens. Neither creates separate long-term memory: one instance shares its agent profile, memory, and skills across projects. Use [separate instances](./docs/multiple-instances.md) when client data or preferences must stay isolated. [Explore topics and panes →](./docs/webui.md#conversation-groups-and-panes)
### Inspect the work and its context
@@ -292,13 +408,15 @@ Context compaction also appears in the conversation timeline. [Explore activity
### Bring your tools into the conversation
-Use Apps to connect MCP servers, enable Agent Plugins, and manage local CLI App adapters. Add a preset or a custom server, then attach an available tool with `@`. Skills provide reusable instructions; Settings holds model, voice, image, web, and chat-channel setup.
+Use Apps to connect MCP servers, enable Agent Plugins, and manage local CLI App adapters. Add a preset or a custom server, then attach an available tool with `@`. Skills provide reusable instructions. **Settings** holds model, voice, image, and web setup; **Channels** handles chat-platform connections.
<p align="center">
<img src="./images/nanobot-apps.png" alt="The Apps MCP catalog with integration presets and controls to add or import a custom MCP server" width="900">
</p>
-[Explore Apps →](./docs/webui.md#apps) · [Discover Skills →](./docs/webui.md#skills) · [Connect chat apps →](./docs/chat-apps.md)
+[Explore Apps →](./docs/webui.md#apps) · [Discover Skills →](./docs/webui.md#skills) · [Connect chat apps →](./docs/guides/chat-app-ai-agent.md)
+
+Before connecting a personal bot to shared channels, check the platform's DM pairing/allowlist and group-access policies separately. Approving a private sender does not restrict group access on every platform; see the [channel reference](./docs/chat-apps.md).
### Let recurring work run on a schedule
@@ -308,9 +426,9 @@ Ask for an automation from the topic that should receive its results. Use **Task
<img src="./images/nanobot-automations.png" alt="The Automations calendar with completed and upcoming recurring tasks arranged by date" width="900">
</p>
-Keep the gateway running for scheduled delivery. [Explore Automations →](./docs/automations.md)
+Keep the gateway running and the host awake for scheduled delivery. Missed scheduled times are not replayed after a gateway restart. See [delivery and recovery rules](./docs/automations.md#delivery-and-reliability). [Explore Automations →](./docs/automations.md)
-For a conversation that should stay out of saved topic history and long-term memory, use [Temporary chat](./docs/webui.md#temporary-chats) from the header. Temporary chats end when the connection closes and use the default workspace in Restricted mode.
+For a conversation that should stay out of saved topic history and long-term memory, use [Temporary chat](./docs/webui.md#temporary-chats) from the header. Temporary chats end when the connection closes and use the default workspace in Restricted mode. Requests still go to the configured model provider, and files created by tools remain after the chat closes.
See the [WebUI guide](./docs/webui.md) for LAN access, background operation, workspace controls, and the full feature tour. Working on the frontend itself? Use [`webui/README.md`](./webui/README.md).
@@ -320,25 +438,24 @@ See the [WebUI guide](./docs/webui.md) for LAN access, background operation, wor
<img src="images/nanobot_arch.png" alt="nanobot architecture" width="800">
</p>
-🐈 nanobot stays lightweight by centering everything around a small agent loop: messages come in from chat apps, the LLM decides when tools are needed, and memory or skills are pulled in only as context instead of becoming a heavy orchestration layer. That keeps the core path readable and easy to extend, while still letting you add channels, tools, memory, and deployment options without turning the system into a monolith.
+The Python gateway owns agent execution, sessions, tools, memory, and security policy for the WebUI, TUI, and chat apps. The clients share that runtime; the core agent loop builds context, calls the model, executes requested tools, and returns the result. Memory, skills, channels, and MCP integrations extend that loop.
+
+The [Python SDK](./docs/python-sdk.md) embeds the agent runtime in your application process. The [OpenAI-compatible API](./docs/openai-api.md) starts a separate HTTP service for `/v1/chat/completions`: each request contains one user message, history is managed by the server, and the model comes from configuration. Responses return to the HTTP client; that service does not deliver tool messages to chat apps.
+
+See [Architecture](./docs/architecture.md) for source ownership and extension points.
## Docs
-Browse the [repo docs](./docs/README.md) for the latest features and GitHub development version, or visit [nanobot.wiki](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview) for the stable release documentation.
-
-- Use task-oriented guides: [Guides](./docs/guides/README.md)
-- Start with no technical background: [Start Without Technical Background](./docs/start-without-technical-background.md)
-- Start from zero with developer basics: [Install and Quick Start](./docs/quick-start.md)
-- Understand the runtime model: [Concepts](./docs/concepts.md)
-- Read the source-level map: [Architecture](./docs/architecture.md)
-- Choose a provider/model: [Providers and Models](./docs/providers.md)
-- Copy provider setup recipes: [Provider Cookbook](./docs/provider-cookbook.md)
-- Debug setup and runtime failures: [Troubleshooting](./docs/troubleshooting.md)
-- Talk to your nanobot with familiar chat apps: [Chat App AI Agent](./docs/guides/chat-app-ai-agent.md) · [Chat Apps](./docs/chat-apps.md)
-- Schedule or trigger agent work: [Automations](./docs/automations.md)
-- Configure providers, web search, MCP, and runtime behavior: [Configuration](./docs/configuration.md)
-- Integrate nanobot with local tools and automations: [OpenAI-Compatible API](./docs/openai-api.md) · [Python SDK](./docs/python-sdk.md)
-- Run nanobot with Docker or as a Linux service: [Deployment](./docs/deployment.md)
+Browse the [repo docs](./docs/README.md) for current source documentation, or visit [nanobot.wiki](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview) for the stable release. The [task guide index](./docs/guides/README.md) groups walkthroughs by outcome.
+
+- Get started: [Beginner walkthrough](./docs/start-without-technical-background.md) or [Install and Quick Start](./docs/quick-start.md).
+- Choose and configure a model: [Providers and Models](./docs/providers.md) and [Provider Cookbook](./docs/provider-cookbook.md).
+- Connect a chat app: [Chat App AI Agent](./docs/guides/chat-app-ai-agent.md) and [channel reference](./docs/chat-apps.md).
+- Schedule or deploy work: [Automations](./docs/automations.md) and [Deployment](./docs/deployment.md).
+- Integrate from code: [Python SDK](./docs/python-sdk.md) and [OpenAI-Compatible API](./docs/openai-api.md).
+- Look up runtime concepts or exact settings: [Concepts](./docs/concepts.md) and [Configuration](./docs/configuration.md).
+- Diagnose a failure: [Troubleshooting](./docs/troubleshooting.md).
+- Extend the core: [Architecture](./docs/architecture.md) and [contribution workflow](./CONTRIBUTING.md).
## Releases
diff --git a/docs/README.md b/docs/README.md
index 935e9e6a3..bff1da832 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,9 +1,11 @@
# nanobot Documentation
-Use these docs to get a working agent first, then open a task guide only when you need the next capability. Source-level design and extension details are kept in the contributor section.
+Use these docs to get a working agent first. After the first reply, describe your next goal to nanobot or choose a task guide to read yourself. Source-level design and extension details are kept in the contributor section.
Repository docs follow the current source tree and can be newer than the latest package release. For published release docs, visit [nanobot.wiki](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview).
+Use the graphical setup steps first when the WebUI exposes the setting. Expand **Manual configuration** for headless deployments or configuration managed as code. Settings without a graphical control keep their direct configuration instructions.
+
## Start Here
| Your situation | Read this | You are done when... |
@@ -19,7 +21,13 @@ The recommended first-run path is:
3. Configure a provider and model in **Settings → Models**.
4. Send `Hello!` before configuring anything else.
-Most people do not need to edit JSON for the first run. The WebUI handles the initial provider, model, and local browser settings. SSH, headless, existing-config, and older-release installs retain `nanobot onboard --wizard` as a terminal fallback. After the WebUI opens, use **Settings** for models and built-in capabilities, **Settings → Channels** for chat apps, and **Apps** for Agent Plugins, CLI Apps, and MCP integrations.
+Most people do not need to edit JSON for the first run. The WebUI handles the initial provider, model, and local browser settings. SSH, headless, existing-config, and older-release installs retain `nanobot onboard --wizard` as a terminal fallback. After the WebUI opens, use **Settings** for models and built-in capabilities, **Channels** for chat apps, and **Apps** for Agent Plugins, CLI Apps, and MCP integrations.
+
+## After the First Reply
+
+When the built-in `nanobot-document` skill is available and enabled, nanobot can consult the documentation bundled with your installation as you ask about features, configuration, or errors. Describe your current setup and one goal in the same chat; see [Continue with nanobot](./quick-start.md#continue-with-nanobot) for examples and explicit skill invocation. The skill links to the task and reference pages below as needed.
+
+For independent reading, choose a task guide below. Use the reference section when you need an exact field, default, command, or protocol detail.
## Add One Capability
diff --git a/docs/automations.md b/docs/automations.md
index a21734db8..fd1bc92d7 100644
--- a/docs/automations.md
+++ b/docs/automations.md
@@ -18,7 +18,7 @@ The two user-created automation types are scheduled automations and local trigge
## Before You Create One
-Keep `nanobot gateway` running. The gateway owns background delivery for chat apps, WebUI topics, scheduled automations, local triggers, heartbeat, and Dream jobs.
+Keep the gateway running. Your WebUI or TUI already uses one; you do not need a second gateway. To keep it alive after closing interactive launchers, run `nanobot gateway --background` with the same instance selectors, or use `/detach` in the TUI. The gateway owns background delivery for chat apps, WebUI topics, scheduled automations, local triggers, heartbeat, and Dream jobs.
Use the same workspace and config for the gateway and any process that sends local trigger messages. If you run multiple nanobot instances, pass the matching `--config` or `--workspace` option to `nanobot trigger`.
@@ -133,11 +133,21 @@ This changes the whole task chat, not a separate forwarding address. Explicit `m
Chat changes store a binding version and the session used by each previous run. Existing jobs do not need a manual migration when upgrading. Older nanobot versions can discard these new fields when they write the cron store. After a chat change, that can make old run results unavailable in the WebUI and remove protection against stale CLI updates.
-Before trying this feature, stop the gateway and other cron writers, then back up the complete cron directory in the active instance's data directory. For a downgrade after changing a chat, stop those processes again and restore that coherent pre-change cron backup. This also restores the old schedules and task settings; later changes are not included. Chat messages are not moved or deleted.
+Before trying this feature, stop the gateway and other cron writers, then back up the complete `cron/` directory in the configured agent workspace (`~/.nanobot/workspace/cron/` by default), including `jobs.json` and `runs/`. For a downgrade after changing a chat, stop those processes again and restore that coherent pre-change cron backup. This also restores the old schedules and task settings; later changes are not included. Chat messages are not moved or deleted.
## Delivery and Reliability
-Automation delivery is workspace-local. Scheduled jobs and local trigger deliveries use the same workspace as the gateway.
+Automation storage and queue delivery belong to the gateway's configured agent workspace. Scheduled and triggered turns linked to WebUI/TUI chats use the chat's saved project context and access mode; chat-app turns use the gateway's configured workspace. The selected project can differ from the agent workspace that stores jobs, memory, and queues. Starting the TUI inside a project selects that project for the chat but does not by itself create a separate gateway instance. Select the matching configured agent workspace when invoking `nanobot trigger --workspace`, not merely the project directory. See [Multiple Instances](multiple-instances.md) when these need to be separate.
+
+Schedules do not replay missed occurrences after a gateway restart:
+
+| Schedule | Behavior after restart |
+|---|---|
+| One-time (`at`) | A time already in the past has no next run and is not automatically executed. Review the task and run it manually or create a replacement. |
+| Interval (`every`) | The next run is one full interval after restart; missed intervals are not replayed. |
+| Cron expression | The next matching time after restart is used; missed matches are not replayed. |
+
+Intervals are also recalculated after a run finishes, so a long-running task can shift its next interval. Use a cron expression for wall-clock scheduling, and keep the host awake and gateway running when timing matters. These rules concern scheduled jobs; queued local trigger messages have the separate recovery behavior below.
Local trigger messages are written to a durable queue. If the gateway is not running yet, the message waits in that workspace. If the linked topic is already running a turn, the trigger waits until the session becomes idle instead of being injected into the active turn.
diff --git a/docs/chat-apps.md b/docs/chat-apps.md
index 6b9eb61cc..00894e08c 100644
--- a/docs/chat-apps.md
+++ b/docs/chat-apps.md
@@ -30,14 +30,14 @@ If that fails, fix installation, config, provider, or model setup first with [`q
For normal local setup, let the WebUI write and validate the channel config:
1. Run `nanobot webui`.
-2. Open **Settings → Channels**.
+2. Open **Channels**.
3. Search for the platform and open its setup panel.
4. Follow the credential fields or QR flow. The screen tells you which platform-side token, permission, account, or URL it needs.
5. Let nanobot install the optional channel support when prompted.
6. Restart from the WebUI if it reports that a restart is required.
7. Send a private test message. If the channel returns a pairing code, approve the pending request in the WebUI and send the message again.
-If your installed stable release does not show **Settings → Channels**, continue with the [manual setup pattern](#manual-setup-pattern) below or install current source.
+If your installed stable release does not show **Channels**, continue with the [manual setup pattern](#manual-setup-pattern) below or install current source.
Optional package installation is available to a same-machine WebUI by default. Remote browser clients cannot change the Python environment unless an administrator explicitly enables that capability. Run `nanobot plugins enable <channel>` locally when the guided install is unavailable.
@@ -54,14 +54,17 @@ The sections below explain what each chat platform requires and provide manual c
## Manual Setup Pattern
-Most examples below are snippets to merge into `~/.nanobot/config.json`. When a snippet includes `allowFrom`, it is showing a static allowlist. For pairing-based access on supported channels, omit `allowFrom`; Slack and Mattermost also need `dm.policy` set to `"allowlist"` for DMs to issue pairing codes.
+<details>
+<summary>Manual configuration</summary>
+
+Most examples below are snippets to merge into `~/.nanobot/config.json`. When a snippet includes `allowFrom`, it is showing a static allowlist. For pairing-based access on channels with a common sender allowlist, omit `allowFrom`. Slack and Mattermost instead use `dm.policy: "allowlist"` with an empty `dm.allowFrom` for DM pairing; their group policies are independent of DM approval.
Every chat app uses the same shape:
1. Create or prepare the bot/account in the chat platform.
2. Copy the token, secret, QR login state, webhook URL, or account ID that platform gives you.
3. Merge that platform's JSON snippet into `~/.nanobot/config.json`.
-4. Prefer pairing for DM-capable channels: omit `allowFrom`, let the first DM receive a pairing code, then approve it with `/pairing approve <code>`.
+4. For DM pairing, use the channel-specific policy described above, let the first DM receive a pairing code, then approve it with `/pairing approve <code>`.
5. For channels without pairing, such as Email, keep access narrow with `allowFrom` or the platform-specific allow list.
6. Check that nanobot can see the configured channel:
@@ -100,6 +103,8 @@ If `nanobot channels status` does not show the channel as enabled, the config sn
| **Signal** | signal-cli daemon + phone number |
| **Linear** | Private OAuth app + public HTTPS callback and webhook URLs |
+</details>
+
<details id="linear">
<summary><b>Linear</b></summary>
@@ -107,7 +112,7 @@ Linear is a native Agent channel rather than a comment bot. A user starts a task
The native Agent API is webhook-based. Linear must reach a public HTTPS URL. An HTTPS tunnel can forward requests to nanobot's local listener without a public IP; a publicly reachable server can use a reverse proxy. Use a fixed hostname for ongoing use. Temporary tunnels also work for testing, but a hostname change requires updating nanobot's public URL and the app's callback and webhook URLs.
-The recommended setup is **Settings → Channels → Linear**. Enter the public URL and wait for automatic saving, select **Create prefilled Linear app**, create the app, then copy its Client ID, Client Secret, and Webhook Signing Secret back into nanobot. Leave each secret field to save it. Once the settings are saved, choose **Connect Linear**. OAuth requests only `read`, `write`, and `app:mentionable`; it deliberately does not request `app:assignable` so a new task must begin with an @mention.
+The recommended setup is **Channels → Linear**. Enter the public URL and wait for automatic saving, select **Create prefilled Linear app**, create the app, then copy its Client ID, Client Secret, and Webhook Signing Secret back into nanobot. Leave each secret field to save it. Once the settings are saved, choose **Connect Linear**. OAuth requests only `read`, `write`, and `app:mentionable`; it deliberately does not request `app:assignable` so a new task must begin with an @mention.
See the [native Linear agent guide](./guides/linear-agent.md) for the complete setup, tunnel examples, security model, and troubleshooting.
@@ -119,7 +124,7 @@ See the [native Linear agent guide](./guides/linear-agent.md) for the complete s
**Recommended WebUI setup**
1. Create a bot with `@BotFather` and copy its token.
-2. Run `nanobot webui`, then open **Settings → Channels → Telegram**.
+2. Run `nanobot webui`, then open **Channels → Telegram**.
3. Paste the token. If the gateway cannot reach Telegram directly, expand **Advanced** and add an HTTP or SOCKS proxy.
4. Save and enable Telegram, then send the bot a direct message.
@@ -718,7 +723,10 @@ nanobot plugins enable slack
"enabled": true,
"botToken": "xoxb-...",
"appToken": "xapp-...",
- "allowFrom": ["YOUR_SLACK_USER_ID"],
+ "dm": {
+ "policy": "allowlist",
+ "allowFrom": ["YOUR_SLACK_USER_ID"]
+ },
"groupPolicy": "mention"
}
}
@@ -731,7 +739,7 @@ nanobot plugins enable slack
nanobot gateway
```
-DM the bot directly or @mention it in a channel — it should respond!
+The listed Slack user can DM the bot directly. Other DM senders receive a pairing code. Group access is independent: with `groupPolicy: "mention"`, any member can invoke the bot by mentioning it in a channel it can see. For DM-only access, set `groupPolicy` to `"allowlist"` and leave `groupAllowFrom` empty.
> [!TIP]
> - `groupPolicy`: `"mention"` (default — respond only when @mentioned), `"open"` (respond to all channel messages), or `"allowlist"` (restrict to specific channels via `groupAllowFrom`).
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 36fd20139..65c3ea8c0 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -151,7 +151,7 @@ Interactive mode exits with `exit`, `quit`, `/exit`, `/quit`, `:q`, or `Ctrl+D`.
First-run WebUI setup binds to `127.0.0.1` by default. Use manual configuration and a WebUI password before exposing the WebSocket channel beyond localhost.
-`--dev` is a foreground source-checkout workflow. Persistent gateway lifecycle is deliberately owned only by `nanobot gateway --background`; `nanobot webui --background` prints migration guidance instead of silently changing process ownership. It installs frontend dependencies when `webui/node_modules` is missing, proxies to the configured WebSocket channel port, and stops Vite when the launcher exits. The shared on-demand gateway stops only when no other interactive client still holds it.
+`--dev` is a foreground source-checkout workflow. For shell-based lifecycle management, use `nanobot gateway --background` (or `/detach` from an interactive TUI); `nanobot webui --background` prints migration guidance instead of silently changing process ownership. It installs frontend dependencies when `webui/node_modules` is missing, proxies to the configured WebSocket channel port, and stops Vite when the launcher exits. The shared on-demand gateway stops only when no other interactive client still holds it.
## Gateway
diff --git a/docs/concepts.md b/docs/concepts.md
index d80ed4c35..057dc23e2 100644
--- a/docs/concepts.md
+++ b/docs/concepts.md
@@ -84,6 +84,8 @@ The WebUI launcher is the normal browser entry point. Underneath, the gateway ke
## Provider and Model Selection
+Choose and configure the primary model in **Settings → Models**, then select its preset in the chat composer. The config-file example below is an alternative for deployment-managed settings.
+
The active model should normally come from a named `modelPresets` entry selected by `agents.defaults.modelPreset`. Direct `agents.defaults.provider` and `agents.defaults.model` still form the implicit `default` preset for older or minimal configs. The active provider is resolved in this order:
1. If the active preset provider or implicit default provider is not `"auto"`, nanobot uses that provider.
@@ -92,6 +94,9 @@ The active model should normally come from a named `modelPresets` entry selected
Pin the provider inside the preset when setting up for the first time. It is easier to debug:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"modelPresets": {
@@ -108,6 +113,8 @@ Pin the provider inside the preset when setting up for the first time. It is eas
}
```
+</details>
+
See [`providers.md`](./providers.md) for practical examples and [`configuration.md#providers`](./configuration.md#providers) for the full provider reference.
## Channels and Sessions
diff --git a/docs/configuration.md b/docs/configuration.md
index 311e5cdfa..18a20599e 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -4,9 +4,9 @@ Config file: `~/.nanobot/config.json`
This is the full reference. If this is your first install, start with [`quick-start.md`](./quick-start.md). If you are trying to choose a model or fix provider/model matching, use [`providers.md`](./providers.md) first and come back here for exact fields and advanced options.
-For normal local use, prefer the WebUI before editing JSON: **Settings → Models** manages model choices and provider credentials, **Settings → Channels** guides chat-platform setup, other Settings pages cover built-in capabilities, and **Apps** manages CLI App and MCP integrations. Edit `config.json` directly when you need an advanced field, automate deployment, or intentionally manage configuration as code.
+For normal local use, prefer the WebUI before editing JSON: **Settings → Models** manages model choices and provider credentials, **Channels** guides chat-platform setup, other Settings pages cover built-in capabilities, and **Apps** manages CLI App and MCP integrations. Use direct configuration for fields without a graphical control; expand the manual alternatives for headless deployments or configuration managed as code.
-The JSON examples below are usually partial snippets to merge into your existing config, not full replacement files. For the mental model behind config, workspace, gateway, channels, sessions, tools, and memory, see [`concepts.md`](./concepts.md).
+Use the graphical steps for settings exposed in the WebUI. Their JSON alternatives are collapsed under **Manual configuration**. Settings without a graphical control retain direct configuration instructions. JSON examples are usually partial snippets to merge into your existing config, not full replacement files. For the mental model behind config, workspace, gateway, channels, sessions, tools, and memory, see [`concepts.md`](./concepts.md).
The generated `config.json` uses camelCase keys such as `apiKey` and `intervalS`. snake_case keys are also accepted for compatibility, but the docs prefer camelCase because that is what nanobot writes back to disk.
@@ -36,7 +36,7 @@ This page is the complete configuration reference. For task-oriented setup, use
| Keep secrets out of `config.json` | [Environment Variables for Secrets](#environment-variables-for-secrets) |
| Tune process-level behavior with env vars | [Runtime Environment Variables](#runtime-environment-variables) |
| Trace model calls | [Langfuse Observability](#langfuse-observability) |
-| Configure credentials and endpoints | [Providers](#providers) |
+| Connect a provider and choose a model | [Providers](#providers) |
| Name and switch model choices | [Model Presets](#model-presets) |
| Add fallback chains | [Model Fallbacks](#model-fallbacks) |
| Configure voice transcription | [Transcription Settings](#transcription-settings) |
@@ -55,7 +55,7 @@ If the WebUI does not expose the option you need, start from the task below. Mos
| Task | First keys to check | Verify with | Deep dive |
|---|---|---|---|
-| Make the first model reply work | `providers.<name>.apiKey`, optional `providers.<name>.apiBase`, `modelPresets.<preset>`, `agents.defaults.modelPreset` | `nanobot status`, then `nanobot agent -m "Hello!"` | [Providers](#providers), [Model Presets](#model-presets) |
+| Make the first model reply work | Choose a provider and model in **Settings → Models**; add its API key or complete sign-in, keeping the default connection settings | Send `Hello!` in chat | [Providers](#providers), [Model Presets](#model-presets) |
| Add fallback models | `modelPresets.<fallback>`, `agents.defaults.fallbackModels` | `nanobot status`, then a normal agent run | [Model Fallbacks](#model-fallbacks) |
| Keep secrets out of the config file | `${ENV_VAR}` placeholders inside any string value | Start nanobot from the same environment that sets the variable | [Environment Variables for Secrets](#environment-variables-for-secrets) |
| Open the bundled WebUI | `channels.websocket.enabled`, optional `channels.websocket.port`, `channels.websocket.tokenIssueSecret` | `nanobot webui` | [Channel Settings](#channel-settings), [WebSocket docs](./websocket.md) |
@@ -244,24 +244,43 @@ Tracing covers the providers that go through nanobot's OpenAI-compatible client
## Providers
+For a normal first setup:
+
+1. Open **Settings → Models → New preset**.
+2. Choose your provider from **Provider**. If you need a new connection, choose **Add provider** and select the matching built-in provider.
+3. Enter its API key or complete its sign-in flow. Keep the default connection settings.
+4. Choose a model available to your account, save the preset, and select it in chat.
+5. Send `Hello!` before changing advanced options.
+
+Built-in hosted providers use their default service endpoints. You normally do not need to find or enter a Base URL, choose a request API, or configure a proxy. The endpoint field can stay at its supplied default. Some providers, such as Azure, need an account-specific resource address; enter it when the setup form requires it.
+
+For a company gateway, a custom service, or a local model server at a different address, expand the connection notes below. Ollama and LM Studio also have local defaults; change them only if your server runs elsewhere.
+
+<details>
+<summary>Custom endpoints and provider-specific options</summary>
+
+A Base URL is the service address nanobot sends model requests to. Change it only when your service supplies a different endpoint, such as a company proxy, a regional service, or a subscription-specific endpoint. Prefer a dedicated built-in provider when one matches your subscription. For an unlisted service, create a custom connection and enter its address and any required credential; choose the request API under **Advanced options** only when that service requires it. See [custom connection APIs](#custom-connection-apis) for protocol details.
+
> [!TIP]
-> - **Voice transcription**: Voice messages and WebUI microphone input use the shared top-level `transcription` settings. The default `transcription.provider` value is `"groq"`; set it to `"openai"` for OpenAI Whisper, `"openrouter"` for OpenRouter speech-to-text models, `"xiaomi_mimo"` for Xiaomi MiMo ASR, or `"assemblyai"` for AssemblyAI. API keys still live in the matching `providers.<provider>` config.
+> - **Voice transcription**: Choose Groq, OpenAI, OpenRouter, Xiaomi MiMo, StepFun, AssemblyAI, or SiliconFlow in **Settings → Capabilities → Transcription**. Voice messages and WebUI microphone input share these settings; Groq is the runtime default. Configure the matching provider credential in **Settings → Models**.
> - **MiniMax Coding Plan**: Exclusive discount links for the nanobot community: [Overseas](https://platform.minimax.io/subscribe/coding-plan?code=9txpdXw04g&source=link) · [Mainland China](https://platform.minimaxi.com/subscribe/token-plan?code=GILTJpMTqZ&source=link)
-> - **MiniMax (Mainland China)**: If your API key is from MiniMax's mainland China platform (minimaxi.com), set `"apiBase": "https://api.minimaxi.com/v1"` in your minimax provider config.
+> - **MiniMax (Mainland China)**: If your API key is from MiniMax's mainland China platform (minimaxi.com), open the minimax connection in **Settings → Models** and set its base URL to `https://api.minimaxi.com/v1`.
> - **MiniMax thinking mode**: `providers.minimaxAnthropic` is the config block for `reasoningEffort` / thinking mode. MiniMax exposes that capability through its Anthropic-compatible endpoint, so nanobot keeps it as a separate provider instead of guessing MiniMax-specific thinking parameters on the generic OpenAI-compatible `minimax` endpoint. It uses the same `MINIMAX_API_KEY`. Default Anthropic-compatible base URL: `https://api.minimax.io/anthropic`; for mainland China use `https://api.minimaxi.com/anthropic`.
> - **Kimi Coding Plan**: Use `providers.kimiCoding` with `provider: "kimi_coding"` for Kimi's dedicated Anthropic Messages API endpoint. The endpoint requires a Claude-compatible `User-Agent`; nanobot sends `claude-code/0.1.0` by default, and you can override it with `extraHeaders.User-Agent` if your account requires a different value.
> - **VolcEngine / BytePlus Coding Plan**: Subscription endpoints are configured through dedicated providers `volcengineCodingPlan` or `byteplusCodingPlan`, separate from the pay-per-use `volcengine` / `byteplus` providers.
> - **OpenCode Zen / Go**: `providers.opencode` (canonical Zen), the legacy-compatible `providers.opencodeZen`, and `providers.opencodeGo` use the same `OPENCODE_API_KEY`, but route to different OpenCode gateways. These providers use OpenCode's OpenAI-compatible `chat/completions` endpoints; choose model IDs from that endpoint family.
-> - **Zhipu Coding Plan**: If you're on Zhipu's coding plan, set `"apiBase": "https://open.bigmodel.cn/api/coding/paas/v4"` in your zhipu provider config.
-> - **Alibaba Cloud BaiLian**: If you're using Alibaba Cloud BaiLian's OpenAI-compatible endpoint, set `"apiBase": "https://dashscope.aliyuncs.com/compatible-mode/v1"` in your dashscope provider config.
-> - **ModelScope**: If you're using ModelScope's OpenAI-compatible endpoint, set `"apiBase": "https://api-inference.modelscope.cn/v1"` in your modelscope provider config.
-> - **StepFun Step Plan**: If you're on StepFun's Step Plan subscription, set `"apiBase": "https://api.stepfun.ai/step_plan/v1"` in your stepfun provider config. Supported models include `step-3.5-flash`, `step-3.5-flash-2603`, and `step-router-v1`.
-> - **Step Fun (Mainland China)**: If your API key is from Step Fun's mainland China platform (stepfun.com), set `"apiBase": "https://api.stepfun.com/v1"` in your stepfun provider config.
-> - **Xiaomi MiMo thinking mode**: MiMo models (e.g. `mimo-v2.5-pro`) default to enabled thinking. Use `agents.defaults.reasoningEffort: "none"` to disable it, or `"low"` / `"medium"` / `"high"` to keep it on. Omitting the field preserves the provider's per-model default.
-> - **Xiaomi MiMo Token Plan**: If you're on MiMo's token plan, set `"apiBase": "https://token-plan-sgp.xiaomimimo.com/v1"` in your xiaomi_mimo provider config.
+> - **Zhipu Coding Plan**: If you're on Zhipu's coding plan, open the zhipu connection in **Settings → Models** and set its base URL to `https://open.bigmodel.cn/api/coding/paas/v4`.
+> - **Alibaba Cloud BaiLian**: The built-in `dashscope` provider already defaults to `https://dashscope.aliyuncs.com/compatible-mode/v1`; no endpoint override is needed for that service.
+> - **ModelScope**: The built-in `modelscope` provider already defaults to `https://api-inference.modelscope.cn/v1`; no endpoint override is needed for that service.
+> - **StepFun Step Plan**: If you're on StepFun's Step Plan subscription, open the stepfun connection in **Settings → Models** and set its base URL to `https://api.stepfun.ai/step_plan/v1`. Supported models include `step-3.5-flash`, `step-3.5-flash-2603`, and `step-router-v1`.
+> - **Step Fun (Mainland China)**: The built-in `stepfun` provider already defaults to `https://api.stepfun.com/v1`; no endpoint override is needed for that service.
+> - **Xiaomi MiMo thinking mode**: MiMo models (e.g. `mimo-v2.5-pro`) default to enabled thinking. In the preset's **Advanced options**, set reasoning effort to `none` to disable it, or `low` / `medium` / `high` to keep it on. Omitting the field preserves the provider's per-model default.
+> - **Xiaomi MiMo Token Plan**: If you're on MiMo's token plan, open the xiaomi_mimo connection in **Settings → Models** and set its base URL to `https://token-plan-sgp.xiaomimimo.com/v1`.
> - **Custom providers**: Besides the built-in `custom` provider, any extra key under `providers` can define its own endpoint. For example, `providers.companyProxy.apiBase` plus `modelPresets.primary.provider: "companyProxy"` creates a separate custom provider. Set `apiBase`; set `apiKey` only when the endpoint requires it. Declare accepted protocols with `providers.<name>.api`; custom connections can use Chat Completions, Responses, or Anthropic Messages. See [custom connection APIs](#custom-connection-apis).
> - **Provider-scoped proxy**: `providers.<name>.proxy` routes only that provider through an HTTP proxy. It is supported for OpenAI-compatible providers, Anthropic Messages, `openai_codex`, and `xai_grok`. Native `bedrock`, `azure_openai`, and `github_copilot` backends reject `proxy`.
+</details>
+
| Provider | Purpose | Get API Key |
|----------|---------|-------------|
| `custom` | Any OpenAI-compatible endpoint | — |
@@ -1314,12 +1333,17 @@ Contributor notes for adding new providers live in [`development.md`](./developm
## Model Presets
+Open **Settings → Models → New preset**, give the preset a unique name, select its provider and model, and save. Use **Advanced options** for generation settings and request API selection. Select the saved preset in the chat composer.
+
Model presets let you name a complete model configuration and select one per session with `/model <preset>`. They are the recommended way to configure models because the same names can be reused for new-session defaults, chat-command switching, and fallback chains.
For browser setup, follow [Configure Your Model](./quick-start.md#2-configure-your-model). The WebUI accepts token values such as `32k` or `1m`; JSON configuration uses integer token counts.
Existing configs do not need to change. Direct `agents.defaults.model`, `provider`, `maxTokens`, `contextWindowTokens`, `temperature`, and `reasoningEffort` fields still define the implicit `default` preset. For new configs, prefer top-level `modelPresets` plus `agents.defaults.modelPreset`.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"modelPresets": {
@@ -1355,6 +1379,8 @@ Existing configs do not need to change. Direct `agents.defaults.model`, `provide
}
```
+</details>
+
`modelPresets` is a top-level object. Each key (`fast`, `deep`, `coding`, etc.) is the preset's one canonical name: it is shown in the interface, passed to `/model <name>`, and referenced by defaults, fallbacks, sessions, and Dream. New and renamed presets must be unique ignoring case. Existing keys accepted by earlier releases remain loadable so upgrades do not break startup. Each preset supports:
Older configs may still contain a `label` inside a preset. It is accepted when loading for compatibility but ignored; the object key remains the canonical name.
@@ -1377,6 +1403,9 @@ Set `agents.defaults.modelPreset` to choose the preset followed by sessions that
Custom providers use Chat Completions by default. If your service requires another protocol, open its WebUI connection editor and expand **Advanced options**. Use **Supported APIs** to select the protocols the service accepts and **Default API** to choose the default for Auto presets. Hover, focus, or tap a setting label for help. Existing connections without a declaration retain their previous behavior until you change these controls.
+<details>
+<summary>Manual configuration</summary>
+
In `config.json`, set `providers.<name>.api` for the built-in `custom` provider or a named custom provider:
```json
@@ -1394,6 +1423,8 @@ In `config.json`, set `providers.<name>.api` for the built-in `custom` provider
}
```
+</details>
+
`supportedApis` must contain at least one of `chat_completions`, `responses`, or `anthropic_messages`. `preferredApi` must belong to that list and defaults to its first entry. Auto presets inherit this default; explicit presets can only use protocols in the connection's list. Before removing a protocol used by an explicit preset, update that preset first.
### Legacy OpenAI API selector migration
@@ -1412,6 +1443,9 @@ Leave API selection on **Auto** unless your service requires a specific protocol
Selecting Responses also offers **Try Chat Completions if Responses is unsupported**, off by default. Enable it only if the service supports the same model through both APIs. The Auto label shows the default preference; permitted Chat fallback can still change the API used for a request.
+<details>
+<summary>Manual configuration</summary>
+
To configure presets in `config.json`:
```json
@@ -1438,6 +1472,8 @@ To configure presets in `config.json`:
}
```
+</details>
+
`supportedApis` must contain at least one of `chat_completions`, `responses`, or `anthropic_messages`. `preferredApi` must belong to that list and defaults to its first entry. Omit `api` or set it to `null` for Auto. An explicit preset declaration overrides the OpenAI connection default; for custom connections, it must stay within the connection's supported APIs.
A Responses-only preset never falls back to Chat Completions. To allow Chat fallback for Responses compatibility errors, include both `responses` and `chat_completions` with `preferredApi: "responses"`. Other errors do not trigger this API fallback. Provider-hosted search uses Responses when the preset allows it.
@@ -1450,6 +1486,8 @@ OpenAI Codex, xAI Grok subscriptions, and Azure OpenAI use Responses; Anthropic
### Model Fallbacks
+In **Settings → Models**, create the primary and backup presets, then use **Enable preset** and arrange their order. The first enabled preset is primary; later entries are tried as fallbacks. Save and test each preset before relying on the chain.
+
`agents.defaults.fallbackModels` defines an ordered failover chain for the active model configuration. The primary model is still selected by `agents.defaults.modelPreset` or, in older configs, by the implicit `default` preset from direct `agents.defaults.*` fields.
Each fallback candidate can be either:
@@ -1459,6 +1497,9 @@ Each fallback candidate can be either:
Preset fallback chain:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"modelPresets": {
@@ -1492,10 +1533,15 @@ Preset fallback chain:
}
```
+</details>
+
String entries are preset names, not raw model names. In the example above, `"deep"` means `modelPresets.deep`; nanobot will not interpret it as a provider model ID. Changing a preset updates both `/model <preset>` switching and any fallback chain that references it.
Inline fallback object:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"modelPresets": {
@@ -1522,6 +1568,8 @@ Inline fallback object:
}
```
+</details>
+
Use inline objects only when a fallback is not worth naming as a reusable preset. `fallbackModels` belongs under `agents.defaults`, not inside individual `modelPresets` entries.
Failover normally runs when the primary provider returns a fallbackable model/provider error before any answer text has been streamed. Stream-stall timeouts are the recovery exception: if the provider already emitted partial answer text and then stalls, nanobot closes the current stream segment and retries/fails over in a new segment. Typical fallback cases include timeouts, connection errors, 5xx server errors, 429 rate limits, overloads, authentication/permission failures such as invalid or expired credentials, and quota/balance exhaustion. It does not run for malformed requests, content filtering/refusals, or context-length/message-format errors.
@@ -1530,8 +1578,13 @@ If fallback candidates use smaller `contextWindowTokens` values, nanobot builds
## Transcription Settings
+Open **Settings → Capabilities → Transcription**, enable it, select a provider and model, and set the language or recording limits under **Advanced options** when needed. Add missing provider credentials through **Settings → Models**. Save and follow any restart prompt.
+
Audio transcription is a shared capability used by chat-channel voice messages and by WebUI microphone input. Chat-channel voice messages are transcribed automatically before they enter the agent. WebUI microphone input is transcribed into the composer first, so you can edit the text before sending.
+<details>
+<summary>Manual configuration</summary>
+
Configure transcription under the top-level `transcription` section:
```json
@@ -1547,11 +1600,13 @@ Configure transcription under the top-level `transcription` section:
}
```
+</details>
+
| Setting | Default | Description |
|---------|---------|-------------|
| `enabled` | `true` | Enables audio transcription for both chat-channel voice messages and WebUI microphone input. |
-| `provider` | `"groq"` | Transcription backend: `"groq"`, `"openai"`, `"openrouter"`, `"xiaomi_mimo"`, `"stepfun"`, or `"assemblyai"`. |
-| `model` | provider default | Optional transcription model override. Defaults to `whisper-large-v3` for Groq, `whisper-1` for OpenAI, `openai/whisper-1` for OpenRouter, `mimo-v2.5-asr` for Xiaomi MiMo ASR, `stepaudio-2.5-asr` for StepFun ASR, and `universal-3-pro,universal-2` for AssemblyAI. OpenRouter accepts only speech-to-text models on its transcription endpoint, such as `nvidia/parakeet-tdt-0.6b-v3`, `openai/whisper-1`, or `openai/gpt-4o-transcribe`; chat LLMs are rejected there. AssemblyAI accepts a comma-separated model fallback list. |
+| `provider` | `"groq"` | Transcription backend: `"groq"`, `"openai"`, `"openrouter"`, `"xiaomi_mimo"`, `"stepfun"`, `"assemblyai"`, or `"siliconflow"`. |
+| `model` | provider default | Optional transcription model override. Defaults to `whisper-large-v3` for Groq, `whisper-1` for OpenAI, `openai/whisper-1` for OpenRouter, `mimo-v2.5-asr` for Xiaomi MiMo ASR, `stepaudio-2.5-asr` for StepFun ASR, `universal-3-pro,universal-2` for AssemblyAI, and `FunAudioLLM/SenseVoiceSmall` for SiliconFlow. OpenRouter accepts only speech-to-text models on its transcription endpoint, such as `nvidia/parakeet-tdt-0.6b-v3`, `openai/whisper-1`, or `openai/gpt-4o-transcribe`; chat LLMs are rejected there. AssemblyAI accepts a comma-separated model fallback list. |
| `language` | `null` | Optional ISO-639 language hint, e.g. `"en"`, `"zh"`, `"ko"`, or `"ja"`. |
| `maxDurationSec` | `120` | Maximum WebUI recording duration. |
| `maxUploadMb` | `25` | Maximum WebUI audio upload size. |
@@ -1566,6 +1621,9 @@ The legacy `channels.*` transcription fields existed before transcription became
Transcription credentials are intentionally not stored in `transcription`. Put the API key and optional endpoint in the matching provider config:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -1581,13 +1639,20 @@ Transcription credentials are intentionally not stored in `transcription`. Put t
}
```
+</details>
+
Selecting a transcription provider does not configure credentials by itself. For example, the effective provider may default to Groq for compatibility, but transcription is only usable when `providers.groq.apiKey` or the matching environment-backed config is available. The Settings UI writes only the top-level `transcription` fields.
If you are adding a new transcription provider, see [`development.md`](./development.md#adding-a-transcription-provider).
## Channel Settings
-Global settings that apply to all channels. Configure under the `channels` section in `~/.nanobot/config.json`:
+Open **Channels** in the sidebar, select the chat platform, and follow its credential or QR setup. Channel-specific options are in its **Advanced** section. Global channel output settings without a graphical control remain documented directly below.
+
+Global settings apply to all channels and have no graphical controls. Configure them under the `channels` section in `~/.nanobot/config.json`:
+
+<details>
+<summary>Manual configuration</summary>
```json
{
@@ -1602,6 +1667,8 @@ Global settings that apply to all channels. Configure under the `channels` secti
}
```
+</details>
+
| Setting | Default | Description |
|---------|---------|-------------|
| `sendProgress` | `true` | Stream agent's text progress to the channel |
@@ -1681,9 +1748,14 @@ When ripgrep (`rg`) is installed, nanobot automatically uses it in place of the
## Web Tools
-nanobot incorporates basic tools for accessing the web. These include searching via APIs, and fetching arbitrary web pages in Markdown format. They are enabled by default, and can be configured in `~/.nanobot/config.json` under `tools.web`.
+Open **Settings → Capabilities → Web access** to enable or disable web tools and configure search and fetch. Use **Configure → Advanced options** for the web proxy and User-Agent, and **Settings → Advanced** for the SSRF whitelist. Follow any restart prompt.
+
+nanobot includes web search and web fetch tools. They are enabled by default. The collapsed examples below show the equivalent `tools.web` configuration.
-If you want to disable them, which removes both `web_search` and `web_fetch` from the tool list sent to the LLM, set `tools.web.enable` to `false`:
+Turn off **Web access** in **Settings → Capabilities** to remove both `web_search` and `web_fetch` from the tool list sent to the model. The manual equivalent is:
+
+<details>
+<summary>Manual configuration</summary>
```json
{
@@ -1695,8 +1767,13 @@ If you want to disable them, which removes both `web_search` and `web_fetch` fro
}
```
+</details>
+
nanobot uses a shared SSRF guard for built-in web fetches and HTTP/SSE MCP connections. By default it blocks loopback, RFC1918/private ranges, CGNAT/Tailscale ranges, link-local addresses, and cloud metadata endpoints. If you need to allow trusted private ranges, explicitly exempt them from SSRF blocking with `tools.ssrfWhitelist`:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -1705,22 +1782,24 @@ nanobot uses a shared SSRF guard for built-in web fetches and HTTP/SSE MCP conne
}
```
-Keep whitelist entries as narrow as possible, such as a single host CIDR (`192.168.1.50/32`). The whitelist is global for the shared SSRF guard; it is not limited to one tool or one MCP server.
+</details>
+
+Keep whitelist entries as narrow as possible, such as a single host CIDR (`192.168.1.50/32`). The whitelist is global for the shared SSRF guard; it is not limited to one tool or one MCP server. This guard does not filter network traffic from shell commands or stdio MCP processes. The shell sandboxes also allow network access; use host or container egress controls when you need to prevent outbound connections.
HTTP/SSE MCP connections use the same process-wide proxy environment behavior as `web_fetch`: proxied targets use the configured proxy, and URLs excluded by `NO_PROXY` remain DNS-pinned direct connections.
-In WebUI, open **Settings → Capabilities → Web access → Configure → Advanced options**
-to set the web proxy. This setting applies to the agent's web search and page reading,
-not model providers, MCP, or your browser. `127.0.0.1` refers to the machine that runs
-nanobot, not the phone or computer that opens WebUI. Clear the field to use the default
-network settings, which can include proxy environment variables. After saving, restart
-nanobot when WebUI requests it. You can configure the proxy before enabling web access.
+In WebUI, open **Settings → Capabilities → Web access → Configure → Advanced options** to set the web proxy. This setting applies to the agent's web search and page reading, not model providers, MCP, or your browser. `127.0.0.1` refers to the machine that runs nanobot, not the phone or computer that opens WebUI. Clear the field to use the default network settings, which can include proxy environment variables. After saving, restart nanobot when WebUI requests it. You can configure the proxy before enabling web access.
> [!TIP]
> Use `proxy` in `tools.web` to route web requests through a proxy:
+> <details>
+> <summary>Manual configuration</summary>
+>
> ```json
> { "tools": { "web": { "proxy": "http://127.0.0.1:7890" } } }
> ```
+>
+> </details>
> `web_fetch` applies DNS pinning for direct connections. When an explicit `tools.web.proxy` or a process-wide proxy environment variable applies to the target URL, nanobot still validates the requested URL locally, but DNS resolution for the outbound fetch happens at the proxy; configure only trusted proxies. URLs excluded by `NO_PROXY` keep the DNS-pinned direct path unless `tools.web.proxy` is configured.
### `tools.web`
@@ -1733,7 +1812,9 @@ nanobot when WebUI requests it. You can configure the proxy before enabling web
### Web Search
-nanobot supports multiple web search providers. Configure in `~/.nanobot/config.json` under `tools.web.search`.
+In **Settings → Capabilities → Web access**, choose the search provider, enter its key or base URL when required, and set the result limit. Save and ask a question requiring current information.
+
+nanobot supports multiple web search providers. Select one in the WebUI as described above; the collapsed examples show the equivalent `tools.web.search` configuration.
By default, web search uses `duckduckgo`, and it works out of the box without an API key.
@@ -1751,6 +1832,9 @@ By default, web search uses `duckduckgo`, and it works out of the box without an
| `duckduckgo` (default) | — | — | Yes |
**Brave:**
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -1764,7 +1848,12 @@ By default, web search uses `duckduckgo`, and it works out of the box without an
}
```
+</details>
+
**Tavily:**
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -1778,7 +1867,12 @@ By default, web search uses `duckduckgo`, and it works out of the box without an
}
```
+</details>
+
**Jina** (free tier with 10M tokens):
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -1792,7 +1886,12 @@ By default, web search uses `duckduckgo`, and it works out of the box without an
}
```
+</details>
+
**Kagi:**
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -1806,7 +1905,12 @@ By default, web search uses `duckduckgo`, and it works out of the box without an
}
```
+</details>
+
**Olostep:**
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -1820,9 +1924,14 @@ By default, web search uses `duckduckgo`, and it works out of the box without an
}
```
+</details>
+
You can also set `OLOSTEP_API_KEY` in the environment instead of storing it in config.
**Bocha** (AI-optimized search, free tier available):
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -1836,9 +1945,14 @@ You can also set `OLOSTEP_API_KEY` in the environment instead of storing it in c
}
```
+</details>
+
Create your API key at [open.bochaai.com](https://open.bochaai.com). Bocha returns structured results optimized for AI consumption, with optional summaries. You can set `BOCHA_API_KEY` in the environment instead of storing it in config.
**Volcengine Search:**
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -1852,9 +1966,14 @@ Create your API key at [open.bochaai.com](https://open.bochaai.com). Bocha retur
}
```
+</details>
+
You can also set `WEB_SEARCH_API_KEY` for compatibility with the Volcengine web-search skill. Create the key in the [Volcengine web search console](https://console.volcengine.com/search-infinity/web-search), then copy it from [API keys](https://console.volcengine.com/search-infinity/api-key). Volcengine Ark keys are separate and do not work for this search provider.
**Keenable** (works without an API key on the free tier):
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -1867,9 +1986,14 @@ You can also set `WEB_SEARCH_API_KEY` for compatibility with the Volcengine web-
}
```
+</details>
+
Keenable search works out of the box with no account, via its token-less public endpoint (free tier, limited to 1,000 requests/hour). Set `apiKey` (or `KEENABLE_API_KEY`) from [keenable.ai](https://keenable.ai) to remove the hourly limit.
**Serper** (Google Search API):
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -1883,9 +2007,14 @@ Keenable search works out of the box with no account, via its token-less public
}
```
+</details>
+
Create a key at [serper.dev](https://serper.dev). You can also set `SERPER_API_KEY` in the environment instead of storing it in config.
**SearXNG** (self-hosted, no API key needed):
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -1899,7 +2028,12 @@ Create a key at [serper.dev](https://serper.dev). You can also set `SERPER_API_K
}
```
+</details>
+
**DuckDuckGo** (zero config):
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -1912,7 +2046,12 @@ Create a key at [serper.dev](https://serper.dev). You can also set `SERPER_API_K
}
```
+</details>
+
**AnySearch** (key-optional, anonymous quota):
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -1925,6 +2064,8 @@ Create a key at [serper.dev](https://serper.dev). You can also set `SERPER_API_K
}
```
+</details>
+
AnySearch works out of the box with no key, via its anonymous quota (lower rate limits). Set `apiKey` (or `ANYSEARCH_API_KEY`) from [anysearch.com](https://anysearch.com/console/api-keys) to lift rate limits. It also offers vertical-domain search and full-page URL content extraction.
#### `tools.web.search`
@@ -1938,18 +2079,28 @@ AnySearch works out of the box with no key, via its anonymous quota (lower rate
### Web Fetch
+In **Settings → Capabilities → Web access**, expand the fetch options and choose whether to use Jina Reader. Save the change; use **Configure → Advanced options** in the same Web access card for network proxy settings.
+
> [!TIP]
> If you are having issues with JS proof-of-work or Cloudflare captchas, set a random user agent and disable Jina Reader:
+> <details>
+> <summary>Manual configuration</summary>
+>
> ```json
> { "tools": { "web": { "userAgent": "Not-A-Browser", "fetch": { "useJinaReader": false } } } }
> ```
+>
+> </details>
nanobot by default uses [Jina Reader](https://jina.ai/reader/), a third-party API, to convert arbitrary pages into Markdown format for easy digestion by the LLM, with a local fallback based on [readability-lxml](https://github.com/buriy/python-readability) if the former fails.
> [!NOTE]
> Using the remote reader means the fetched URL itself is disclosed to the third-party service. URLs that visibly carry credentials (userinfo, signed-URL or token-style query parameters) are detected and fetched locally instead, but secrets embedded in a URL's *path* (for example bot-token or webhook-style URLs) cannot be reliably detected. Set `useJinaReader: false` if fetched URLs must never leave the machine.
-If you want to always use the local conversion, you can force it using:
+To always use local conversion, turn off **Jina Reader** in the Web access settings. The manual equivalent is:
+
+<details>
+<summary>Manual configuration</summary>
```json
{
@@ -1963,6 +2114,8 @@ If you want to always use the local conversion, you can force it using:
}
```
+</details>
+
#### `tools.web.fetch`
| Option | Type | Default | Description |
@@ -1977,12 +2130,17 @@ See [Image Generation](./image-generation.md) for WebUI usage, provider examples
## MCP (Model Context Protocol)
+Open **Apps → MCP**, choose a preset or **Add MCP server**, and enter the stdio command or HTTP/SSE endpoint. Configure authentication and enabled tools in the server editor, save, and follow any connection or restart prompt.
+
> [!TIP]
> The config format is compatible with Claude Desktop / Cursor. You can copy MCP server configs directly from any MCP server's README.
nanobot supports [MCP](https://modelcontextprotocol.io/) — connect external tool servers and use them as native agent tools.
-Add MCP servers to your `config.json`:
+For headless or deployment-managed setup, expand the manual configuration below:
+
+<details>
+<summary>Manual configuration</summary>
```json
{
@@ -2003,6 +2161,8 @@ Add MCP servers to your `config.json`:
}
```
+</details>
+
MCP servers can run locally over stdio or connect remotely over HTTP:
| Connection | Config | Example |
@@ -2012,6 +2172,9 @@ MCP servers can run locally over stdio or connect remotely over HTTP:
Remote HTTP servers may use browser OAuth instead of static headers. In the WebUI, open **Apps → MCP → Add MCP server**, choose **Custom**, select HTTP or SSE, and choose **OAuth** under **Authentication**. Save the server, then choose **Connect**. For manual configuration, add `auth: "oauth"` and open **Apps → MCP** to connect. Known presets such as Xmind, Notion, and Linear add the config automatically on first click.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -2026,6 +2189,8 @@ Remote HTTP servers may use browser OAuth instead of static headers. In the WebU
}
```
+</details>
+
nanobot opens the server's authorization page and handles the callback through the gateway. The tools become available immediately when hot reload succeeds; otherwise the WebUI asks for a restart. OAuth tokens and dynamic client registration data are stored in the nanobot data directory under `auth/mcp.json`; they are not written to `config.json`. Removing the MCP server from Apps also removes its saved OAuth credentials. Normal gateway startup never opens a browser or registers a new OAuth client when credentials are missing—interactive authorization starts only after a user clicks **Connect**.
For a remotely accessed WebUI, HTTPS is recommended. Configure `channels.websocket.publicWsUrl` with the browser-facing `wss://` endpoint so nanobot can register the matching HTTPS callback and finish automatically. A loopback WebUI may use HTTP. When a remote WebUI is served over plain HTTP, nanobot instead registers a localhost callback and asks you to paste the complete callback URL from the browser address bar after authorization.
@@ -2035,6 +2200,9 @@ For a remotely accessed WebUI, HTTPS is recommended. Configure `channels.websock
Use `toolTimeout` to override the default 30s per-call timeout for slow servers:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -2048,8 +2216,13 @@ Use `toolTimeout` to override the default 30s per-call timeout for slow servers:
}
```
+</details>
+
Use `enabledTools` to register only a subset of tools from an MCP server:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -2064,6 +2237,8 @@ Use `enabledTools` to register only a subset of tools from an MCP server:
}
```
+</details>
+
`enabledTools` accepts either the raw MCP tool name (for example `read_file`) or the wrapped nanobot tool name (for example `mcp_filesystem_write_file`).
- Omit `enabledTools`, or set it to `["*"]`, to register all capabilities (tools, resources, and prompts).
@@ -2077,6 +2252,8 @@ MCP tools are automatically discovered and registered on startup. The LLM can us
## Security
+Open **Settings → Advanced** for workspace restriction, shell sandbox settings, SSRF exceptions, and remote package installation. Choose the narrowest access needed and follow any restart prompt. Use **Channels** for each chat platform's access controls.
+
> [!TIP]
> For production deployments, set both `"restrictToWorkspace": true` and `"tools.exec.sandbox"` (`"bwrap"` on Linux, `"seatbelt"` on macOS) in your config. `restrictToWorkspace` enables nanobot's application-level workspace guards; `tools.exec.sandbox` provides process-level isolation for shell commands.
@@ -2098,26 +2275,11 @@ For API keys, tokens, and other secrets, see [Environment Variables for Secrets]
| `tools.exec.sandboxRwBinds` | `[]` | Extra absolute paths to expose read-write inside the exec sandbox (`--bind-try` for `"bwrap"`, an SBPL `file-read* file-write*` rule for `"seatbelt"`), for trusted tool caches or scratch directories. Use sparingly: paths listed here are intentionally writable by shell commands inside the sandbox. Paths equal to or containing the active workspace are ignored. |
| `tools.webuiAllowRemotePackageInstall` | `false` | When `false`, the WebUI can install missing optional packages only from a browser opened on the same machine as nanobot. Set to `true` only when a trusted remote admin is allowed to install Python packages into this nanobot environment. |
| `tools.ssrfWhitelist` | `[]` | CIDR ranges exempted from the shared SSRF guard used by web fetches and HTTP/SSE MCP connections. Prefer exact host CIDRs such as `192.168.1.50/32`; broad ranges increase SSRF exposure. |
-| `channels.*.allowFrom` | omitted | Access control per channel. Omit to use pairing-only mode; set `["*"]` to allow everyone; or list specific user IDs. See [Pairing](#pairing) for details. |
-
-Each new user request includes the current project and file-access restriction in model-only
-context. This uses the same policy resolver as the tools, including restrictions from
-a configured exec sandbox. It does not grant access or change OS permissions.
-The context is stored with that request, not rewritten in earlier messages. New requests
-refresh it after a project switch or context compaction. It is hidden from the chat view.
-This adds a small amount of input text per user request. Tool continuations and transient
-retries reuse the stored context; they do not add another copy. Access-mode changes do not
-rewrite the system prompt, tool definitions, or previous messages. Changing the project or
-compacting history can change the prompt prefix. Cache hits still depend on the provider.
-
-To diagnose a path error, the agent can call `my(action="check", key="workspace_sandbox")`.
-This read-only result shows the current tool directory and workspace restriction, including
-the restriction from `tools.exec.sandbox`. The older `workspace` value is an agent-directory
-display; it does not select the current project or grant access.
-Check `exec_config` for the configured shell sandbox and extra binds. Those binds do not grant
-file-tool access or permit an external shell `working_dir`. OS file permissions still apply.
-The `workspace_sandbox.enforced` field reports external sandbox markers, not whether a
-configured shell sandbox has started successfully.
+| `channels.*.allowFrom` | omitted | For channels using the common sender allowlist, omit to require pairing, set `["*"]` to allow everyone, or list specific user IDs. Slack and Mattermost instead use `dm.policy` / `dm.allowFrom` for DMs and default to open DMs; review their group policy separately. See [Pairing](#pairing). |
+
+Each new user request includes the current project and file-access restriction in model-only context. This uses the same policy resolver as the tools, including restrictions from a configured exec sandbox. It does not grant access or change OS permissions. The context is stored with that request, not rewritten in earlier messages. New requests refresh it after a project switch or context compaction. It is hidden from the chat view. This adds a small amount of input text per user request. Tool continuations and transient retries reuse the stored context; they do not add another copy. Access-mode changes do not rewrite the system prompt, tool definitions, or previous messages. Changing the project or compacting history can change the prompt prefix. Cache hits still depend on the provider.
+
+To diagnose a path error, the agent can call `my(action="check", key="workspace_sandbox")`. This read-only result shows the current tool directory and workspace restriction, including the restriction from `tools.exec.sandbox`. The older `workspace` value is an agent-directory display; it does not select the current project or grant access. Check `exec_config` for the configured shell sandbox and extra binds. Those binds do not grant file-tool access or permit an external shell `working_dir`. OS file permissions still apply. The `workspace_sandbox.enforced` field reports external sandbox markers, not whether a configured shell sandbox has started successfully.
**Docker security**: The official Docker image runs as a non-root user (`nanobot`, UID 1000) with bubblewrap pre-installed. The default `docker-compose.yml` drops all Linux capabilities except the `CHOWN`, `SETGID`, and `SETUID` capabilities required by the root entrypoint to initialize bind-mount ownership and become UID 1000. It enables `no-new-privileges` so the final non-root process cannot regain those bootstrap capabilities, and keeps Docker's default AppArmor/seccomp profiles enabled. If you enable `"tools.exec.sandbox": "bwrap"` inside Docker, start Compose with `docker-compose.bwrap.yml` as an additional override so bubblewrap can create nested namespaces. The host must also allow unprivileged user namespaces; the override cannot bypass a host-level namespace restriction.
@@ -2138,11 +2300,14 @@ Pairing lets users get access to the bot through a simple code exchange — no c
4. The user can now chat with the bot normally.
-Pairing only works in **DMs** — unapproved users in group chats are silently ignored.
+Pairing codes are issued only in **DMs**. Channels using the common sender allowlist, such as Telegram and Discord, also reject unapproved group senders unless a configured allowlist already permits them. Slack and Mattermost authorize groups independently of DM approval: `groupPolicy: "mention"` allows channel members to invoke the bot by mentioning it. Use `groupPolicy: "allowlist"` with an empty `groupAllowFrom` for DM-only access, or list only the intended channel IDs. Approval of one DM user does not restrict those groups to that user.
### Pairing-only mode
-By default, if you don't set `allowFrom`, pairing-capable channels can issue a pairing code when an unapproved user DMs the bot. This means you can skip `allowFrom` entirely and manage access through pairing:
+For channels using the common sender allowlist, such as Telegram and Discord, omitting `allowFrom` requires approval and lets an unapproved user request a pairing code by DM. Slack and Mattermost are exceptions: their DMs default to open access, as described below. For Telegram, you can omit `allowFrom` and manage access through pairing:
+
+<details>
+<summary>Manual configuration</summary>
```json
{
@@ -2154,8 +2319,13 @@ By default, if you don't set `allowFrom`, pairing-capable channels can issue a p
}
```
+</details>
+
Slack and Mattermost DMs are open by default. To use pairing there, set the channel's `dm.policy` to `"allowlist"` and leave `dm.allowFrom` empty until you approve users:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"channels": {
@@ -2167,8 +2337,13 @@ Slack and Mattermost DMs are open by default. To use pairing there, set the chan
}
```
+</details>
+
If you prefer to allow everyone without approval:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"channels": {
@@ -2180,6 +2355,8 @@ If you prefer to allow everyone without approval:
}
```
+</details>
+
### Managing access
| Command | What it does |
@@ -2202,6 +2379,8 @@ nanobot agent -m "/pairing approve ABCD-EFGH"
## Gateway Heartbeat
+The WebUI has no control for heartbeat registration or its interval. Configure these fields directly in `config.json` and restart the gateway.
+
The gateway can run a protected heartbeat cron job that periodically checks `HEARTBEAT.md` in the active workspace. This is enabled by default when you run `nanobot gateway`.
```json
@@ -2209,8 +2388,7 @@ The gateway can run a protected heartbeat cron job that periodically checks `HEA
"gateway": {
"heartbeat": {
"enabled": true,
- "intervalS": 1800,
- "keepRecentMessages": 8
+ "intervalS": 1800
}
}
}
@@ -2226,7 +2404,6 @@ The heartbeat job is backed by the same cron service as user-created reminders.
|--------|---------|-------------|
| `gateway.heartbeat.enabled` | `true` | Register the built-in heartbeat cron job on gateway startup. |
| `gateway.heartbeat.intervalS` | `1800` | Seconds between heartbeat checks. |
-| `gateway.heartbeat.keepRecentMessages` | `8` | Number of recent heartbeat-session messages to retain after each run. |
| `gateway.restartMode` | `auto` | Restart strategy for `/restart`: `auto` uses `spawn` on Windows foreground runs and `exec` elsewhere. Use `exit` with Windows service wrappers such as WinSW or nssm so the service manager owns the restart. |
### Custom heartbeat evaluator prompt
@@ -2236,8 +2413,13 @@ The notification gate runs on a built-in system prompt. Advanced users can overr
## Subagent Concurrency
+Open **Settings → Advanced** and change **Concurrent subagents** under **Run limits**. Follow any restart prompt.
+
By default, nanobot allows four subagents to run at the same time. Additional subagents wait for capacity instead of being rejected. Lower the limit if a local model server cannot hold multiple KV caches, or raise it when the provider can handle more parallel work:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"agents": {
@@ -2248,6 +2430,8 @@ By default, nanobot allows four subagents to run at the same time. Additional su
}
```
+</details>
+
The deprecated `agents.defaults.failOnToolError` field is silently ignored when present in older configs.
| Option | Default | Description |
@@ -2257,6 +2441,8 @@ The deprecated `agents.defaults.failOnToolError` field is silently ignored when
## Auto Compact
+The WebUI has no control for the idle-compaction threshold or scan interval. Configure these fields directly in `config.json`; use `/compact` for an immediate compaction.
+
When a session is idle for longer than a configured threshold, nanobot summarizes its conversation context. When you return, the model receives that summary and new messages instead of replaying the messages covered by the summary. The original conversation remains in your saved chat history, but even its most recent messages are no longer included verbatim in the model's context after idle compaction.
```json
@@ -2290,21 +2476,31 @@ Use `/compact` in chat to compact the current session without waiting for the id
## Timezone
+Open **Settings → System → Timezone**. Keep **System timezone** on to follow the host, or turn it off and choose a fixed IANA timezone. Follow any restart prompt.
+
Time is context. Context should be precise.
-By default, nanobot uses `UTC` for runtime time context. If you want the agent to think in your local time, set `agents.defaults.timezone` to a valid [IANA timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones):
+New configurations use `agents.defaults.timezoneMode: "auto"`: nanobot detects the host's IANA timezone when loading the config and falls back to `UTC` if detection fails. To use a fixed timezone, set `timezoneMode` to `"manual"` and `timezone` to a valid [IANA timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones):
+
+<details>
+<summary>Manual configuration</summary>
```json
{
"agents": {
"defaults": {
+ "timezoneMode": "manual",
"timezone": "Asia/Shanghai"
}
}
}
```
-This affects runtime time strings shown to the model, such as runtime context. It also becomes the default timezone for cron schedules when a cron expression omits `tz`, and for one-shot `at` times when the ISO datetime has no explicit offset.
+</details>
+
+In `"auto"` mode, the detected timezone overrides the stored `timezone` value. Older configs with an explicit `timezone` but no `timezoneMode` are treated as `"manual"`, preserving their configured timezone.
+
+The effective timezone affects runtime time strings shown to the model, such as runtime context. It also becomes the default timezone for cron schedules when a cron expression omits `tz`, and for one-shot `at` times when the ISO datetime has no explicit offset.
Common examples: `UTC`, `America/New_York`, `America/Los_Angeles`, `Europe/London`, `Europe/Berlin`, `Asia/Tokyo`, `Asia/Shanghai`, `Asia/Singapore`, `Australia/Sydney`.
@@ -2312,8 +2508,13 @@ Common examples: `UTC`, `America/New_York`, `America/Los_Angeles`, `Europe/Londo
## Unified Session
+Open **Settings → System** and change **Shared sessions**. Enable it only for a single-user setup where conversations should share context. Follow any restart prompt.
+
By default, each channel × chat ID combination gets its own session. If you use nanobot across multiple channels (e.g. Telegram + Discord + CLI) and want them to share the same conversation, enable `unifiedSession`:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"agents": {
@@ -2324,6 +2525,8 @@ By default, each channel × chat ID combination gets its own session. If you use
}
```
+</details>
+
When enabled, all incoming messages — regardless of which channel they arrive on — are routed into a single shared session. Switching from Telegram to Discord (or any other channel) continues the same conversation seamlessly.
| Behavior | `false` (default) | `true` |
@@ -2338,8 +2541,13 @@ When enabled, all incoming messages — regardless of which channel they arrive
## Disabled Skills
+Open **Skills** in the sidebar, find the installed skill, and turn its switch off or on. This controls whether the agent can load it without deleting its files.
+
nanobot ships with built-in skills, and your workspace can also define custom skills under `skills/`. If you want to hide specific skills from the agent, set `agents.defaults.disabledSkills` to a list of skill directory names:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"agents": {
@@ -2350,6 +2558,8 @@ nanobot ships with built-in skills, and your workspace can also define custom sk
}
```
+</details>
+
Disabled skills are excluded from the main agent's skill summary, from always-on skill injection, and from subagent skill summaries. This is useful when some bundled skills are unnecessary for your deployment or should not be exposed to end users.
| Option | Default | Description |
@@ -2368,10 +2578,15 @@ CLI Apps use the same skills-only package layout while their installer manages e
## Tool Hint Max Length
+Open **Settings → Advanced** and change **Summary length** under **Run limits**. Follow any restart prompt.
+
Tool hints are the short progress messages shown when the agent calls tools (e.g. `$ cd …/project && npm test`). By default, these are truncated at 40 characters, which can make long commands hard to read.
Set `agents.defaults.toolHintMaxLength` to control the truncation threshold:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"agents": {
@@ -2382,6 +2597,8 @@ Set `agents.defaults.toolHintMaxLength` to control the truncation threshold:
}
```
+</details>
+
| Option | Default | Description |
|--------|---------|-------------|
| `agents.defaults.toolHintMaxLength` | `40` | Maximum characters for tool hint display. Range: 20–500. Higher values show more of the command or path; lower values keep hints compact. |
diff --git a/docs/deployment.md b/docs/deployment.md
index 7e8e9eccf..0c5129c88 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -1,10 +1,10 @@
# Deployment
-Use this page after `nanobot agent -m "Hello!"` works locally. Deployment keeps long-running surfaces online: WebUI, chat apps, heartbeat, Dream, cron jobs, and channel connections.
+Use this page to keep an already working agent online, or start with the [Docker setup](#docker-compose) on a new headless host. A normal WebUI reply is sufficient to confirm an existing model setup; a CLI check is useful for terminal and container deployments. Deployment keeps long-running surfaces online: WebUI, chat apps, heartbeat, Dream, cron jobs, and channel connections.
## Before You Deploy
-Check these once before Render, Docker, systemd, or LaunchAgent:
+Check these before making a deployment persistent. For a new container host, perform them inside the container after the initialization steps below:
| Check | Why it matters |
|---|---|
@@ -109,6 +109,20 @@ Set `publicWsUrl` to the browser-facing `wss://` endpoint when the tunnel sends
### Docker Compose
+On a new Linux host, install Git and Docker with the Compose plugin, then get the repository. No host Python or host `nanobot` installation is required:
+
+```bash
+git clone https://github.com/HKUDS/nanobot.git
+cd nanobot
+docker compose build
+docker compose run --rm nanobot-cli onboard
+```
+
+The last command initializes `~/.nanobot/config.json` and the workspace in the bind mount. Skip it when reusing an existing configuration. Edit that file on the host and merge your provider settings from [provider setup](./providers.md); select the provider/model you can access, either through the documented model preset or direct `agents.defaults.provider` and `agents.defaults.model` settings. Keep `agents.defaults.workspace` as a container path, normally `~/.nanobot/workspace` (resolved inside the container), rather than a host home-directory path.
+
+Also merge the Docker bind and authentication settings [above](#docker): `gateway.host` and `channels.websocket.host` must be `0.0.0.0`, and `tokenIssueSecret` must be a private random value. These snippets are partial configuration, not replacements for your provider settings. Config `${VAR}` references require those variables inside every CLI and gateway container; Compose does not forward arbitrary host variables automatically. Either add the necessary `environment` entries to the services or keep credentials in the protected config file.
+
+
The default image preinstalls WhatsApp dependencies. To bake other enabled channels into an image (recommended for deployments without PyPI access), pass a comma-separated `NANOBOT_CHANNELS` build argument:
```bash
@@ -118,9 +132,11 @@ NANOBOT_CHANNELS=telegram,slack docker compose build
The image keeps nanobot in a virtual environment owned by its built-in non-root runtime user (UID 1000). If an enabled channel was not preinstalled, gateway startup can therefore install its manifest-declared dependencies. Rebuilding with `NANOBOT_CHANNELS` keeps that installation reproducible instead of relying on the container's writable layer. If you override the container with a different `--user`, bake every enabled channel into the image because that UID is not guaranteed write access to the virtual environment.
```bash
-docker compose run --rm nanobot-cli onboard # first-time setup
-vim ~/.nanobot/config.json # add API keys
-docker compose up -d nanobot-gateway # start gateway
+docker compose run --rm nanobot-cli status
+docker compose run --rm nanobot-cli agent -m "Hello!"
+# Continue only after a normal reply.
+docker compose up -d nanobot-gateway
+curl --fail http://127.0.0.1:18790/health
```
```bash
@@ -129,6 +145,8 @@ docker compose logs -f nanobot-gateway # view logs
docker compose down # stop
```
+Open `http://HOST:8765` and enter the configured `tokenIssueSecret` when prompted. For a remote host, allow access only from the intended network or use an SSH tunnel (`ssh -L 8765:127.0.0.1:8765 user@HOST`) and open `http://127.0.0.1:8765` locally. The health check confirms the process is reachable; send a browser message to verify the model and WebUI together.
+
The default Compose file drops all Linux capabilities except `CHOWN`, `SETUID`, and `SETGID`, which the root entrypoint needs to fix bind-mount ownership and become UID 1000. It also enables `no-new-privileges`, so the non-root process cannot regain those bootstrap capabilities through setuid binaries or file capabilities. Docker's default AppArmor/seccomp profiles remain enabled. If you explicitly set `"tools.exec.sandbox": "bwrap"` in `~/.nanobot/config.json`, add the bwrap override file when starting containers:
```bash
@@ -153,9 +171,13 @@ docker build --build-arg NANOBOT_CHANNELS=telegram,slack -t nanobot .
# Initialize config (first time only)
docker run -v ~/.nanobot:/home/nanobot/.nanobot --rm nanobot onboard
-# Edit config on host to add API keys
+# Merge model/provider and Docker bind/auth settings as described above.
vim ~/.nanobot/config.json
+# Verify the configuration and model before running the persistent gateway.
+docker run -v ~/.nanobot:/home/nanobot/.nanobot --rm nanobot status
+docker run -v ~/.nanobot:/home/nanobot/.nanobot --rm nanobot agent -m "Hello!"
+
# Run gateway (connects to enabled channels, e.g. Telegram/Discord/Mochat).
# `-p 8765:8765` exposes the WebSocket channel / WebUI alongside the gateway
# health endpoint on 18790.
@@ -164,7 +186,7 @@ docker run \
--cap-add CHOWN --cap-add SETGID --cap-add SETUID \
--security-opt no-new-privileges:true \
-v ~/.nanobot:/home/nanobot/.nanobot \
- -p 18790:18790 -p 8765:8765 \
+ -p 127.0.0.1:18790:18790 -p 8765:8765 \
nanobot gateway
# If `tools.exec.sandbox: "bwrap"` is enabled, run with the extra permissions
@@ -185,9 +207,15 @@ docker run -v ~/.nanobot:/home/nanobot/.nanobot --rm nanobot agent -m "Hello!"
docker run -v ~/.nanobot:/home/nanobot/.nanobot --rm nanobot status
```
+## Switch an Existing Gateway to a Service
+
+Before installing an OS service, finish active work and close WebUI/TUI launchers that could start another gateway. Stop the existing instance: use `nanobot gateway stop` for a recorded background gateway (including one retained by `/detach`), or Ctrl+C in the terminal running a foreground gateway. Pass the same `--config` and `--workspace` selectors to stop, status, and service-install commands for a custom instance.
+
+The service installer does not take over an existing standalone process. Starting both on the same ports makes the new service fail. If an OS service already owns the instance, manage it with its service manager instead of launching another process.
+
## Linux Service
-Run the gateway as a systemd user service so it starts automatically and restarts on failure.
+Run the gateway as a systemd user service so it starts automatically and restarts on failure. Complete the [existing-gateway handoff](#switch-an-existing-gateway-to-a-service) first if an instance is already running.
Preview the generated unit first:
@@ -230,7 +258,7 @@ The installer writes `~/.config/systemd/user/nanobot-gateway.service`, runs `sys
## macOS LaunchAgent
-Use a LaunchAgent when you want `nanobot gateway` to stay online after you log in, without keeping a terminal open.
+Use a LaunchAgent when you want `nanobot gateway` to stay online after you log in, without keeping a terminal open. Complete the [existing-gateway handoff](#switch-an-existing-gateway-to-a-service) first if an instance is already running.
Preview the generated plist first:
diff --git a/docs/development.md b/docs/development.md
index f746bd4cb..ef6cdde8f 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -2,6 +2,8 @@
This page collects contributor-facing notes for extending nanobot. User-facing setup and runtime options live in [`configuration.md`](./configuration.md).
+For browser interface changes, start with [WebUI development](../webui/README.md). For Python setup and contribution checks, see [CONTRIBUTING.md](../CONTRIBUTING.md). The sections below cover provider extensions.
+
## Adding an LLM Provider
nanobot uses the provider registry in `nanobot/providers/registry.py` as the source of truth for LLM provider metadata. Most OpenAI-compatible providers need only two changes.
diff --git a/docs/guides/README.md b/docs/guides/README.md
index 8bc53bb6b..a4a9b4b84 100644
--- a/docs/guides/README.md
+++ b/docs/guides/README.md
@@ -2,6 +2,8 @@
Start with [Install and Quick Start](../quick-start.md) and get one reply before using a guide below. Each guide targets one outcome; linked reference pages hold the complete option tables and edge cases.
+You can ask nanobot to guide your next task using the built-in `nanobot-document` skill, or read a guide yourself. See [Continue with nanobot](../quick-start.md#continue-with-nanobot) for availability and examples. Each task guide describes its starting requirements, setup steps, and how to check the result; use the parts that match your current instance.
+
## Start and Use
| Goal | Guide |
@@ -14,7 +16,7 @@ Start with [Install and Quick Start](../quick-start.md) and get one reply before
## Connect a Chat App
-Use **Settings → Channels** in the WebUI for guided setup. These guides explain the account, bot, token, permission, and test-message steps on each platform.
+Use **Channels** in the WebUI for guided setup. These guides explain the account, bot, token, permission, and test-message steps on each platform.
| Goal | Guide |
|---|---|
diff --git a/docs/guides/ai-agent-memory.md b/docs/guides/ai-agent-memory.md
index c22861306..f148842b3 100644
--- a/docs/guides/ai-agent-memory.md
+++ b/docs/guides/ai-agent-memory.md
@@ -13,33 +13,27 @@ This guide explains how to use nanobot's long-term AI agent memory: session hist
Use memory when an agent should remember stable preferences, project facts, decisions, and recurring context across sessions. Do not use memory as a dumping ground for every raw transcript; nanobot separates short-term messages from curated durable knowledge.
-## Install
+## Before you start
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-nanobot agent -m "Hello!"
-```
+Use an installation with a configured model that has already returned a reply. If this is your first setup, follow [Quick Start](../quick-start.md), then return here. Existing WebUI users can continue in the current instance.
## Minimal working example
-Ask the agent to remember a stable fact in a normal session, then run Dream:
+In your existing chat, send a specific preference, such as “For Acme release notes, use concise bullet points.” Then send these commands one at a time, waiting for each to finish:
```text
+/compact
/dream
-```
-
-Inspect recent memory changes:
-
-```text
/dream-log
```
-The exact files live in the active workspace, usually under `~/.nanobot/workspace/`.
+Compaction puts recent conversation into the archive Dream reads. Dream then decides what to save; inspect its changes to confirm the preference reached `USER.md` or `memory/MEMORY.md`. Ask the agent to read the saved preference, then check it in a new chat. For corrections and restoration, follow [Save and Check a Preference](../memory.md#save-and-check-a-preference).
+
+The files live in the configured agent workspace, normally `~/.nanobot/workspace/`. Selecting a project or starting a new topic does not move or isolate this memory.
## Production notes
-- Use one workspace per project or personal context.
+- Use separate configured instances when projects or clients need separate memory.
- Keep durable facts concise; old session details belong in `history.jsonl`.
- Use `/dream-prompt init` when a workspace needs custom memory guidance.
- Review Git-backed memory changes when memory affects important workflows.
@@ -52,9 +46,9 @@ The exact files live in the active workspace, usually under `~/.nanobot/workspac
## Troubleshooting
-- If memory feels stale, run `/dream` and inspect `/dream-log`.
+- If a recent preference is missing, run `/compact`, wait for completion, then run `/dream` and inspect `/dream-log`.
- If memory changed incorrectly, use `/dream-restore` to inspect and restore previous versions.
-- If a new session lacks context, confirm it uses the same workspace.
+- If a new session lacks context, confirm the fact was saved and it uses the same configured agent workspace.
## Related nanobot docs
diff --git a/docs/guides/ai-agent-webui.md b/docs/guides/ai-agent-webui.md
index 327b7bb7c..0bf72c6fc 100644
--- a/docs/guides/ai-agent-webui.md
+++ b/docs/guides/ai-agent-webui.md
@@ -13,13 +13,9 @@ nanobot includes a browser WebUI for persistent chat sessions, visible agent act
Use the WebUI when you want a local AI agent interface that is easier to operate than a terminal, especially for project work, file attachments, model switching, workspace selection, Apps, Skills, and scheduled automations.
-## Install
+## Before you start
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-nanobot agent -m "Hello!"
-```
+Complete [Quick Start](../quick-start.md) if nanobot is not installed or cannot reply yet. If you already have a working WebUI or CLI session, continue here using that instance; no reinstall or second gateway is needed.
The published wheel already includes the WebUI bundle. You only need the `webui/` source directory when changing the frontend.
diff --git a/docs/guides/build-a-personal-ai-agent.md b/docs/guides/build-a-personal-ai-agent.md
index c32578714..cc982c4df 100644
--- a/docs/guides/build-a-personal-ai-agent.md
+++ b/docs/guides/build-a-personal-ai-agent.md
@@ -19,23 +19,11 @@ Follow [Quick Start](../quick-start.md) to install nanobot using the recommended
## Minimal working example
-First prove the runtime can answer:
-
-```bash
-nanobot agent -m "Hello!"
-```
-
-Then open the browser workbench:
-
-```bash
-nanobot webui
-```
-
-The WebUI starts the local gateway, opens a browser, and keeps persistent chat sessions for longer work.
+Continue in the WebUI from Quick Start. Start a new topic, select a practice folder and **Restricted** access, and ask nanobot to summarize a file there. See [Your first file task](../start-without-technical-background.md#your-first-file-task) for a complete example. Reopen the same instance with `nanobot webui` if it is not running; the launcher starts or joins its gateway.
## Production notes
-- Keep one workspace per project or personal context.
+- Choose a project folder for file work. Use [separate instances](../multiple-instances.md) when identity or long-term memory must be isolated.
- Use `modelPresets` when you want stable names for fast, deep, local, or fallback models.
- Keep `nanobot gateway` running for WebUI, chat apps, automations, and the WebSocket channel.
- Use the Python SDK or OpenAI-compatible API when another program should call the agent.
@@ -50,7 +38,7 @@ The WebUI starts the local gateway, opens a browser, and keeps persistent chat s
## Troubleshooting
- `nanobot status` shows the config path, workspace path, and active model.
-- If `nanobot agent -m "Hello!"` fails, fix provider setup before opening the WebUI or chat apps.
+- If the model cannot reply, use **Settings → Models** to correct its connection before adding chat apps.
- If the WebUI opens but does not answer, check gateway logs and provider credentials.
## Related nanobot docs
diff --git a/docs/guides/chat-app-ai-agent.md b/docs/guides/chat-app-ai-agent.md
index 518dc05a8..5785f1c7e 100644
--- a/docs/guides/chat-app-ai-agent.md
+++ b/docs/guides/chat-app-ai-agent.md
@@ -13,13 +13,9 @@ nanobot can run as a self-hosted chatbot or AI agent in Telegram, Discord, Slack
Use chat apps when the agent should live where users already communicate: private DMs, team channels, group chats, email threads, or bot workspaces.
-## Install
+## Before you start
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-nanobot webui
-```
+Complete [Quick Start](../quick-start.md) if nanobot is not installed or cannot reply yet. If you already have a working WebUI or CLI session, continue here using that instance; no reinstall or second gateway is needed.
Send `Hello!` in the WebUI before adding a channel. Then choose one platform guide for the bot/account prerequisites:
@@ -38,14 +34,14 @@ Send `Hello!` in the WebUI before adding a channel. Then choose one platform gui
Use the guided channel setup:
1. Get the platform token, login state, webhook, or mailbox credentials.
-2. Open **Settings → Channels** in the WebUI.
+2. Open **Channels** in the WebUI.
3. Choose the platform and open its setup panel.
4. Complete the credential or QR flow and install optional support if prompted.
5. Restart when the WebUI requests it.
6. Send a private test message.
7. Approve the pairing request in the WebUI when a DM-capable channel asks for one.
-If your installed release does not show **Settings → Channels**, use the full [Chat Apps reference](../chat-apps.md#manual-setup-pattern) to configure the channel manually.
+If your installed release does not show **Channels**, use the full [Chat Apps reference](../chat-apps.md#manual-setup-pattern) to configure the channel manually.
Check status from the terminal when you need a lower-level confirmation:
@@ -78,7 +74,7 @@ Use the full [Chat Apps reference](../chat-apps.md) when you manage `config.json
- If `nanobot channels status` does not show the channel, the config key or optional dependency is likely missing.
- If the first DM returns a pairing code, approve the pending request in the WebUI or use `/pairing approve <code>` from an authorized chat.
-- If messages do not arrive, run `nanobot gateway --verbose` and compare platform credentials, event permissions, and allow lists.
+- If messages do not arrive, inspect the running gateway logs and compare platform credentials, event permissions, and allow lists. Use `--verbose` when restarting that gateway for diagnosis.
- If group replies are unexpected, review that channel's group policy.
## Related nanobot docs
diff --git a/docs/guides/configure-langfuse-observability.md b/docs/guides/configure-langfuse-observability.md
index 8f1fa459c..d167af788 100644
--- a/docs/guides/configure-langfuse-observability.md
+++ b/docs/guides/configure-langfuse-observability.md
@@ -14,13 +14,7 @@ Use Langfuse when you need observability for model requests, latency, errors, co
## Install
-Install nanobot and prove the agent works:
-
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-nanobot agent -m "Hello!"
-```
+Complete [Quick Start](../quick-start.md) if nanobot is not installed or cannot reply yet. Continue with the same working instance.
Install Langfuse:
diff --git a/docs/guides/configure-mcp-tools.md b/docs/guides/configure-mcp-tools.md
index f5df2f225..0f62223fe 100644
--- a/docs/guides/configure-mcp-tools.md
+++ b/docs/guides/configure-mcp-tools.md
@@ -12,13 +12,9 @@ This guide adds an MCP server to nanobot so the agent can use external tools thr
Use MCP when the capability you need already exists as an MCP server, or when you want external tools to be managed outside nanobot core.
-## Install
+## Before you start
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-nanobot agent -m "Hello!"
-```
+Complete [Quick Start](../quick-start.md) if nanobot is not installed or cannot reply yet. If you already have a working WebUI or CLI session, continue here using that instance; no reinstall or second gateway is needed.
Install the MCP server runtime separately. Many examples use `npx`, `uvx`, or a remote HTTP endpoint.
@@ -32,6 +28,9 @@ For local interactive setup:
4. Save and restart when prompted.
5. Mention the connected MCP server with `@` in the next message and ask for a small test action.
+<details>
+<summary>Manual configuration</summary>
+
For manual or deployment-managed config, add this to `~/.nanobot/config.json`:
```json
@@ -50,6 +49,8 @@ For manual or deployment-managed config, add this to `~/.nanobot/config.json`:
Restart nanobot and ask a question that requires the MCP tool.
+</details>
+
## Production notes
- Prefer `enabledTools` over exposing every tool by default.
diff --git a/docs/guides/configure-model-fallback.md b/docs/guides/configure-model-fallback.md
index 0f0eebd7e..3fd189872 100644
--- a/docs/guides/configure-model-fallback.md
+++ b/docs/guides/configure-model-fallback.md
@@ -12,18 +12,19 @@ Model fallback lets nanobot try a primary model first, then fall back to one or
Use fallback when you want better reliability across rate limits, provider outages, local model downtime, or cost-sensitive routing.
-## Install
+## Before you start
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-nanobot agent -m "Hello!"
-```
+Complete [Quick Start](../quick-start.md) if nanobot is not installed or cannot reply yet. If you already have a working WebUI or CLI session, continue here using that instance; no reinstall or second gateway is needed.
Verify each provider works before adding it as a fallback.
## Minimal working example
+In **Settings → Models**, create the primary and backup presets, then use **Enable preset** and arrange their order. The first enabled preset is primary; later entries are tried as fallbacks. Save and test each preset before relying on the chain.
+
+<details>
+<summary>Manual configuration</summary>
+
Merge this shape into `~/.nanobot/config.json` and replace provider/model names with ones you control:
```json
@@ -55,6 +56,8 @@ Merge this shape into `~/.nanobot/config.json` and replace provider/model names
String entries in `fallbackModels` are preset names, not raw model IDs. Replace the placeholder model IDs with currently supported model IDs from your provider. The [Provider Cookbook](../provider-cookbook.md) has concrete recipes for common providers.
+</details>
+
## Production notes
- In the WebUI, a reply produced by a named fallback preset shows its provider logo and preset name next to the reply timestamp. Hover, focus, or click the badge for an explanation. The composer still shows your selected preset; primary replies have no fallback badge. Saved replies retain the name used for that invocation, even after a preset is renamed or deleted. Older replies without recorded attribution and unnamed inline fallback objects are not labeled.
diff --git a/docs/guides/configure-ollama-prompt-cache.md b/docs/guides/configure-ollama-prompt-cache.md
index 826ca211f..fd83b1718 100644
--- a/docs/guides/configure-ollama-prompt-cache.md
+++ b/docs/guides/configure-ollama-prompt-cache.md
@@ -144,7 +144,14 @@ Ollama reuses the existing model layers. The new tag adds a small template and m
## Select the derived model in nanobot
-Merge this preset into `~/.nanobot/config.json` and select it:
+Open **Settings → Models → New preset**, select your Ollama connection, enter the derived model name, and save. Use **Enable preset** if it is disabled, then drag it to the first enabled position, marked **Primary**. This saves the default model used by sessions without their own model selection, including the fresh CLI session below.
+
+Run the CLI commands with the same nanobot home as the WebUI. If the WebUI uses a custom home, add `--home <path>` before each subcommand.
+
+<details>
+<summary>Manual configuration</summary>
+
+Merge this preset into your instance's `config.json` to make it the default:
```json
{
@@ -170,7 +177,9 @@ Merge this preset into `~/.nanobot/config.json` and select it:
}
```
-Verify the selected model and repeat the two-turn check:
+</details>
+
+Run `nanobot status` and confirm that **Model** shows `llama3.1:8b-prefix-stable-v1`, then repeat the two-turn check. If `cli:ollama-stable-check` already exists with a saved model selection, use a new session name for both turns.
```bash
nanobot status
@@ -184,7 +193,16 @@ In one controlled test with Ollama 0.32.1, `llama3.1:8b`, and one slot, the seco
## Roll back
-Switch `agents.defaults.modelPreset` back to the original preset. When no config uses the derived tag, remove it with:
+In **Settings → Models**, move the original preset back to the first enabled position and disable the derived preset. For conversations with a saved model selection, select the original preset in the composer as well.
+
+<details>
+<summary>Manual configuration</summary>
+
+Set `agents.defaults.modelPreset` back to the original preset in your instance's `config.json`.
+
+</details>
+
+When no configuration or session uses the derived tag, remove it with:
```bash
ollama rm llama3.1:8b-prefix-stable-v1
diff --git a/docs/guides/configure-openai-compatible-provider.md b/docs/guides/configure-openai-compatible-provider.md
index cda4b47e6..ce2b92b92 100644
--- a/docs/guides/configure-openai-compatible-provider.md
+++ b/docs/guides/configure-openai-compatible-provider.md
@@ -12,12 +12,9 @@ nanobot can call OpenAI-compatible model providers by configuring an `apiBase`,
Use this for local or hosted services that expose OpenAI-compatible endpoints, including internal gateways, local model servers, and provider proxies that are not already named in nanobot.
-## Install
+## Before you start
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-```
+Complete [Quick Start](../quick-start.md) if nanobot is not installed or cannot reply yet. If you already have a working WebUI or CLI session, continue here using that instance; no reinstall or second gateway is needed.
Verify the endpoint responds before debugging nanobot:
@@ -27,6 +24,14 @@ curl -sS https://api.example.com/v1/models
## Minimal working example
+1. Open **Settings → Models → New preset**.
+2. In **Provider**, choose **Add provider** and create a custom connection with your endpoint URL and credential.
+3. Select the model served by that endpoint, name the preset, and save.
+4. Select the preset in the chat composer and send `Hello!`.
+
+<details>
+<summary>Manual configuration</summary>
+
Merge this into `~/.nanobot/config.json`:
```json
@@ -54,11 +59,9 @@ Merge this into `~/.nanobot/config.json`:
}
```
-Then run:
+</details>
-```bash
-nanobot agent -m "Hello!"
-```
+Verify in the WebUI with the new preset selected. For the manual snippet above, which sets the global default, you can instead run `nanobot agent -m "Hello!"` from the same instance. A different CLI session does not inherit a WebUI topic's model selection.
## Production notes
diff --git a/docs/guides/configure-web-search.md b/docs/guides/configure-web-search.md
index 87c4d129f..fafe275e3 100644
--- a/docs/guides/configure-web-search.md
+++ b/docs/guides/configure-web-search.md
@@ -12,13 +12,9 @@ nanobot includes built-in web search and web fetch tools. Search uses DuckDuckGo
Configure web search when the agent needs current information, public web research, source discovery, or page fetching during a task.
-## Install
+## Before you start
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-nanobot agent -m "Hello!"
-```
+Complete [Quick Start](../quick-start.md) if nanobot is not installed or cannot reply yet. If you already have a working WebUI or CLI session, continue here using that instance; no reinstall or second gateway is needed.
Web tools are enabled by default. Configure them only when you want a specific provider, API key, proxy, fetch behavior, or SSRF allowlist.
@@ -27,11 +23,14 @@ Web tools are enabled by default. Configure them only when you want a specific p
For local interactive setup:
1. Run `nanobot webui`.
-2. Open **Settings → Web**.
+2. Open **Settings → Capabilities → Web access**.
3. Enable web search, choose a provider, and enter its API key if required.
4. Save and restart when prompted.
5. Ask a question that requires current information and inspect the cited sources.
+<details>
+<summary>Manual configuration</summary>
+
For manual or deployment-managed config, use the default search provider:
```json
@@ -64,6 +63,8 @@ Or use an API-backed provider:
Ask a question that requires current information and inspect the tool activity in the WebUI or logs.
+</details>
+
## Production notes
- Keep API keys in environment variables.
diff --git a/docs/guides/deploy-nanobot-gateway.md b/docs/guides/deploy-nanobot-gateway.md
index 755d2a372..ad654d8e9 100644
--- a/docs/guides/deploy-nanobot-gateway.md
+++ b/docs/guides/deploy-nanobot-gateway.md
@@ -12,33 +12,33 @@ The nanobot gateway is the long-running self-hosted AI agent process that keeps
Use this when nanobot should keep running after a single CLI turn. Chat apps, browser sessions, background automations, local triggers, and server-side integrations all depend on a live gateway.
-## Install
+## Start from your current setup
+
+If nanobot already replies in the WebUI, its gateway is already running. To keep it alive after closing the launcher, close the foreground launcher and start the same instance in background mode:
```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-nanobot status
-nanobot agent -m "Hello!"
+nanobot gateway --background
+nanobot gateway status
+nanobot gateway logs
```
-## Minimal working example
+Run `nanobot webui` when you need to return to the browser; it attaches to the running gateway. Do not run a second foreground gateway for the same instance.
-Run the gateway in the foreground:
+For a new host, choose one setup path:
-```bash
-nanobot gateway
-```
+- **Docker:** follow [container initialization and verification](../deployment.md#docker-compose). It creates the config and checks the model inside the container; a host nanobot installation is unnecessary.
+- **Host installation:** follow the [quick start](../quick-start.md). On a headless machine, use `nanobot onboard --wizard`, then `nanobot agent -m "Hello!"` to check the selected model.
-For WebUI background usage:
+## Keep the gateway running
+
+Background mode keeps the current process alive; for automatic startup after reboot and restart on failure, choose [Docker Compose](../deployment.md#docker-compose), a [systemd user service](../deployment.md#linux-service), or a [macOS LaunchAgent](../deployment.md#macos-launchagent). Use the same config and workspace as the successful model check. Stop a manually managed gateway before starting a service for that instance.
+
+For foreground diagnosis only:
```bash
-nanobot gateway --background
-nanobot gateway status
-nanobot gateway logs
+nanobot gateway --verbose
```
-Open the configured WebUI URL in a browser, or run `nanobot webui` as a foreground client.
-
## Production notes
- Docker Compose is the most repeatable Linux container path.
@@ -50,7 +50,7 @@ Open the configured WebUI URL in a browser, or run `nanobot webui` as a foregrou
## Security notes
- Plan ports before exposing services. Gateway health defaults to `18790`, WebUI/WebSocket defaults to `8765`, and `nanobot serve` defaults to `8900`.
-- Bind externally only when you have configured tokens or API keys.
+- Protect WebUI and API network listeners with their respective token or key settings. The health endpoint has no authentication; keep its published port on loopback or behind a restricted monitoring interface.
- Keep chat access control intentional before deploying.
- Use Docker or Linux sandboxing when shell tools are enabled for unattended work.
diff --git a/docs/guides/discord-ai-agent.md b/docs/guides/discord-ai-agent.md
index 24bd8b143..75a485d62 100644
--- a/docs/guides/discord-ai-agent.md
+++ b/docs/guides/discord-ai-agent.md
@@ -11,24 +11,24 @@ This guide connects nanobot to Discord so a Discord user or server channel can t
## Prerequisites
-- A working local nanobot reply:
-
-```bash
-nanobot agent -m "Hello!"
-```
+- A normal reply in your existing nanobot WebUI or CLI. If you have not reached that point, complete [Quick Start](../quick-start.md) first.
- Access to the Discord Developer Portal.
- A Discord server where you can invite a bot.
-## Install nanobot
+## Continue from your running instance
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-```
+If you are already chatting in the WebUI, keep it open and continue below. It has already started the gateway. To reopen it later, use the same installation's `nanobot webui` command; there is no need to install nanobot again.
+
+For terminal or server setup, use the manual configuration section below. Reuse the config/home and executable from your working instance. Docker users should use the [container commands](../deployment.md#docker-compose).
## Enable the Discord channel
+Create a Discord application and bot, enable **Message Content Intent**, and invite it with permission to read history and send messages. In **Channels → Discord**, enter the bot token, enable the channel, and save. Use **Advanced** for allowed channels and reply behavior; follow any restart prompt.
+
+<details>
+<summary>Manual configuration</summary>
+
Install the optional channel dependency:
```bash
@@ -60,21 +60,31 @@ Invite the bot with permissions to read history and send messages.
Set `replyToMessage` to `true` to make responses use Discord's native reply UI. It defaults to `false`, preserving the existing behavior.
-## Run nanobot gateway
+</details>
-```bash
-nanobot channels status
-nanobot gateway
-```
+## Apply the settings
+
+In the WebUI, follow any restart prompt and keep the launcher running for the first test. You do not need to start another gateway. For unattended operation afterward, use [background or service mode](../cli-reference.md#gateway).
+
+For manual config changes, restart the existing gateway through its owning terminal, `nanobot gateway restart` for background mode, or its service/container supervisor. If none is running, start `nanobot gateway` and leave it running. Run diagnostic CLI commands in a separate terminal using the same installation and config.
## Test a message
-Send the bot a DM first. It should return a pairing code. Approve it from a trusted local surface:
+Send the bot a DM first. It should return a pairing code. Return to the WebUI pairing prompt and enter the code from your own private chat. Only a matching pending code is approved; do not enter another person's code. Then send your message again.
+
+<details>
+<summary>Terminal-only pairing</summary>
+
+In a separate local terminal, using the same instance:
```bash
nanobot agent -m "/pairing approve ABCD-EFGH"
```
+Replace the example code with your actual code.
+
+</details>
+
After approval, mention it in an allowed server channel:
```text
diff --git a/docs/guides/email-ai-agent.md b/docs/guides/email-ai-agent.md
index 881a5014a..3bcce94ba 100644
--- a/docs/guides/email-ai-agent.md
+++ b/docs/guides/email-ai-agent.md
@@ -11,24 +11,24 @@ This guide turns nanobot into an email AI agent that polls IMAP for accepted mes
## Prerequisites
-- A working local nanobot reply:
-
-```bash
-nanobot agent -m "Hello!"
-```
+- A normal reply in your existing nanobot WebUI or CLI. If you have not reached that point, complete [Quick Start](../quick-start.md) first.
- A mailbox for the bot.
- IMAP and SMTP access. For Gmail, use an app password rather than your account password.
-## Install nanobot
+## Continue from your running instance
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-```
+If you are already chatting in the WebUI, keep it open and continue below. It has already started the gateway. To reopen it later, use the same installation's `nanobot webui` command; there is no need to install nanobot again.
+
+For terminal or server setup, use the manual configuration section below. Reuse the config/home and executable from your working instance. Docker users should use the [container commands](../deployment.md#docker-compose).
## Enable the Email channel
+Prepare a dedicated mailbox and app password. In **Channels → Email**, grant mailbox access, enter IMAP and SMTP settings, and restrict allowed senders. Use **Advanced** for trusted authentication services and other mailbox options. Enable the channel, save, and follow any restart prompt.
+
+<details>
+<summary>Manual configuration</summary>
+
Merge this snippet into `~/.nanobot/config.json` and replace the addresses and passwords:
```json
@@ -54,12 +54,13 @@ Merge this snippet into `~/.nanobot/config.json` and replace the addresses and p
}
```
-## Run nanobot gateway
+</details>
-```bash
-nanobot channels status
-nanobot gateway
-```
+## Apply the settings
+
+In the WebUI, follow any restart prompt and keep the launcher running for the first test. You do not need to start another gateway. For unattended operation afterward, use [background or service mode](../cli-reference.md#gateway).
+
+For manual config changes, restart the existing gateway through its owning terminal, `nanobot gateway restart` for background mode, or its service/container supervisor. If none is running, start `nanobot gateway` and leave it running. Run diagnostic CLI commands in a separate terminal using the same installation and config.
## Test a message
@@ -80,7 +81,12 @@ Email authentication now requires an explicit receiving-service trust anchor. Th
1. Back up your configuration and temporarily disable the Email channel while configuring the receiver. Do not turn off SPF/DKIM verification as an upgrade workaround.
2. Confirm with your receiving mail service or administrator which exact `authserv-id` it adds, and that it strips externally supplied headers claiming that identity. It must provide one consolidated `Authentication-Results` header. A name visible in a received email is not, by itself, proof of trust; do not infer it from your IMAP hostname or copy it from an arbitrary message.
-3. In Email settings, open **Advanced** and set **Trusted authentication services**, or merge the following fields into `channels.email` in your existing config:
+3. In **Channels → Email**, open **Advanced** and set **Trusted authentication services** to your confirmed receiver identity. Keep SPF/DKIM verification enabled.
+
+ <details>
+ <summary>Manual configuration</summary>
+
+ Merge these fields into `channels.email` in your existing config:
```json
{
@@ -91,6 +97,9 @@ Email authentication now requires an explicit receiving-service trust anchor. Th
```
The example is for a receiver using `mx.google.com`; use your confirmed receiver identity instead. JSON uses a list; the WebUI accepts comma-separated values. Wildcards and URLs are not accepted. Multiple configured identities are alternatives, not permission to combine multiple trusted result headers.
+
+ </details>
+
4. Check the IMAP/SMTP connection, re-enable Email, and restart the gateway after editing a configuration file. Send one ordinary message from an allowed address and confirm receipt and reply. A successful connection check verifies credentials and configuration, not your mail service's header-stripping policy.
Each enabled verification method must pass and identify the visible sender's domain, or a parent/subdomain of it. DKIM uses `header.d` when present, otherwise the domain of the receiver-reported `header.i`. This is not a full DMARC policy implementation, and domain authentication does not independently authenticate the mailbox local part. Forwarders, mailing lists, or receivers that emit separate SPF and DKIM result headers may need mail-service changes. Keep Email disabled if the receiver cannot meet the trust contract.
diff --git a/docs/guides/feishu-ai-agent.md b/docs/guides/feishu-ai-agent.md
index 9c4458dc6..3de18d996 100644
--- a/docs/guides/feishu-ai-agent.md
+++ b/docs/guides/feishu-ai-agent.md
@@ -11,24 +11,24 @@ This guide connects nanobot to Feishu or Lark through the `feishu` channel. The
## Prerequisites
-- A working local nanobot reply:
-
-```bash
-nanobot agent -m "Hello!"
-```
+- A normal reply in your existing nanobot WebUI or CLI. If you have not reached that point, complete [Quick Start](../quick-start.md) first.
- A Feishu or Lark account that can create or approve bot apps.
- Permission to run `nanobot gateway` continuously.
-## Install nanobot
+## Continue from your running instance
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-```
+If you are already chatting in the WebUI, keep it open and continue below. It has already started the gateway. To reopen it later, use the same installation's `nanobot webui` command; there is no need to install nanobot again.
+
+For terminal or server setup, use the manual configuration section below. Reuse the config/home and executable from your working instance. Docker users should use the [container commands](../deployment.md#docker-compose).
## Enable the Feishu channel
+Open **Channels → Feishu** and follow the QR connection flow. Install support if prompted, then open the authorization link or scan the code. If using an existing app, enter its App ID and App Secret in the setup panel. Enable the channel, save, and follow any restart prompt.
+
+<details>
+<summary>Manual configuration</summary>
+
Install the optional channel dependency:
```bash
@@ -66,21 +66,31 @@ Omitting `allowFrom` enables pairing-only mode. A new user should DM the bot, ge
For manual apps, enable the Bot capability, receive-message events, and Long Connection mode. If your app cannot get the `cardkit:card:write` permission, set `"streaming": false`.
-## Run nanobot gateway
+</details>
-```bash
-nanobot channels status
-nanobot gateway
-```
+## Apply the settings
+
+In the WebUI, follow any restart prompt and keep the launcher running for the first test. You do not need to start another gateway. For unattended operation afterward, use [background or service mode](../cli-reference.md#gateway).
+
+For manual config changes, restart the existing gateway through its owning terminal, `nanobot gateway restart` for background mode, or its service/container supervisor. If none is running, start `nanobot gateway` and leave it running. Run diagnostic CLI commands in a separate terminal using the same installation and config.
## Test a message
-DM the bot first. It should return a pairing code. Approve it from a trusted local surface:
+DM the bot first. It should return a pairing code. Return to the WebUI pairing prompt and enter the code from your own private chat. Only a matching pending code is approved; do not enter another person's code. Then send your message again.
+
+<details>
+<summary>Terminal-only pairing</summary>
+
+In a separate local terminal, using the same instance:
```bash
nanobot agent -m "/pairing approve ABCD-EFGH"
```
+Replace the example code with your actual code.
+
+</details>
+
After approval, DM the bot again or mention it in a group chat:
```text
diff --git a/docs/guides/linear-agent.md b/docs/guides/linear-agent.md
index b1a28ee51..2d7602695 100644
--- a/docs/guides/linear-agent.md
+++ b/docs/guides/linear-agent.md
@@ -104,7 +104,7 @@ Keep `nanobot webui` running throughout the setup.
### 1. Enter the public address
-1. Open **Settings → Channels → Linear**.
+1. Open **Channels → Linear**.
2. Enter your public origin in **Public HTTPS URL**, for example `https://nanobot.example.com`.
3. Leave the three credential fields empty for now.
4. Wait for **Settings saved.**, then select **Create Linear app**. Selecting it before entering an address shows a prompt and returns focus to the URL field.
@@ -141,7 +141,7 @@ In the new Linear app's settings, copy these values:
| Client Secret | **OAuth client secret** |
| Webhook signing secret | **Webhook signing secret** |
-Return to **Settings → Channels → Linear** and paste all three values. Ordinary fields save automatically after a short pause. For each secret, select **Save** beside that field and wait for its **Saved** status. **Connect Linear** becomes available once the required settings are saved. Listener settings, callback paths, and allowed users are in **Advanced**; setup guides are in the dialog's **Help** menu.
+Return to **Channels → Linear** and paste all three values. Ordinary fields save automatically after a short pause. For each secret, select **Save** beside that field and wait for its **Saved** status. **Connect Linear** becomes available once the required settings are saved. Listener settings, callback paths, and allowed users are in **Advanced**; setup guides are in the dialog's **Help** menu.
A masked value with **Saved** means this instance already has the secret; it is not an empty input. To change it, select **Replace**, enter the new secret, then **Save**. **Cancel** or Escape leaves the saved secret unchanged. Leaving the field or showing the newly typed value does not save it. A failed save retains the draft for retry; the old secret is never sent back to the browser.
@@ -223,7 +223,7 @@ Member switches are stored in the instance's `linear/state.sqlite3`, separately
The setup is complete when all of these checks pass:
-- **Settings → Channels → Linear** shows the channel as on with no runtime error.
+- **Channels → Linear** shows the channel as on with no runtime error.
- The Linear app's **Webhooks → Delivery status** is enabled, its URL uses the current public origin, and **Events** includes **Agent session events**.
- While the channel is running, opening `http://127.0.0.1:3979/linear/health` on the nanobot machine returns `{"ok":true}`. Use your configured host and port if you changed them.
- If your proxy also forwards `/linear/health`, its public URL returns `{"ok":true}`. This is optional: a proxy exposing only the callback and webhook can correctly return 404 for public health. Use successful OAuth and webhook delivery to verify those two routes; do not expose the admin UI for this check.
@@ -234,6 +234,9 @@ The setup is complete when all of these checks pass:
## Manual configuration
+<details>
+<summary>Manual configuration</summary>
+
Use this path when deployment tooling manages `~/.nanobot/config.json` directly. The WebUI path above is easier because it generates the Linear app definition and completes OAuth for you.
Merge this section into `~/.nanobot/config.json`:
@@ -267,6 +270,8 @@ Webhook: https://nanobot.example.com/linear/webhook
Subscribe the webhook to exactly `AgentSessionEvent`, `PermissionChange`, and `OAuthAuthorization` and enable webhook delivery in the Linear app's settings. Do not subscribe to `Comment`. The OAuth connection step in the WebUI is still required: it installs the app and stores the workspace-scoped access and refresh tokens.
+</details>
+
## Security and reliability
- OAuth uses authorization code flow, PKCE, a short-lived CSRF state, and the Linear app actor.
diff --git a/docs/guides/long-running-ai-agent.md b/docs/guides/long-running-ai-agent.md
index 087dc354e..d75a551db 100644
--- a/docs/guides/long-running-ai-agent.md
+++ b/docs/guides/long-running-ai-agent.md
@@ -13,29 +13,28 @@ nanobot can keep agent work alive across turns through sustained goals, persiste
Use this when the task is not a one-shot answer: project work, recurring checks, scheduled summaries, file maintenance, multi-step research, or local triggers from scripts and build jobs.
-## Install
+## Before you start
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-nanobot agent -m "Hello!"
-```
+Use an installation with a configured model that has already returned a reply. If this is your first setup, follow [Quick Start](../quick-start.md), then return here. Existing WebUI users can continue in the current instance.
## Minimal working example
-Start a gateway:
+Your running WebUI or TUI already uses a gateway. In that chat, start a sustained goal:
-```bash
-nanobot gateway
+```text
+/goal Review this workspace, identify missing tests, and propose the smallest next fix.
```
-From the WebUI or a chat session, start a sustained goal:
+For scheduled or trigger-based runs, create the automation from the target chat so nanobot can link it to the correct session and project context.
-```text
-/goal Review this workspace, identify missing tests, and propose the smallest next fix.
+To keep work running after closing the interactive launcher, promote the existing gateway from a terminal:
+
+```bash
+nanobot gateway --background
+nanobot gateway status
```
-For scheduled or trigger-based runs, create the automation from the target chat so nanobot can link it to the correct session and workspace.
+Use the same `--config` and explicit `--workspace` selectors as your instance. In the TUI, `/detach` also keeps the gateway running while closing the client. A background gateway does not survive a machine shutdown by itself; see [Deployment](../deployment.md) for service management. Review [schedule restart behavior](../automations.md#delivery-and-reliability) before relying on a timed task.
## Production notes
diff --git a/docs/guides/mattermost-ai-agent.md b/docs/guides/mattermost-ai-agent.md
index 4783f7159..f5f8b1aed 100644
--- a/docs/guides/mattermost-ai-agent.md
+++ b/docs/guides/mattermost-ai-agent.md
@@ -11,24 +11,26 @@ This guide connects nanobot to Mattermost through the built-in Mattermost channe
## Prerequisites
-- A working local nanobot reply:
-
-```bash
-nanobot agent -m "Hello!"
-```
+- A normal reply in your existing nanobot WebUI or CLI. If you have not reached that point, complete [Quick Start](../quick-start.md) first.
- A Mattermost server URL.
- A bot token or personal access token for the bot account.
-## Install nanobot
+## Continue from your running instance
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-```
+If you are already chatting in the WebUI, keep it open and continue below. It has already started the gateway. To reopen it later, use the same installation's `nanobot webui` command; there is no need to install nanobot again.
+
+For terminal or server setup, use the manual configuration section below. Reuse the config/home and executable from your working instance. Docker users should use the [container commands](../deployment.md#docker-compose).
## Enable the Mattermost channel
+Prepare the Mattermost bot token and team ID. In **Channels → Mattermost**, enter the server URL, token, and team ID. Use **Advanced** for group and thread policies; for DM pairing, choose **Allowlist** with an empty DM allowlist. Enable the channel, save, and follow any restart prompt.
+
+DM approval does not restrict group access. With the mention policy below, any member can invoke the bot in a channel it can see. For DM-only access, set the group policy to **Allowlist** and leave the group allowlist empty. To allow selected channels, add their IDs; all members of those channels can then use the bot under the configured mention/thread rules.
+
+<details>
+<summary>Manual configuration</summary>
+
Merge this snippet into `~/.nanobot/config.json`:
```json
@@ -56,21 +58,31 @@ When `groupPolicy` is `"allowlist"`, `groupAllowFrom` remains the outer channel
Mattermost DMs are open by default. Setting `dm.policy` to `"allowlist"` with no `dm.allowFrom` entries makes new DM senders receive a pairing code. Approve the code before using the bot normally.
-## Run nanobot gateway
+</details>
-```bash
-nanobot channels status
-nanobot gateway
-```
+## Apply the settings
+
+In the WebUI, follow any restart prompt and keep the launcher running for the first test. You do not need to start another gateway. For unattended operation afterward, use [background or service mode](../cli-reference.md#gateway).
+
+For manual config changes, restart the existing gateway through its owning terminal, `nanobot gateway restart` for background mode, or its service/container supervisor. If none is running, start `nanobot gateway` and leave it running. Run diagnostic CLI commands in a separate terminal using the same installation and config.
## Test a message
-DM the bot account. It should return a pairing code. Approve it from a trusted local surface:
+DM the bot account. It should return a pairing code. Return to the WebUI pairing prompt and enter the code from your own private chat. Only a matching pending code is approved; do not enter another person's code. Then send your message again.
+
+<details>
+<summary>Terminal-only pairing</summary>
+
+In a separate local terminal, using the same instance:
```bash
nanobot agent -m "/pairing approve ABCD-EFGH"
```
+Replace the example code with your actual code.
+
+</details>
+
Then DM the bot again, or mention it in a channel where the bot has access:
```text
diff --git a/docs/guides/mcp-tools-for-ai-agents.md b/docs/guides/mcp-tools-for-ai-agents.md
index 8643e1109..f3bcdd417 100644
--- a/docs/guides/mcp-tools-for-ai-agents.md
+++ b/docs/guides/mcp-tools-for-ai-agents.md
@@ -5,25 +5,26 @@ nanobot can connect MCP servers and expose their tools to the agent alongside bu
## What you will build
- a working nanobot agent
-- one MCP server configured in `config.json`
+- one MCP server connected through **Apps → MCP**
- a restricted set of tools available to the model
## When to use this
Use MCP when a tool already exists as an MCP server, when another application publishes an MCP adapter, or when you want a clean boundary between nanobot and external tool logic.
-## Install
+## Before you start
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-nanobot agent -m "Hello!"
-```
+Complete [Quick Start](../quick-start.md) if nanobot is not installed or cannot reply yet. If you already have a working WebUI or CLI session, continue here using that instance; no reinstall or second gateway is needed.
Install the MCP server's own runtime separately. For example, many local MCP servers use `npx` or `uvx`.
## Minimal working example
+Open **Apps → MCP**, choose a preset or add a custom server, configure its command or endpoint, limit its enabled tools, and save. Follow any connection or restart prompt, then mention the integration with `@` in chat and request a small test action.
+
+<details>
+<summary>Manual configuration</summary>
+
Add a stdio MCP server to `~/.nanobot/config.json`:
```json
@@ -40,6 +41,8 @@ Add a stdio MCP server to `~/.nanobot/config.json`:
}
```
+</details>
+
Restart nanobot, then ask a question that needs the MCP tool.
## Production notes
@@ -58,7 +61,7 @@ Restart nanobot, then ask a question that needs the MCP tool.
## Troubleshooting
-- Start `nanobot gateway --verbose` and check MCP startup logs.
+- Check MCP startup logs on the running gateway; use `--verbose` when restarting it for diagnosis.
- Confirm the MCP command works by itself before debugging nanobot.
- If an HTTP MCP server is blocked, review the SSRF whitelist and use a narrow host CIDR.
diff --git a/docs/guides/openai-compatible-agent-api.md b/docs/guides/openai-compatible-agent-api.md
index 3fb21c137..a258d8d39 100644
--- a/docs/guides/openai-compatible-agent-api.md
+++ b/docs/guides/openai-compatible-agent-api.md
@@ -13,27 +13,25 @@ nanobot can expose a local OpenAI-compatible endpoint behind `/v1/chat/completio
Use this when an existing client, another language, or a separate process already knows how to call an OpenAI-compatible API. Use the Python SDK when you want in-process access to sessions, memory, runtime helpers, and hooks.
-## Install
+## Start from your current setup
-```bash
-python -m pip install nanobot-ai
-nanobot plugins enable api
-nanobot onboard --wizard
-nanobot agent -m "Hello!"
-```
+If you already get replies in the WebUI, open **Settings → System**, configure the API service, and start it. Keep that gateway running; do not also start `nanobot serve` on the same port.
-## Minimal working example
-
-Start the API server:
+If nanobot is not configured yet, complete the [quick start](../quick-start.md) first. For a terminal-managed API using that existing config:
```bash
+nanobot plugins enable api
+nanobot agent -m "Hello!"
nanobot serve
```
-Call the chat endpoint:
+## Make a request
+
+In another terminal, call the chat endpoint. If you configured an API key, set `NANOBOT_API_KEY` to it first:
```bash
curl http://127.0.0.1:8900/v1/chat/completions \
+ -H "Authorization: Bearer $NANOBOT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [{"role": "user", "content": "hi"}],
@@ -43,8 +41,9 @@ curl http://127.0.0.1:8900/v1/chat/completions \
## Production notes
-- Pass `session_id` to isolate users, jobs, or workflows.
-- Streaming uses Server-Sent Events when `stream` is `true`.
+- Pass `session_id` to separate conversation histories. Callers still share files, memory, and tool permissions; it is not a user authorization boundary.
+- Streaming uses Server-Sent Events when `stream` is `true`. A stream without `[DONE]` is incomplete; retries can repeat tool actions. See [sessions, failures, and retries](../openai-api.md#sessions-failures-and-retries).
+- The API service returns results to its HTTP client; it does not deliver `message` tool calls to chat apps. Forward results from your application when that is needed.
- `/v1/models` reports the fixed model surface expected by compatible clients.
- File uploads are supported through JSON base64 or multipart form data.
diff --git a/docs/guides/python-ai-agent-sdk.md b/docs/guides/python-ai-agent-sdk.md
index 5bc817f32..5e789ab60 100644
--- a/docs/guides/python-ai-agent-sdk.md
+++ b/docs/guides/python-ai-agent-sdk.md
@@ -14,13 +14,9 @@ Use the Python SDK for notebooks, evals, product backends, local scripts, workfl
Use the OpenAI-compatible API instead when another language or process should call nanobot over HTTP.
-## Install
+## Before you start
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-nanobot agent -m "Hello!"
-```
+Use an installation with a configured model that has already returned a reply. If this is your first setup, follow [Quick Start](../quick-start.md), then return here. Existing WebUI users can continue in the current instance.
## Minimal working example
@@ -42,9 +38,10 @@ asyncio.run(main())
## Production notes
- Reuse one `Nanobot` instance for related work.
-- Pass `session_key` when a user, job, or eval case needs persistent history.
+- Pass `session_key` when a job or eval case needs persistent history. Different keys share workspace files and long-term memory.
- Use `bot.stream(...)` when the caller needs live text, tool, or failure events.
- Use hooks for audit logs or custom observability.
+- For short-lived scripts, see [Persist memory](../python-sdk.md#persist-memory-in-a-short-lived-script): closing the SDK does not run Dream.
## Security notes
diff --git a/docs/guides/qq-ai-agent.md b/docs/guides/qq-ai-agent.md
index bdd48a309..09aed00fb 100644
--- a/docs/guides/qq-ai-agent.md
+++ b/docs/guides/qq-ai-agent.md
@@ -11,24 +11,24 @@ This guide connects nanobot to QQ through the official `qq` channel. The officia
## Prerequisites
-- A working local nanobot reply:
-
-```bash
-nanobot agent -m "Hello!"
-```
+- A normal reply in your existing nanobot WebUI or CLI. If you have not reached that point, complete [Quick Start](../quick-start.md) first.
- Access to the QQ Open Platform.
- A QQ account added to the bot sandbox for testing.
-## Install nanobot
+## Continue from your running instance
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-```
+If you are already chatting in the WebUI, keep it open and continue below. It has already started the gateway. To reopen it later, use the same installation's `nanobot webui` command; there is no need to install nanobot again.
+
+For terminal or server setup, use the manual configuration section below. Reuse the config/home and executable from your working instance. Docker users should use the [container commands](../deployment.md#docker-compose).
## Enable the QQ channel
+Create a QQ bot application, copy its AppID and AppSecret, and add your account to the sandbox members. In **Channels → QQ**, enter those credentials, enable the channel, and save. Follow any installation or restart prompt.
+
+<details>
+<summary>Manual configuration</summary>
+
Install the optional channel dependency:
```bash
@@ -52,21 +52,31 @@ In the QQ Open Platform, create a bot application and copy the AppID and AppSecr
Omitting `allowFrom` enables pairing-only mode. A new private sender should get a pairing code before normal agent access.
-## Run nanobot gateway
+</details>
-```bash
-nanobot channels status
-nanobot gateway
-```
+## Apply the settings
+
+In the WebUI, follow any restart prompt and keep the launcher running for the first test. You do not need to start another gateway. For unattended operation afterward, use [background or service mode](../cli-reference.md#gateway).
+
+For manual config changes, restart the existing gateway through its owning terminal, `nanobot gateway restart` for background mode, or its service/container supervisor. If none is running, start `nanobot gateway` and leave it running. Run diagnostic CLI commands in a separate terminal using the same installation and config.
## Test a message
-Send the QQ bot a private message from a sandbox account. It should return a pairing code. Approve it from a trusted local surface:
+Send the QQ bot a private message from a sandbox account. It should return a pairing code. Return to the WebUI pairing prompt and enter the code from your own private chat. Only a matching pending code is approved; do not enter another person's code. Then send your message again.
+
+<details>
+<summary>Terminal-only pairing</summary>
+
+In a separate local terminal, using the same instance:
```bash
nanobot agent -m "/pairing approve ABCD-EFGH"
```
+Replace the example code with your actual code.
+
+</details>
+
Send the message again after approval.
## Security notes
diff --git a/docs/guides/secure-local-ai-agent.md b/docs/guides/secure-local-ai-agent.md
index c0ab7593c..151da96c6 100644
--- a/docs/guides/secure-local-ai-agent.md
+++ b/docs/guides/secure-local-ai-agent.md
@@ -13,16 +13,17 @@ This guide covers the practical controls to review before letting a nanobot agen
Use this before exposing nanobot to teammates, chat apps, public networks, broad web access, or unattended automations.
-## Install
+## Before you start
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-nanobot agent -m "Hello!"
-```
+If nanobot is already open, continue in that WebUI. Otherwise follow the [first-run guide](../start-without-technical-background.md) to install it, configure a model, and send a test message.
## Minimal working example
+Open **Settings → Advanced**. Enable workspace restriction, then choose the shell sandbox supported by your host (`bwrap` on Linux or `seatbelt` on macOS). Disable shell execution when the agent does not need it. Follow any restart prompt.
+
+<details>
+<summary>Manual configuration</summary>
+
Start with workspace restriction:
```json
@@ -37,22 +38,24 @@ Start with workspace restriction:
}
```
-`bwrap` is Linux-only and requires bubblewrap. On macOS or Windows, keep `restrictToWorkspace` enabled and review shell access carefully.
+`bwrap` is Linux-only and requires bubblewrap. On macOS, use `"sandbox": "seatbelt"`. Windows has no supported OS shell sandbox; disable shell execution if the application-level workspace guard is insufficient.
+
+</details>
## Production notes
- Use environment variables for provider keys, bot tokens, and mailbox passwords.
-- Keep one workspace per trust boundary.
-- Prefer pairing for DM-capable chat apps, use narrow `allowFrom` lists only when static allowlists are intentional, and keep group policy mention-only at first.
-- Bind WebUI, WebSocket, and API services to localhost unless remote access is intentional.
+- Use [separate instances and workspaces](../multiple-instances.md) for data that must not share memory. Project selection inside one instance does not isolate memory. Use separate OS accounts or containers for mutually untrusted users.
+- Prefer [pairing](../configuration.md#pairing) for DM-capable chat apps. Slack and Mattermost DMs default to open access: set `dm.policy` to `"allowlist"` to require approval. Configure group access separately; mention-only controls when the bot responds, not who is trusted.
+- Bind WebUI, WebSocket, and API services to localhost unless remote access is intentional. Share [WebUI access](../webui.md#sharing-access) only with trusted administrators; it has no per-user roles or private topic ownership.
## Security notes
- `restrictToWorkspace` is an application-level guard, not an OS sandbox.
- `tools.exec.enable: false` removes shell execution entirely.
-- HTTP web fetch and HTTP MCP use SSRF protections by default.
+- HTTP web fetch and HTTP MCP use SSRF protections by default. Shell commands and stdio MCP processes are outside this guard. Neither shell sandbox blocks network access; use host or container egress controls for an offline deployment.
- Adding broad `tools.ssrfWhitelist` ranges increases exposure.
-- `allowFrom: ["*"]` bypasses pairing and means anyone who can reach that channel can talk to the bot.
+- On channels using the common sender allowlist, `allowFrom: ["*"]` bypasses pairing and allows every sender. Slack and Mattermost use the DM and group policies described above.
## Troubleshooting
diff --git a/docs/guides/self-hosted-ai-agent.md b/docs/guides/self-hosted-ai-agent.md
index 6c806a049..ffe2662d0 100644
--- a/docs/guides/self-hosted-ai-agent.md
+++ b/docs/guides/self-hosted-ai-agent.md
@@ -13,31 +13,19 @@ This guide sets up nanobot as a self-hosted AI agent runtime on your own machine
Use this path when you want local or server-side ownership of the agent process, workspace files, memory files, and provider keys. It is also the right path when the agent must keep running after one terminal command finishes.
-## Install
+## Choose your starting point
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-nanobot agent -m "Hello!"
-```
+**Already chatting in the WebUI:** you already have a self-hosted agent and a running gateway. Open **Channels** to connect a chat platform; use the same running gateway. If you want it to survive closing the launcher, follow [long-running gateway setup](./deploy-nanobot-gateway.md).
-Complete the CLI check before deploying the gateway. A deployment problem is much easier to debug after the provider and model are known to work.
+**New desktop installation:** follow the [quick start](../quick-start.md), configure a model in **Settings → Models**, and send `Hello!`. A normal browser reply confirms the setup; no additional CLI test or second gateway is required.
-## Minimal working example
+**New headless server:** follow the [Docker setup](../deployment.md#docker-compose), or install on the host using the [quick start's terminal setup](../quick-start.md). Verify the selected provider before installing a persistent service.
-For chat apps, automations, and WebSocket delivery, start the gateway:
+Self-hosting keeps the agent runtime and its state on your machine. A hosted model provider still receives prompts and any file content included in them. For local model inference, use the [Ollama setup](../provider-cookbook.md#recipe-ollama-local-model); local inference alone does not disable network-capable tools.
-```bash
-nanobot gateway
-```
+## Confirm the result
-For the browser surface, use the WebUI launcher instead. It can start and manage the local gateway for you:
-
-```bash
-nanobot webui
-```
-
-Or connect a channel in `~/.nanobot/config.json`, then keep the same gateway process running for messages.
+Send a message through the interface you intend to use. Check that it replies, then confirm the chosen gateway or service stays running after you close the setup terminal. Browser, chat channels, and automations use the gateway; the optional OpenAI-compatible API has its own [service setup](./openai-compatible-agent-api.md).
## Production notes
diff --git a/docs/guides/slack-ai-agent.md b/docs/guides/slack-ai-agent.md
index 2c1eae6ea..53f6006f8 100644
--- a/docs/guides/slack-ai-agent.md
+++ b/docs/guides/slack-ai-agent.md
@@ -11,23 +11,25 @@ This guide connects nanobot to Slack through Socket Mode. No public webhook URL
## Prerequisites
-- A working nanobot reply:
-
-```bash
-nanobot agent -m "Hello!"
-```
+- A normal reply in your existing nanobot WebUI or CLI. If you have not reached that point, complete [Quick Start](../quick-start.md) first.
- Permission to create a Slack app in a workspace.
-## Install nanobot
+## Continue from your running instance
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-```
+If you are already chatting in the WebUI, keep it open and continue below. It has already started the gateway. To reopen it later, use the same installation's `nanobot webui` command; there is no need to install nanobot again.
+
+For terminal or server setup, use the manual configuration section below. Reuse the config/home and executable from your working instance. Docker users should use the [container commands](../deployment.md#docker-compose).
## Enable the Slack channel
+Create a Slack app with Socket Mode, a bot token, an app-level token with `connections:write`, and the required event subscriptions. In **Channels → Slack**, enter those tokens, enable the channel, and save. For pairing, expand **Advanced**, set the DM policy to **Allowlist**, and leave its allowlist empty; follow any restart prompt.
+
+DM approval does not restrict group access. With the mention policy below, any member can invoke the bot in a channel it can see. For DM-only access, set the group policy to **Allowlist** and leave the group allowlist empty. To allow selected channels, add their IDs; all members of those channels can then use the bot under the configured mention/thread rules.
+
+<details>
+<summary>Manual configuration</summary>
+
Install the optional channel dependency:
```bash
@@ -56,21 +58,31 @@ Merge this snippet into `~/.nanobot/config.json`:
Slack DMs are open by default. Setting `dm.policy` to `"allowlist"` with no `dm.allowFrom` entries makes new DM senders receive a pairing code. Approve the code before using the bot normally.
-## Run nanobot gateway
+</details>
-```bash
-nanobot channels status
-nanobot gateway
-```
+## Apply the settings
+
+In the WebUI, follow any restart prompt and keep the launcher running for the first test. You do not need to start another gateway. For unattended operation afterward, use [background or service mode](../cli-reference.md#gateway).
+
+For manual config changes, restart the existing gateway through its owning terminal, `nanobot gateway restart` for background mode, or its service/container supervisor. If none is running, start `nanobot gateway` and leave it running. Run diagnostic CLI commands in a separate terminal using the same installation and config.
## Test a message
-DM the Slack bot directly. It should return a pairing code. Approve it from a trusted local surface:
+DM the Slack bot directly. It should return a pairing code. Return to the WebUI pairing prompt and enter the code from your own private chat. Only a matching pending code is approved; do not enter another person's code. Then send your message again.
+
+<details>
+<summary>Terminal-only pairing</summary>
+
+In a separate local terminal, using the same instance:
```bash
nanobot agent -m "/pairing approve ABCD-EFGH"
```
+Replace the example code with your actual code.
+
+</details>
+
Then DM the bot again, or mention it in a channel:
```text
diff --git a/docs/guides/telegram-ai-agent.md b/docs/guides/telegram-ai-agent.md
index 7b549f734..15b706228 100644
--- a/docs/guides/telegram-ai-agent.md
+++ b/docs/guides/telegram-ai-agent.md
@@ -11,36 +11,25 @@ This guide connects one Telegram bot to nanobot. Messages sent to that bot use y
## Prerequisites
-- A working nanobot CLI reply:
-
-```bash
-nanobot agent -m "Hello!"
-```
+- A normal reply in your existing nanobot WebUI or CLI. If you have not reached that point, complete [Quick Start](../quick-start.md) first.
- A Telegram account.
-- A bot token from `@BotFather`.
+- A bot token: open Telegram, find `@BotFather`, send `/newbot`, follow its name/username prompts, and copy the returned token. Keep the token private.
-## Install nanobot
+## Continue from your running instance
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-```
+If you are already chatting in the WebUI, keep it open and continue below. It has already started the gateway. To reopen it later, use the same installation's `nanobot webui` command; there is no need to install nanobot again.
-## Connect Telegram in the WebUI
-
-Start the WebUI:
+For terminal or server setup, use the manual configuration section below. Reuse the config/home and executable from your working instance. Docker users should use the [container commands](../deployment.md#docker-compose).
-```bash
-nanobot webui
-```
+## Connect Telegram in the WebUI
-Open **Settings → Channels → Telegram**:
+Open **Channels → Telegram**:
1. If Telegram support is not installed, turn on its switch and confirm the installation.
2. Paste the token from BotFather.
3. If the gateway cannot reach Telegram directly, expand **Advanced** and enter an HTTP or SOCKS proxy such as `http://127.0.0.1:7890`.
-4. Save and enable Telegram.
+4. Save and enable Telegram. For a first private setup, leave the sender allowlist empty: new senders must pair before they can use the agent. Do not set it to `*`.
The configuration badge appears as soon as a bot token is saved. A connection check is separate: if Telegram is temporarily unreachable, the saved configuration remains valid and the bot can continue working in environments where the gateway has network access.
@@ -48,6 +37,9 @@ Saved tokens and proxy URLs are masked. A proxy entered here is used both for th
## Manual setup
+<details>
+<summary>Manual configuration</summary>
+
For a headless installation, install Telegram support:
```bash
@@ -74,14 +66,13 @@ Omitting `allowFrom` enables pairing-only mode. The first DM from a new user get
Telegram uses long polling by default. Webhook mode is available for public HTTPS deployments; start with long polling for the first test.
-## Run nanobot gateway
+</details>
-```bash
-nanobot channels status
-nanobot gateway
-```
+## Apply the settings
+
+In the WebUI, follow any restart prompt and keep the launcher running for the first test. You do not need to start another gateway. For unattended operation afterward, use [background or service mode](../cli-reference.md#gateway).
-Leave the gateway running while you test messages.
+For manual config changes, restart the existing gateway through its owning terminal, `nanobot gateway restart` for background mode, or its service/container supervisor. If none is running, start `nanobot gateway` and leave it running. Run diagnostic CLI commands in a separate terminal using the same installation and config.
## Test a message
@@ -91,13 +82,22 @@ Open Telegram, DM the bot, and send:
Hello from Telegram
```
-The bot should reply with a pairing code. Approve it from an already trusted surface, such as the local CLI:
+The bot should reply with a pairing code. Return to the WebUI pairing prompt and enter the code from your own Telegram private chat. Do not approve codes from other people. An unapproved sender receives a code, not an agent reply.
+
+<details>
+<summary>Terminal-only pairing</summary>
+
+In a separate local terminal, using the same instance:
```bash
nanobot agent -m "/pairing approve ABCD-EFGH"
```
-Send the message again after approval. The reply should use the same model and workspace as your local CLI check.
+Replace the example code with your actual code.
+
+</details>
+
+Send the message again after approval. Confirm that your private chat now receives a normal agent reply.
## Security notes
@@ -111,7 +111,7 @@ Send the message again after approval. The reply should use the same model and w
- If the channel is not listed, run `nanobot plugins enable telegram` again in the same Python environment.
- If the WebUI shows a saved configuration but the live check cannot reach Telegram, the token is still saved. Confirm the gateway can reach `api.telegram.org`, or open **Advanced → Network proxy** and enter a proxy.
- If Telegram rejects the token, copy the current token from BotFather or regenerate it.
-- If messages do not arrive, run `nanobot gateway --verbose` and confirm the Telegram channel is enabled.
+- If messages do not arrive, check the Telegram runtime status in **Channels** and the logs of the running gateway. Confirm it is enabled and can reach Telegram; do not start a second gateway to diagnose the first.
- If a first DM returns a pairing code, that is expected. Approve the code before testing normal agent replies.
- If Telegram Web shows unsupported rich messages, keep `richMessages` disabled.
diff --git a/docs/guides/wechat-ai-agent.md b/docs/guides/wechat-ai-agent.md
index c38d0f0bf..90d849f29 100644
--- a/docs/guides/wechat-ai-agent.md
+++ b/docs/guides/wechat-ai-agent.md
@@ -11,23 +11,23 @@ This guide connects nanobot to WeChat through the `weixin` channel. The channel
## Prerequisites
-- A working local nanobot reply:
-
-```bash
-nanobot agent -m "Hello!"
-```
+- A normal reply in your existing nanobot WebUI or CLI. If you have not reached that point, complete [Quick Start](../quick-start.md) first.
- A WeChat account that can complete QR-code login.
-## Install nanobot
+## Continue from your running instance
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-```
+If you are already chatting in the WebUI, keep it open and continue below. It has already started the gateway. To reopen it later, use the same installation's `nanobot webui` command; there is no need to install nanobot again.
+
+For terminal or server setup, use the manual configuration section below. Reuse the config/home and executable from your working instance. Docker users should use the [container commands](../deployment.md#docker-compose).
## Enable the WeChat channel
+Open **Channels → WeChat (Weixin)**, install support if prompted, and follow the QR connection flow using your WeChat account. Enable the channel, save, and follow any restart prompt. New private senders receive a pairing code until approved.
+
+<details>
+<summary>Manual configuration</summary>
+
Install the optional channel dependency:
```bash
@@ -56,21 +56,31 @@ nanobot channels login weixin
Use `--force` if you need to discard saved login state and authenticate again.
-## Run nanobot gateway
+</details>
-```bash
-nanobot channels status
-nanobot gateway
-```
+## Apply the settings
+
+In the WebUI, follow any restart prompt and keep the launcher running for the first test. You do not need to start another gateway. For unattended operation afterward, use [background or service mode](../cli-reference.md#gateway).
+
+For manual config changes, restart the existing gateway through its owning terminal, `nanobot gateway restart` for background mode, or its service/container supervisor. If none is running, start `nanobot gateway` and leave it running. Run diagnostic CLI commands in a separate terminal using the same installation and config.
## Test a message
-Send a private WeChat message to the bot. It should reply with a pairing code. Approve it from a trusted local surface:
+Send a private WeChat message to the bot. It should reply with a pairing code. Return to the WebUI pairing prompt and enter the code from your own private chat. Only a matching pending code is approved; do not enter another person's code. Then send your message again.
+
+<details>
+<summary>Terminal-only pairing</summary>
+
+In a separate local terminal, using the same instance:
```bash
nanobot agent -m "/pairing approve ABCD-EFGH"
```
+Replace the example code with your actual code.
+
+</details>
+
Send the message again after approval and watch gateway logs for the sender ID and reply.
## Security notes
diff --git a/docs/guides/whatsapp-ai-agent.md b/docs/guides/whatsapp-ai-agent.md
index 53e53a841..77e3394f8 100644
--- a/docs/guides/whatsapp-ai-agent.md
+++ b/docs/guides/whatsapp-ai-agent.md
@@ -11,24 +11,24 @@ This guide connects nanobot to WhatsApp through the `whatsapp` channel. The chan
## Prerequisites
-- A working local nanobot reply:
-
-```bash
-nanobot agent -m "Hello!"
-```
+- A normal reply in your existing nanobot WebUI or CLI. If you have not reached that point, complete [Quick Start](../quick-start.md) first.
- A WhatsApp account that can link a new device.
- A machine that can keep `nanobot gateway` running.
-## Install nanobot
+## Continue from your running instance
-```bash
-python -m pip install nanobot-ai
-nanobot onboard --wizard
-```
+If you are already chatting in the WebUI, keep it open and continue below. It has already started the gateway. To reopen it later, use the same installation's `nanobot webui` command; there is no need to install nanobot again.
+
+For terminal or server setup, use the manual configuration section below. Reuse the config/home and executable from your working instance. Docker users should use the [container commands](../deployment.md#docker-compose).
## Enable the WhatsApp channel
+Open **Channels → WhatsApp**, install support if prompted, and follow the QR connection flow. Scan the code from **WhatsApp → Settings → Linked Devices**. Enable the channel and save; choose mention-only group replies under **Advanced** for a first deployment. Follow any restart prompt.
+
+<details>
+<summary>Manual configuration</summary>
+
Install the optional channel dependency:
```bash
@@ -58,22 +58,32 @@ Merge this snippet into `~/.nanobot/config.json`:
Omitting `allowFrom` enables pairing-only mode for private chats. `groupPolicy` defaults to `"open"` in the channel, but `"mention"` is safer for a first deployment.
-## Run nanobot gateway
+</details>
-```bash
-nanobot channels status
-nanobot gateway
-```
+## Apply the settings
+
+In the WebUI, follow any restart prompt and keep the launcher running for the first test. You do not need to start another gateway. For unattended operation afterward, use [background or service mode](../cli-reference.md#gateway).
+
+For manual config changes, restart the existing gateway through its owning terminal, `nanobot gateway restart` for background mode, or its service/container supervisor. If none is running, start `nanobot gateway` and leave it running. Run diagnostic CLI commands in a separate terminal using the same installation and config.
## Test a message
-Send the bot a private WhatsApp message. It should return a pairing code. Approve it from a trusted local surface:
+Send the bot a private WhatsApp message. It should return a pairing code. Return to the WebUI pairing prompt and enter the code from your own private chat. Only a matching pending code is approved; do not enter another person's code. Then send your message again.
+
+<details>
+<summary>Terminal-only pairing</summary>
+
+In a separate local terminal, using the same instance:
```bash
nanobot agent -m "/pairing approve ABCD-EFGH"
```
-Send the message again after approval. The reply should use the same model and workspace as your local CLI check.
+Replace the example code with your actual code.
+
+</details>
+
+Send the message again after approval. Confirm that your private chat now receives a normal agent reply.
## Security notes
diff --git a/docs/image-generation.md b/docs/image-generation.md
index cfa346ae1..2748cdfee 100644
--- a/docs/image-generation.md
+++ b/docs/image-generation.md
@@ -2,18 +2,19 @@
nanobot can generate and edit images through the `generate_image` tool. Enable the tool in WebUI Settings, then ask for an image normally in chat; the agent decides when to call it and can keep iterating on generated images in the same conversation.
-The feature is disabled by default. Open **Settings → Image**, choose a configured provider and model, enable image generation, and save. The running gateway applies the change immediately. If that screen is not available in your installed version, use the manual config below.
+The feature is disabled by default. Open **Settings → Capabilities → Image generation**, choose a configured provider and model, enable image generation, and save. The running gateway applies the change immediately. If that screen is not available in your installed version, use the manual config below.
## Quick Setup
**WebUI**
-1. Add the image provider credential under **Settings → Models → Manage providers** if it is not already configured.
-2. Open **Settings → Image**.
+1. Add the image provider credential under **Settings → Models → Provider → Add provider** if it is not already configured.
+2. Open **Settings → Capabilities → Image generation**.
3. Select the provider and image model, then enable image generation.
4. Save and ask for a simple test image. If the gateway cannot apply the change live, WebUI will prompt you to restart it.
-**Manual config**
+<details>
+<summary>Manual configuration</summary>
This snippet uses the current built-in image-generation default so the JSON has concrete names. It is not a provider recommendation; replace `provider` and `model` with any supported image provider and model you intend to use.
@@ -34,6 +35,8 @@ This snippet uses the current built-in image-generation default so the JSON has
}
```
+</details>
+
See [Provider Notes](#provider-notes) for Custom, AIHubMix, MiniMax, Gemini, Ollama, StepFun, Zhipu, and ModelScope configuration examples.
> [!TIP]
@@ -90,10 +93,15 @@ Both camelCase and snake_case config keys are accepted, but docs use camelCase t
## Provider Notes
+For each provider below, add or edit its connection in **Settings → Models**, then choose the provider and image model in **Settings → Capabilities → Image generation**. Connection-specific headers, request bodies, and proxy settings are in the provider editor's **Advanced options**. The collapsed JSON examples are for manual deployments.
+
### OpenRouter
OpenRouter uses a chat-completions style image response. Configure:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -106,6 +114,8 @@ OpenRouter uses a chat-completions style image response. Configure:
}
```
+</details>
+
Use a model that supports image generation and image editing if you want reference-image edits.
### OpenAI Codex
@@ -138,6 +148,9 @@ POST /v1/images/generations
The response must include generated images in `data[].b64_json` or `data[].url`. Native prediction APIs, such as Replicate's `/v1/models/{owner}/{model}/predictions`, are not directly compatible unless you put an OpenAI-compatible gateway in front of them.
+<details>
+<summary>Manual configuration</summary>
+
Configure:
```json
@@ -158,6 +171,8 @@ Configure:
}
```
+</details>
+
The `apiBase` is required. The provider sends requests to `{apiBase}/images/generations` using the OpenAI Images API format with `response_format: "b64_json"`. The `apiKey` is optional for local or unauthenticated endpoints. Reference-image edits are not supported by the generic `custom` provider.
`extraBody` can adapt provider-specific quirks because it is merged last into the request body. Examples:
@@ -176,6 +191,9 @@ AIHubMix `gpt-image-2-free` is supported through AIHubMix's unified predictions
/v1/models/openai/gpt-image-2-free/predictions
```
+<details>
+<summary>Manual configuration</summary>
+
Configure:
```json
@@ -198,12 +216,17 @@ Configure:
}
```
+</details>
+
`quality: low` is optional. It can make free image models faster and less likely to time out, but it is not required for correctness.
### MiniMax
MiniMax `image-01` supports text-to-image and reference-image (subject reference) edits. Supported aspect ratios are `1:1`, `16:9`, `4:3`, `3:2`, `2:3`, `3:4`, `9:16`, and `21:9`.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -222,6 +245,8 @@ MiniMax `image-01` supports text-to-image and reference-image (subject reference
}
```
+</details>
+
### Gemini
nanobot supports two Gemini image generation model families via Google's Generative Language API:
@@ -233,6 +258,9 @@ nanobot supports two Gemini image generation model families via Google's Generat
For reference-image edits, use a Gemini Flash image model:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -250,12 +278,17 @@ For reference-image edits, use a Gemini Flash image model:
}
```
+</details>
+
Imagen 4 supports the aspect ratios `1:1`, `9:16`, `16:9`, `3:4`, and `4:3`. Unsupported ratios are ignored and the model uses its default. The `defaultImageSize` setting has no effect on Gemini models; sizing is controlled by `defaultAspectRatio` only. Reference images passed with an Imagen model are ignored (with a warning logged).
### Ollama
Ollama's experimental native image generation API works with local servers and hosted ollama.com models. Local access at `http://localhost:11434/api` does not require an API key; set `providers.ollama.apiKey` only when targeting `https://ollama.com/api`.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -275,6 +308,8 @@ Ollama's experimental native image generation API works with local servers and h
}
```
+</details>
+
Ollama maps `defaultAspectRatio` and `defaultImageSize` to native `width` and `height` values. Reference images are not supported by this integration.
### StepFun
@@ -283,6 +318,9 @@ StepFun (阶跃星辰) `step-image-edit-2` supports text-to-image generation. T
Supported aspect ratios: `1:1`, `16:9`, `9:16`, `3:4`, `4:3`. Sizes are specified as `WIDTHxHEIGHT` (e.g. `1024x1024`, `1280x800`, `800x1280`).
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -300,6 +338,8 @@ Supported aspect ratios: `1:1`, `16:9`, `9:16`, `3:4`, `4:3`. Sizes are specifi
}
```
+</details>
+
> [!NOTE]
> The StepFun provider reuses the existing `providers.stepfun` config block (the same one used for StepFun's LLM API). Set `providers.stepfun.apiKey` once and it is shared between text and image generation.
>
@@ -309,6 +349,9 @@ Supported aspect ratios: `1:1`, `16:9`, `9:16`, `3:4`, `4:3`. Sizes are specifi
StepPlan is StepFun's subscription tier and uses a different API base URL. The image generation endpoint path is the same — just override `apiBase`:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -327,6 +370,8 @@ StepPlan is StepFun's subscription tier and uses a different API base URL. The i
}
```
+</details>
+
`apiBase` takes precedence over the registry default, so with the StepPlan base URL configured, image requests are sent to `https://api.stepfun.ai/step_plan/v1/images/generations` — the same path prefix used for LLM calls. The API key is shared with the standard StepFun provider.
### Zhipu
@@ -335,6 +380,9 @@ Zhipu (智谱) `glm-image` model supports text-to-image generation. The API retu
Supported aspect ratios: `1:1`, `16:9`, `9:16`, `3:4`, `4:3`. Sizes can be specified as `WIDTHxHEIGHT` (e.g. `1280x1280`, `1728x960`) or using aspect ratio presets.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -352,6 +400,8 @@ Supported aspect ratios: `1:1`, `16:9`, `9:16`, `3:4`, `4:3`. Sizes can be speci
}
```
+</details>
+
Other supported models: `cogview-4`, `cogview-4-250304`, `cogview-3-flash`. Reference images are not supported by this integration.
### ModelScope
@@ -360,6 +410,9 @@ ModelScope (魔搭社区) API-Inference supports text-to-image generation and im
Supported aspect ratios: `1:1`, `16:9`, `9:16`, `3:4`, `4:3`. Sizes can be specified as `WIDTHxHEIGHT` (e.g. `1024x1024`, `1664x928`) or using aspect ratio presets.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -377,6 +430,8 @@ Supported aspect ratios: `1:1`, `16:9`, `9:16`, `3:4`, `4:3`. Sizes can be speci
}
```
+</details>
+
## Artifacts
Generated images are stored under the active nanobot instance's media directory:
@@ -429,7 +484,7 @@ Use the reference image. Keep the same robot and composition, change the palette
| Symptom | Check |
|---------|-------|
-| `generate_image` is not available | Enable image generation in **Settings → Image** and save. For manual config changes, restart the gateway |
+| `generate_image` is not available | Enable image generation in **Settings → Capabilities → Image generation** and save. For manual config changes, restart the gateway |
| Missing API key error | Configure `providers.<provider>.apiKey`; if using `${VAR_NAME}`, confirm the environment variable is visible to the gateway process |
| `unsupported image generation provider` | Use `openrouter`, `openai`, `openai_codex`, `custom`, `aihubmix`, `minimax`, `gemini`, `ollama`, `stepfun`, `zhipu`, or `modelscope` |
| AIHubMix says `Incorrect model ID` | Use `model: "gpt-image-2-free"`; nanobot expands it to the required `openai/gpt-image-2-free` model path internally |
diff --git a/docs/memory.md b/docs/memory.md
index 14ac173eb..af9004afd 100644
--- a/docs/memory.md
+++ b/docs/memory.md
@@ -35,7 +35,7 @@ Automatic compaction does not post lifecycle notices to built-in chat channels b
This file is:
-- append-only
+- appended to as conversations are compacted
- cursor-based
- optimized for machine consumption first, human inspection second
@@ -45,11 +45,13 @@ Each line is a JSON object:
{"cursor": 42, "timestamp": "2026-04-03 00:02", "content": "- User prefers dark mode\n- Decided to use PostgreSQL"}
```
+After scheduled or manual Dream runs, nanobot can prune the oldest entries already processed by Dream and atomically rewrite the file. The default retention target is 1000 entries; entries Dream has not processed are retained even when this exceeds the target. The journal is therefore not a permanent archive of every summary.
+
It is not the final memory. It is the material from which final memory is shaped.
### Stage 2: Dream
-`Dream` is the slower, more thoughtful layer. It runs on a cron schedule by default and can also be triggered manually.
+`Dream` is the slower, more thoughtful layer. It runs on a cron schedule while the gateway is running and Dream is enabled, and can also be triggered manually. A standalone Python SDK instance does not start this scheduler.
Dream reads:
@@ -76,12 +78,12 @@ workspace/
│ └── dream.md # Optional instructions for how Dream organizes memory
└── memory/
├── MEMORY.md # Project facts, decisions, and durable context
- ├── history.jsonl # Append-only history summaries
+ ├── history.jsonl # History summaries with bounded retention after Dream
├── .cursor # Consolidator write cursor
└── .dream_cursor # Dream consumption cursor
```
-A selected project may provide its own `AGENTS.md`, but project-local `SOUL.md`, `USER.md`, and `memory/` do not replace the agent-owned files above. This keeps one agent's profile and memory continuous while it works across projects. Use a separate configured agent workspace when identity or memory must be isolated.
+A selected project may provide its own `AGENTS.md`, but project-local `SOUL.md`, `USER.md`, and `memory/` do not replace the agent-owned files above. This keeps one agent's profile and memory continuous while it works across projects. Use a [separate configured agent workspace](multiple-instances.md) when identity or memory must be isolated. A new chat, SDK `session_key`, or selected project does not create separate long-term memory.
These files play different roles:
@@ -149,6 +151,22 @@ Memory is not hidden behind the curtain. Users can inspect and guide it.
These commands exist for a reason: automatic memory is powerful, but users should always retain the right to inspect, understand, and restore it.
+## Save and Check a Preference
+
+In your existing WebUI or TUI chat, send a specific preference, for example:
+
+```text
+For Acme release notes, use concise bullet points and British spelling.
+```
+
+To consolidate it now, send `/compact` and wait for its completion, then send `/dream` and wait for the completion message. Dream reads compacted history, so running `/dream` immediately after a short conversation without compaction may find nothing new. Model-based consolidation may decide that no durable change is needed.
+
+Use `/dream-log` to review what changed. Inspect `USER.md` and `memory/MEMORY.md` in the configured agent workspace with your local editor, or select that workspace before asking the agent to read them. A Restricted chat in another project may not have permission to read these files directly. A conversational acknowledgement alone does not confirm that a durable file changed. Start a new chat in the same instance and ask which release-note style is saved to check reuse.
+
+To correct a preference, state what should replace the old value, then repeat compaction, Dream, and inspection. You can also edit the durable files directly; review unprocessed history for old conflicting instructions. `/dream-restore` lists versions, and `/dream-restore <sha>` restores the memory state before that change, including other changes made in that version.
+
+For separate clients with private context, create separate [instances](multiple-instances.md). Labelling a fact with a client name helps organization but does not isolate access.
+
## Versioned Memory
After Dream changes long-term memory files, nanobot can record that change with `GitStore`.
@@ -185,6 +203,8 @@ Each workspace has its own guide. Changing this file does not affect other nanob
## Configuration
+Enable or disable Dream through **Settings → Capabilities → Memory consolidation**. Its frequency, cron override, and model override have no graphical controls; configure those fields directly below.
+
Dream is configured under `agents.defaults.dream`:
```json
diff --git a/docs/multiple-instances.md b/docs/multiple-instances.md
index c5a93d5cb..7c01a45ef 100644
--- a/docs/multiple-instances.md
+++ b/docs/multiple-instances.md
@@ -2,6 +2,10 @@
Use a separate home directory for each instance. Place `--home` before the subcommand; without it, nanobot uses `~/.nanobot`.
+Use this for separate clients, users, or personal/work agents that need independent configuration and long-term memory. A new topic or a different project folder inside one instance does not provide that separation.
+
+Separate homes and workspaces separate stored application data; they do not create an operating-system security boundary. Processes running as the same OS user may still access each other's files through unrestricted tools. For mutually untrusted users, use separate OS accounts or containers with separate mounts and credentials, and configure [tool restrictions](./configuration.md#security) for each instance.
+
## Quick Start
```bash
@@ -9,7 +13,7 @@ nanobot --home ~/.nanobot-work onboard
nanobot --home ~/.nanobot-work webui --port 8766 --gateway-port 18791
```
-Configure this instance's models and channels in WebUI Settings or `~/.nanobot-work/config.json`. Onboarding saves its default workspace as `~/.nanobot-work/workspace`.
+Configure this instance's models in **Settings → Models** and chat apps through **Channels** in the sidebar. Onboarding saves its default workspace as `~/.nanobot-work/workspace`. Use the collapsed examples in the [configuration reference](./configuration.md) for deployment-managed JSON.
Use the same home for other commands:
diff --git a/docs/openai-api.md b/docs/openai-api.md
index cefaa2497..86af82007 100644
--- a/docs/openai-api.md
+++ b/docs/openai-api.md
@@ -1,6 +1,8 @@
# Nanobot OpenAI-Compatible API: Run a Local Agent Behind /v1/chat/completions
-nanobot can expose a minimal OpenAI-compatible endpoint for local integrations:
+nanobot can expose a minimal OpenAI-compatible endpoint for local integrations. If your agent already replies in the WebUI, open **Settings → System**, configure and start the API service there. You do not need another installation or a separate `nanobot serve` process.
+
+For a terminal-managed API, use your existing configured installation:
```bash
nanobot plugins enable api
@@ -14,8 +16,13 @@ For setup help, see [`quick-start.md`](./quick-start.md), [`providers.md`](./pro
## Authentication
+For graphical setup, open **Settings → System**, find the API service, enter its host, port, and API key, and start it. Set a key before binding to a network interface. The config-file alternative is collapsed below.
+
Local-only `127.0.0.1` usage does not require an API key. If you bind the API server to all interfaces with `api.host: "0.0.0.0"` or `"::"`, nanobot requires `api.apiKey`; otherwise startup fails to avoid exposing an unauthenticated agent endpoint on the network.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"api": {
@@ -26,6 +33,8 @@ Local-only `127.0.0.1` usage does not require an API key. If you bind the API se
}
```
+</details>
+
When `api.apiKey` is set, send it as a Bearer token on API routes. The health endpoint remains unauthenticated so local probes and load balancers can still check process health.
```bash
@@ -35,24 +44,36 @@ curl http://127.0.0.1:8900/v1/models \
## Behavior
-- Session isolation: pass `"session_id"` in the request body to isolate conversations; omit for a shared default session (`api:default`)
+- Conversation history: pass `"session_id"` in the request body to select a conversation; omit for a shared default session (`api:default`). This is not user authentication or a separate workspace.
- Single-message input: each request must contain exactly one `user` message
- Fixed model: omit `model`, or pass the same model shown by `/v1/models`
- Streaming: set `stream=true` to receive Server-Sent Events (`text/event-stream`) with OpenAI-compatible delta chunks, terminated by `data: [DONE]`; omit or set `stream=false` for a single JSON response
- **File uploads**: supports images, PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx) via JSON base64 or `multipart/form-data` (max 10MB per file)
-- API requests run in the synthetic `api` channel, so the `message` tool does **not** automatically deliver to Telegram/Discord/etc. To proactively send to another chat, call `message` with an explicit `channel` and `chat_id` for an enabled channel.
+- API requests run in the synthetic `api` channel. Responses are returned to the HTTP client; the standalone API service does not deliver `message` tool calls to chat apps.
-Example tool call for cross-channel delivery from an API session:
+`nanobot serve` creates its own in-process message queue without starting chat-channel consumers. The API service started from **Settings → System** uses the same command. An explicit `channel` and `chat_id` can enqueue a tool message, but it does not cause platform delivery, even when that channel is enabled or a separate gateway is running. Do not treat the tool acknowledgement as a delivery receipt. Applications that need to forward an API result to Telegram, Discord, or another platform must handle that delivery separately.
-```json
-{
- "content": "Build finished successfully.",
- "channel": "telegram",
- "chat_id": "123456789"
-}
-```
+## Sessions, failures, and retries
+
+All callers use the same configured API key, agent, workspace, long-term memory, and tool permissions. Any authorized caller can select any `session_id`; the server does not bind it to a user identity. A distinct ID separates conversation history, not access to files or memory. Use [separate instances](./multiple-instances.md) for separate trust boundaries, or enforce user-to-session authorization in your own application before forwarding requests.
-If `channel` points to a channel that is not enabled in your config, nanobot will queue the outbound event but no platform delivery will occur.
+Requests with the same session ID are serialized within one API process. Different sessions can run concurrently and share workspace files; session locking does not make file changes transactional. Send one turn at a time per conversation when ordering matters.
+
+| Failure | Client-visible result |
+|---|---|
+| Missing or incorrect configured key | HTTP 401 |
+| Invalid request or wrong model | HTTP 400 |
+| Oversized or invalid upload | HTTP 413 |
+| Non-streaming execution timeout | HTTP 504 |
+| Unhandled non-streaming execution failure | HTTP 500 |
+
+These API error responses use `{"error":{"message":"...","type":"...","code":400}}`, with the status code for that failure. An HTTP 200 response can still contain a model or tool failure described in assistant text; it does not certify that the requested action succeeded.
+
+Once an SSE response has started, an execution failure or timeout closes it **without** a final `finish_reason: "stop"` chunk or `data: [DONE]`. There is no separate SSE error event. Treat a stream ending without `[DONE]` as incomplete, even if HTTP status was 200 or some text arrived.
+
+Execution timeout defaults to 120 seconds (`api.timeout`, or `nanobot serve --timeout`). It starts after acquiring the session lock, so waiting behind another request can make total request time longer. A client timeout or disconnect is not a reliable cancellation interface. A failed SSE write cancels its running task, but disconnect detection may wait for output; non-streaming work can continue after a client disconnects. Cancellation and timeout do not undo tool actions already performed.
+
+There is no request idempotency key or automatic deduplication. Retrying can repeat a message, file edit, or external action. Check the result before retrying side-effecting requests, and disable automatic client retries when duplicate actions would matter.
## Endpoints
@@ -62,8 +83,11 @@ If `channel` points to a channel that is not enabled in your config, nanobot wil
## curl
+The examples below use a local server. If you configured `api.apiKey`, set `NANOBOT_API_KEY` to that same value in the client shell; it is separate from your model provider key. The authorization header is ignored when the local server has no configured key.
+
```bash
curl http://127.0.0.1:8900/v1/chat/completions \
+ -H "Authorization: Bearer $NANOBOT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [{"role": "user", "content": "hi"}],
@@ -77,6 +101,7 @@ Send images inline using the OpenAI multimodal content format:
```bash
curl http://127.0.0.1:8900/v1/chat/completions \
+ -H "Authorization: Bearer $NANOBOT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [{"role": "user", "content": [
@@ -93,11 +118,13 @@ Upload any supported file type (images, PDF, Word, Excel, PPT) via multipart:
```bash
# Single file
curl http://127.0.0.1:8900/v1/chat/completions \
+ -H "Authorization: Bearer $NANOBOT_API_KEY" \
-F "message=Summarize this report" \
# Multiple files with session isolation
curl http://127.0.0.1:8900/v1/chat/completions \
+ -H "Authorization: Bearer $NANOBOT_API_KEY" \
-F "message=Compare these files" \
@@ -112,10 +139,13 @@ Supported file types:
## Python (`requests`)
```python
+import os
+
import requests
resp = requests.post(
"http://127.0.0.1:8900/v1/chat/completions",
+ headers={"Authorization": f"Bearer {os.environ.get('NANOBOT_API_KEY', '')}"},
json={
"messages": [{"role": "user", "content": "hi"}],
"session_id": "my-session", # optional: isolate conversation
@@ -128,16 +158,22 @@ print(resp.json()["choices"][0]["message"]["content"])
## Python (`openai`)
+`local-no-key` is only a client-library placeholder for a local server with no key configured. For an authenticated server, supply its actual API key. Discover the configured model instead of copying a provider-specific model ID.
+
```python
+import os
+
from openai import OpenAI
client = OpenAI(
base_url="http://127.0.0.1:8900/v1",
- api_key="dummy",
+ api_key=os.environ.get("NANOBOT_API_KEY") or "local-no-key",
+ max_retries=0, # A retry could repeat a tool action.
)
+model_id = client.models.list().data[0].id
resp = client.chat.completions.create(
- model="MiniMax-M2.7",
+ model=model_id,
messages=[{"role": "user", "content": "hi"}],
extra_body={"session_id": "my-session"}, # optional: isolate conversation
)
diff --git a/docs/provider-cookbook.md b/docs/provider-cookbook.md
index 085d8f1da..c88ef77b0 100644
--- a/docs/provider-cookbook.md
+++ b/docs/provider-cookbook.md
@@ -4,7 +4,7 @@ This page is for cases where you already know what you want to connect and need
If this is your first install and terminal commands are new to you, start with [`start-without-technical-background.md`](./start-without-technical-background.md). If you want the field-by-field explanation, read [`providers.md`](./providers.md) and then [`configuration.md#providers`](./configuration.md#providers).
-Most examples below are snippets to merge into `~/.nanobot/config.json`. Keep any existing sections you still need, and replace placeholder keys such as `${OPENROUTER_API_KEY}` with environment-variable references or real values only on your own machine.
+Use **Settings → Models** for the recipes below. The collapsed **Manual configuration** examples are snippets for headless deployments or configuration managed as code. Keep existing config sections when merging a snippet, and keep real credentials on your own machine.
Recipes are examples, not rankings. Pick the recipe that matches the credential, endpoint, and model ID you already intend to use.
@@ -27,12 +27,14 @@ Match the recipe to the credential or endpoint you already have:
## How to Use a Recipe
-1. Install nanobot and run `nanobot onboard` once so `~/.nanobot/config.json` exists. Use `nanobot onboard --wizard` if you prefer prompts over hand-editing JSON.
-2. Put secrets in environment variables when possible.
-3. Merge the recipe snippet into `~/.nanobot/config.json`.
-4. Run `nanobot status`.
-5. Run `nanobot agent -m "Hello!"`.
-6. If the CLI works, then connect WebUI, gateway, or chat apps.
+1. Install nanobot and open `nanobot webui`.
+2. Open **Settings → Models → New preset**. If **Convert to presets** appears, choose it first.
+3. Select the recipe's provider from **Provider**, or choose **Add provider** and save its credentials and endpoint.
+4. Select a model available to your account. Expand **Advanced options** if you need generation settings or an explicit request API.
+5. Save the preset and select it in the chat composer.
+6. Send `Hello!` and confirm a normal reply before connecting a chat app.
+
+For fallback recipes, create each preset first, then use **Enable preset** and arrange the order in **Settings → Models**. The first enabled preset is the primary; the others are fallbacks.
The active model should normally come from `agents.defaults.modelPreset`, and that name should point to an entry in `modelPresets`. Direct `agents.defaults.provider` and `agents.defaults.model` still work for older configs, but presets are easier to switch and easier to reuse as fallbacks.
@@ -60,8 +62,13 @@ Environment variables set this way apply only to the current terminal. For long-
## Recipe: OpenRouter Gateway
+Select OpenRouter in **Settings → Models → New preset**, add its API key through **Provider → Add provider** if needed, and choose a model available to your account. Save and select the preset in chat.
+
This recipe applies when one API key routes many hosted model families.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -86,6 +93,8 @@ This recipe applies when one API key routes many hosted model families.
}
```
+</details>
+
Verify:
```bash
@@ -97,10 +106,15 @@ If this fails with `401` or `unauthorized`, check that `OPENROUTER_API_KEY` is v
## Recipe: OpenCode Zen or Go
+In **Settings → Models → New preset**, choose OpenCode Zen or OpenCode Go to match your account, add its credential, select a model from that endpoint, and save. Select the preset in chat.
+
This recipe applies when your credential comes from OpenCode Zen or OpenCode Go. Both providers use `OPENCODE_API_KEY`; pick the provider block that matches the subscription or balance you want to use.
OpenCode Zen:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -125,8 +139,13 @@ OpenCode Zen:
}
```
+</details>
+
OpenCode Go:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -151,6 +170,8 @@ OpenCode Go:
}
```
+</details>
+
Verify:
```bash
@@ -162,8 +183,13 @@ OpenCode's docs list models across multiple endpoint types. The `opencode_zen` a
## Recipe: OpenAI Direct
+In **Settings → Models → New preset**, select OpenAI, add its API key, choose a model available to your account, and save. Leave request API selection on Auto unless your endpoint requires an explicit choice.
+
This recipe applies when you have an OpenAI API key and want to call OpenAI directly instead of through a gateway.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -188,6 +214,8 @@ This recipe applies when you have an OpenAI API key and want to call OpenAI dire
}
```
+</details>
+
Verify:
```bash
@@ -198,8 +226,13 @@ If your shell cannot use inline environment variables, set `OPENAI_API_KEY` firs
## Recipe: Anthropic Direct
+In **Settings → Models → New preset**, select Anthropic, add its API key, choose a Claude model available to your account, and save. Select the preset in chat.
+
This recipe applies when your key comes from Anthropic and your model name is an Anthropic model ID, not an OpenRouter model path.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -224,6 +257,8 @@ This recipe applies when your key comes from Anthropic and your model name is an
}
```
+</details>
+
Verify:
```bash
@@ -234,6 +269,9 @@ If you copied a model name such as `anthropic/claude-sonnet-4.5`, that is a gate
If you use an Anthropic-compatible proxy, keep the preset provider as `anthropic` and set `providers.anthropic.apiBase`:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -259,12 +297,19 @@ If you use an Anthropic-compatible proxy, keep the preset provider as `anthropic
}
```
+</details>
+
Do not configure Anthropic-compatible endpoints as arbitrary custom provider names; named custom providers use the OpenAI-compatible request format.
## Recipe: Kimi Coding Plan
+In **Settings → Models → New preset**, select Kimi Coding, add your Coding Plan key, choose `kimi-for-coding`, and save. Select the preset in chat.
+
This recipe applies when your key comes from Kimi's Coding Plan endpoint. Nanobot uses a dedicated `kimi_coding` provider for this Anthropic Messages API endpoint; do not configure it as a generic `custom` provider.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -288,6 +333,8 @@ This recipe applies when your key comes from Kimi's Coding Plan endpoint. Nanobo
}
```
+</details>
+
Verify:
```bash
@@ -299,8 +346,13 @@ The default base URL is `https://api.kimi.com/coding/v1`. This endpoint requires
## Recipe: Custom OpenAI-Compatible Provider
+In **Settings → Models → New preset → Provider → Add provider**, create a custom connection with the endpoint URL and any required key. Select its served model, save the preset, and select it in chat.
+
This recipe applies to an OpenAI-compatible service that is not a named nanobot provider.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -326,6 +378,8 @@ This recipe applies to an OpenAI-compatible service that is not a named nanobot
}
```
+</details>
+
Verify the endpoint before blaming nanobot:
```bash
@@ -337,6 +391,9 @@ nanobot agent -m "Hello!"
For multiple custom endpoints, do not overload the single `custom` block. Name each endpoint under `providers` and reference that same name from the preset:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -372,17 +429,26 @@ For multiple custom endpoints, do not overload the single `custom` block. Name e
}
```
+</details>
+
These custom names define direct connections: `apiBase` is required and `apiKey` is optional when the endpoint allows anonymous or placeholder credentials. Declare accepted protocols and a default with [`providers.<name>.api`](./configuration.md#custom-connection-apis). An Anthropic-compatible endpoint uses `supportedApis: ["anthropic_messages"]`; model presets can select any protocol within the connection declaration.
## Recipe: Ollama Local Model
-This recipe applies when Ollama is already installed and the model has been pulled locally.
+Follow the server preparation below, then open **Settings → Models → New preset**, select or add an Ollama connection at `http://localhost:11434/v1`, choose the downloaded model, and save. Select the preset in chat. If nanobot runs in a container or on another computer, `localhost` refers to that host; use an address reachable from nanobot.
+
+If Ollama is not installed, follow its [official quickstart](https://docs.ollama.com/quickstart) ([Linux setup](https://docs.ollama.com/linux)). Keep the Ollama app or service running. If no service is running, start `ollama serve` in a terminal and leave it open; do not start a second server when the app or system service already owns the port. In a separate terminal, download a model and confirm it is listed:
```bash
-ollama serve
ollama pull llama3.2
+ollama list
```
+Use that exact model name in nanobot. Downloading requires internet access and disk space; model inference then runs on the machine hosting Ollama.
+
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -407,21 +473,31 @@ ollama pull llama3.2
}
```
+</details>
+
Verify:
```bash
curl -sS http://localhost:11434/v1/models
-nanobot agent -m "Hello!"
```
+Send `Hello!` in the WebUI with the local preset selected. A CLI test uses its own session/default selection; to make the local preset the global primary, enable it and move it first in **Settings → Models**.
+
+Local inference does not disable network tools. For local-only document work, turn off **Web access**, avoid cloud fallbacks and remote integrations, and review shell access. Shell commands can still use the network even with a sandbox; a strict offline policy needs host/container network controls. See [local tool security](./guides/secure-local-ai-agent.md).
+
If you see `connection refused`, Ollama is not running or `apiBase` points to the wrong port. If every response is slow, try a smaller local model or lower `contextWindowTokens`.
If direct Ollama responses are fast but tool-using nanobot turns repeatedly evaluate thousands of prompt tokens, the model's chat template may be moving its tool definitions between requests. See [Improve Ollama Tool-Calling Prompt Cache Reuse](./guides/configure-ollama-prompt-cache.md) for a diagnostic procedure and an optional model-specific workaround.
## Recipe: vLLM or LM Studio
+Start your local model server, then use **Settings → Models → New preset** to add its connection with the local `/v1` endpoint and any required key. Enter the served model name, save, and select the preset in chat.
+
This recipe applies when a local server exposes an OpenAI-compatible `/v1` API.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -447,8 +523,13 @@ This recipe applies when a local server exposes an OpenAI-compatible `/v1` API.
}
```
+</details>
+
For LM Studio, use its local base URL and provider name:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -472,12 +553,19 @@ For LM Studio, use its local base URL and provider name:
}
```
+</details>
+
The config key can be `lmStudio` or `lm_studio`, but the preset provider should use the registry name `lm_studio`.
## Recipe: Fallback Presets
+Create each preset in **Settings → Models**, use **Enable preset**, and arrange the primary first with backups after it. Test each preset in chat before relying on the fallback order.
+
This recipe applies when one provider sometimes rate-limits, one model is expensive, or you want a local backup.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"modelPresets": {
@@ -512,6 +600,8 @@ This recipe applies when one provider sometimes rate-limits, one model is expens
}
```
+</details>
+
`fallbackModels` belongs under `agents.defaults`. String entries are preset names, not raw model names. nanobot tries the active preset first, then the fallback presets in order.
Keep fallback candidates realistic. If the local fallback has a smaller context window, nanobot must build context that fits the smallest window in the active chain.
@@ -550,6 +640,9 @@ Langfuse is not a model provider in `config.json`. It is configured through envi
Use this after you have more than one preset and are chatting through a supported channel.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"modelPresets": {
@@ -574,6 +667,8 @@ Use this after you have more than one preset and are chatting through a supporte
}
```
+</details>
+
In chat:
```text
diff --git a/docs/providers.md b/docs/providers.md
index 410cb4b4e..01d7ebafd 100644
--- a/docs/providers.md
+++ b/docs/providers.md
@@ -2,7 +2,7 @@
Use this page when the first reply fails because of provider/model mismatch, or when you want to adapt the concrete setup example to a different provider. If you already know which provider you want and only need a pasteable setup, use [`provider-cookbook.md`](./provider-cookbook.md).
-For normal local setup, open **Settings → Models → New preset**. Select your provider, or choose **Add provider** from the **Provider** menu. See [Configure Your Model](./quick-start.md#2-configure-your-model) for the steps. Use the JSON below for manual deployments, local endpoints, provider-specific fields, or diagnosis.
+For normal local setup, open **Settings → Models → New preset**. Select your provider, or choose **Add provider** from the **Provider** menu. See [Configure Your Model](./quick-start.md#2-configure-your-model) for the steps. Enter local endpoints and provider-specific connection fields in that editor; expand **Advanced options** when needed. Expand **Manual configuration** below for headless deployments, config-file management, or diagnosis.
The model picker fetches online catalogs for OpenAI Codex, xAI Grok, and GitHub Copilot. An explicit authorization failure hides the picker’s search and model list and offers **Sign in again** using the existing provider login flow. Successful WebUI sign-in clears the catalog cache and restores model selection. Existing presets, selected models, and unsaved preset details are preserved. Network, rate-limit, and service failures instead keep cached or built-in lists available, label them as potentially out of date, and offer **Refresh failed. Click to retry**. Manual model IDs remain available for these temporary failures. A successful chat may have used a fallback preset and does not prove that the selected provider's authorization is still valid. When a live chat uses a fallback model, a dismissible notice above the composer names that model and links to model settings. If the provider explicitly rejected OAuth credentials, the notice instead names the provider that needs a new login, with fallback completion as secondary information. Network errors, ordinary permission denials, and rate limits do not request reauthentication. The notice does not change your selected preset.
@@ -12,7 +12,7 @@ For every setup, answer three questions:
2. What model name does that provider expect?
3. Does the provider need `apiKey`, `apiBase`, OAuth login, cloud credentials, or only a local server URL?
-Prefer a named `modelPresets` entry for the model/provider pair, then select it with `agents.defaults.modelPreset`. Direct `agents.defaults.provider` and `agents.defaults.model` still work for existing configs, but presets make runtime `/model` switching and fallback chains clearer. Pin `provider` inside the preset while setting up; you can switch back to `"auto"` later.
+Prefer a named preset created in **Settings → Models**, then select it in the chat composer. Direct `agents.defaults.provider` and `agents.defaults.model` still work for existing configs, but presets make runtime `/model` switching and fallback chains clearer. Pin `provider` inside the preset while setting up; you can switch back to `"auto"` later.
## Choose a Provider Without Guessing
@@ -24,11 +24,16 @@ The docs show concrete provider names so the JSON is copyable, not because nanob
| An OpenCode Zen or Go key | `providers.opencodeZen.apiKey` or `providers.opencodeGo.apiKey`, then a preset with `provider: "opencode_zen"` or `provider: "opencode_go"`. |
| A company proxy or regional endpoint | The matching provider block plus `apiBase` if the proxy gives you a URL. |
| A local OpenAI-compatible server | A local provider block such as `ollama`, `vllm`, `lmStudio`, or `custom`, usually with `apiBase`. |
-| An OAuth-based account | Run the matching `nanobot provider login ...` command, then select that provider explicitly in a preset. |
-| No provider yet | Pick one outside nanobot based on account access, pricing, regional availability, privacy requirements, and the model IDs you need. Then come back with its key and model ID. |
+| An OAuth-based account | Choose the provider in **Settings → Models**, complete its sign-in flow, and select it explicitly in a preset. |
+| No provider yet | Follow [Prepare your model details](./start-without-technical-background.md#2-prepare-your-model-details) for an API account example, or the [Ollama recipe](./provider-cookbook.md#recipe-ollama-local-model) for local models. Check account access, pricing, regional availability, and privacy requirements before choosing. |
## Minimal Shape
+Create and select a preset through **Settings → Models** as described above. The JSON alternative shows where those values are stored.
+
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -53,6 +58,8 @@ The docs show concrete provider names so the JSON is copyable, not because nanob
}
```
+</details>
+
The provider config gives nanobot credentials and endpoint details. The model preset names the provider/model pair. The agent defaults choose which named preset to use for normal turns. Replace the example provider and model together; mixing an API key from one provider with a model ID from another is the most common first-run failure.
## Provider, Model, API Key, and Base URL
@@ -83,6 +90,9 @@ Preparation preserves each adapter's model and API capability rules. When automa
Gateway-style setup for model IDs served through OpenRouter.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -106,10 +116,15 @@ Gateway-style setup for model IDs served through OpenRouter.
}
```
+</details>
+
Use the model ID exactly as OpenRouter lists it.
To opt into OpenRouter server-managed search and fetch, add:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -125,12 +140,17 @@ To opt into OpenRouter server-managed search and fetch, add:
}
```
+</details>
+
Chat Completions-compatible OpenRouter [server tools](https://openrouter.ai/docs/guides/features/server-tools), such as those above, are appended to nanobot's generated functions. This keeps unrelated local tools such as `write_file` available in the same request. Responses-only server tools require an API surface that the OpenRouter provider does not currently enable.
### OrcaRouter Gateway
[OrcaRouter](https://www.orcarouter.ai) is an OpenAI-compatible model routing gateway. Configure the built-in `orcarouter` provider and use a model ID from OrcaRouter's catalog:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -154,12 +174,17 @@ Chat Completions-compatible OpenRouter [server tools](https://openrouter.ai/docs
}
```
+</details>
+
Use the model ID exactly as OrcaRouter lists it. `orcarouter/auto` routes to a suitable upstream automatically; explicit IDs such as `anthropic/claude-sonnet-4.6` or `openai/gpt-5` are also accepted. OrcaRouter API keys start with `sk-orca-`. The WebUI can load the account's model catalog after the API key is saved under **Settings → Models**.
### Eden AI Gateway
Eden AI exposes an OpenAI-compatible chat-completions endpoint at `https://api.edenai.run/v3`. Configure the built-in `edenai` provider and use the full `provider/model` identifier listed by Eden AI:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -182,12 +207,17 @@ Eden AI exposes an OpenAI-compatible chat-completions endpoint at `https://api.e
}
```
+</details>
+
Nanobot sends the model ID unchanged, including its provider prefix. Use Eden AI's [model listing](https://www.edenai.co/docs/v3/llms/listing-models) to choose a currently available model. The WebUI can also load that catalog after the Eden AI API key is saved under **Settings → Models**.
### OpenCode Zen and Go
OpenCode Zen and OpenCode Go are OpenCode-managed gateways for coding-agent models. They share `OPENCODE_API_KEY`, but use separate provider config keys and default base URLs in nanobot.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -211,8 +241,13 @@ OpenCode Zen and OpenCode Go are OpenCode-managed gateways for coding-agent mode
}
```
+</details>
+
For OpenCode Go, switch the provider block and preset:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -231,10 +266,15 @@ For OpenCode Go, switch the provider block and preset:
}
```
+</details>
+
OpenCode documents model IDs with `opencode/<model-id>` for Zen and `opencode-go/<model-id>` for Go. nanobot accepts those prefixes and strips them before sending the request to OpenCode. Use model IDs that OpenCode lists under the `chat/completions` endpoint; models listed only under `responses`, `messages`, or provider-specific endpoints are not handled by this OpenAI-compatible provider path.
### Anthropic Direct
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -258,10 +298,15 @@ OpenCode documents model IDs with `opencode/<model-id>` for Zen and `opencode-go
}
```
+</details>
+
Anthropic direct uses the native Anthropic provider. Do not use an OpenRouter model ID unless the provider is OpenRouter.
If you use an Anthropic-compatible proxy, keep the provider as `anthropic` and override `apiBase`:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -279,10 +324,15 @@ If you use an Anthropic-compatible proxy, keep the provider as `anthropic` and o
}
```
+</details>
+
For a named custom provider serving Anthropic Messages, set `providers.<name>.api.supportedApis` to `["anthropic_messages"]`. Auto presets then use Messages with that connection's credentials and endpoint.
### OpenAI Direct
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -306,6 +356,8 @@ For a named custom provider serving Anthropic Messages, set `providers.<name>.ap
}
```
+</details>
+
Replace the model with a model ID available to your account. Leave API selection on Auto unless you need to choose Chat Completions or Responses in the preset's **Advanced options**. See [preset API settings](./configuration.md#preset-request-api) for WebUI and JSON configuration. `providers.openai.api` sets the connection default; explicit presets override it. If your configuration still uses `apiType`, follow the [migration instructions](./configuration.md#legacy-openai-api-selector-migration).
Direct OpenAI Responses, OpenAI Codex, Azure OpenAI Responses, and eligible GitHub Copilot models can retain server-provided conversation state; [native context compaction](./configuration.md#responses-state-and-compaction) depends on provider support. The WebUI offers switches for OpenAI web search, Codex Fast mode, and Grok X Search.
@@ -318,6 +370,9 @@ The `deepseek-flash` alias uses Responses automatically at `https://api.deepseek
The `custom` provider fits one OpenAI-compatible endpoint that is not represented by a named provider.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -342,10 +397,15 @@ The `custom` provider fits one OpenAI-compatible endpoint that is not represente
}
```
+</details>
+
`custom` does not infer a default base URL. Set `apiBase`.
If you have more than one custom OpenAI-compatible endpoint, give each endpoint its own provider key under `providers` and use that same key in the model preset. The key can be a name that makes sense in your environment, such as `companyProxy`, `tenant-a`, or `dev-local`.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -379,6 +439,8 @@ If you have more than one custom OpenAI-compatible endpoint, give each endpoint
}
```
+</details>
+
Custom provider keys define direct connections. Without an API declaration, they use OpenAI-compatible Chat Completions. `apiBase` is required because nanobot cannot know the endpoint URL. `apiKey` is optional for local servers or private proxies that do not require one. Choose a name that does not conflict with a built-in provider name or alias, such as `openai`, `openai-codex`, `github-copilot`, or `lm-studio`. Declare the accepted protocols under `api` as described in [connection request APIs](./configuration.md#custom-connection-apis).
If your custom endpoint documents a nonstandard thinking toggle, set `providers.<name>.thinkingStyle` to `thinking_type`, `enable_thinking`, or `reasoning_split`; nanobot then maps `reasoningEffort` onto that provider-specific request body. Leave it unset for ordinary OpenAI-compatible endpoints.
@@ -389,6 +451,9 @@ ModelScope (魔搭社区) exposes an OpenAI-compatible LLM endpoint plus a separ
Create a ModelScope [access token](https://modelscope.cn/my/myaccesstoken), then choose a model whose page exposes API-Inference. The example below uses [`Qwen/Qwen3-32B`](https://modelscope.cn/models/Qwen/Qwen3-32B); hosted availability and quotas are controlled by ModelScope. See the official [API-Inference guide](https://modelscope.cn/docs/model-service/API-Inference/intro) for current service details.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -412,10 +477,15 @@ Create a ModelScope [access token](https://modelscope.cn/my/myaccesstoken), then
}
```
+</details>
+
Use an inference-enabled model ID exactly as ModelScope publishes it (usually `Namespace/model-name`). The default base URL is `https://api-inference.modelscope.cn/v1`; override `providers.modelscope.apiBase` only if your account routes through a different host. Chat model IDs may optionally be prefixed with `modelscope/`; nanobot strips that routing prefix before sending the request.
ModelScope image generation reuses the same provider key but is configured under `tools.imageGeneration`, not in a model preset:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -428,11 +498,16 @@ ModelScope image generation reuses the same provider key but is configured under
}
```
+</details>
+
Use the image model's exact ModelScope ID without a leading `modelscope/`; the image client sends this value unchanged and handles ModelScope's async submit/poll flow. The example uses [`Qwen/Qwen-Image-2512`](https://modelscope.cn/models/Qwen/Qwen-Image-2512). See [Image Generation](./image-generation.md#modelscope) for supported sizes, aspect ratios, and the complete provider configuration.
### Ollama
-Start Ollama separately, then point nanobot at the OpenAI-compatible endpoint.
+Prepare Ollama using the [local model recipe](./provider-cookbook.md#recipe-ollama-local-model), then point nanobot at its OpenAI-compatible endpoint.
+
+<details>
+<summary>Manual configuration</summary>
```json
{
@@ -457,12 +532,17 @@ Start Ollama separately, then point nanobot at the OpenAI-compatible endpoint.
}
```
+</details>
+
Most Ollama setups do not require an API key.
Ollama renders the OpenAI-compatible messages and tools through each model's chat template. If ordinary model responses are fast but tool-using turns show low prompt cache reuse, diagnose the rendered template before changing nanobot's context or memory settings. The [Ollama prompt-cache guide](./guides/configure-ollama-prompt-cache.md) explains the log pattern and a tested `llama3.1:8b` workaround.
### vLLM or Other Local OpenAI-Compatible Server
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -487,10 +567,15 @@ Ollama renders the OpenAI-compatible messages and tools through each model's cha
}
```
+</details>
+
Some OpenAI-compatible local servers require any non-empty API key even when they do not validate it.
### LM Studio
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -514,12 +599,17 @@ Some OpenAI-compatible local servers require any non-empty API key even when the
}
```
+</details>
+
Config keys may be camelCase or snake_case. Provider names in model presets should use the registry name, such as `lm_studio`.
### AWS Bedrock
Bedrock can use the AWS credential chain, profile, region, or Bedrock bearer token depending on your AWS setup.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"providers": {
@@ -544,6 +634,8 @@ Bedrock can use the AWS credential chain, profile, region, or Bedrock bearer tok
}
```
+</details>
+
See [`configuration.md#providers`](./configuration.md#providers) for Bedrock-specific notes.
### OAuth Providers
@@ -612,6 +704,9 @@ Pin `provider` in presets when using gateway catalog IDs such as `anthropic/clau
Model presets are the recommended model configuration surface. Use them when you want named model choices, runtime `/model` switching, or reusable fallback targets.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"modelPresets": {
@@ -638,12 +733,17 @@ Model presets are the recommended model configuration surface. Use them when you
}
```
+</details>
+
The preset name `default` is reserved for the implicit `agents.defaults` settings. Do not define `modelPresets.default`; use `/model default` to return to the direct `agents.defaults.*` fields in older configs.
## Fallback Models
Fallbacks are useful for transient provider failures, rate limits, or model availability issues. Keep fallbacks compatible with the task size and tool use. Prefer fallback presets so each candidate has a name and a complete provider, model, generation, and context-window configuration.
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"modelPresets": {
@@ -678,10 +778,15 @@ Fallbacks are useful for transient provider failures, rate limits, or model avai
}
```
+</details>
+
String entries in `fallbackModels` are preset names, not raw model names. nanobot tries them in order after the active preset. Each fallback preset uses its own `provider`, `model`, `maxTokens`, `contextWindowTokens`, `temperature`, and optional `reasoningEffort`.
Use inline fallback objects only when a model is not worth naming as a preset:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"modelPresets": {
@@ -708,6 +813,8 @@ Use inline fallback objects only when a model is not worth naming as a preset:
}
```
+</details>
+
`fallbackModels` belongs under `agents.defaults`, not inside each preset. If fallback candidates use smaller context windows, nanobot builds context using the smallest window in the active chain so every candidate can receive the same prompt. See [`configuration.md#model-fallbacks`](./configuration.md#model-fallbacks) for failure conditions.
## Quick Checks
diff --git a/docs/python-sdk.md b/docs/python-sdk.md
index 20b794562..649012ba7 100644
--- a/docs/python-sdk.md
+++ b/docs/python-sdk.md
@@ -30,19 +30,7 @@ python -m pip install nanobot-ai
`Nanobot.from_config()` reuses your normal `~/.nanobot/config.json` and `~/.nanobot/workspace/`. Provider, model, tools, memory, and session behavior match the CLI unless you override them. For the difference between config and workspace, see [Concepts: Config vs Workspace](concepts.md#config-vs-workspace).
-Before writing SDK code, run the same first-run checks from the main [Install and Quick Start](quick-start.md):
-
-```bash
-nanobot status
-```
-
-`nanobot status` should show the config path, workspace path, active model or preset, and provider summary. Then send one real message:
-
-```bash
-nanobot agent -m "Hello!"
-```
-
-A normal assistant reply means install, config, provider/model selection, and workspace access are all usable. Once that works, the SDK should see the same runtime.
+If you have already received a normal reply in the WebUI, use that saved configuration directly. For a separate Python environment, `nanobot status` shows which config, workspace, and model the SDK will load.
## 5-Minute Quick Start
@@ -67,6 +55,17 @@ Use `async with` when possible so tool connections and background cleanup are cl
The SDK is async-first because agent runs may stream tokens, execute tools, and wait on external services. In a normal Python script, wrap your async function with `asyncio.run(...)` as shown above. In a notebook or another async app, call `await bot.run(...)` directly from your existing event loop.
+The default agent workspace comes from config, not the notebook's current directory. For a notebook that should use its current folder as both file workspace and agent state, choose it explicitly:
+
+```python
+from pathlib import Path
+
+async with Nanobot.from_config(workspace=Path.cwd()) as bot:
+ result = await bot.run("List the files in this workspace.")
+```
+
+This also places memory and skills in that workspace. Use a separate configured instance when notebook experiments must not share existing agent state.
+
### Inspect What Happened
`bot.run(...)` returns a `RunResult`, not just a string:
@@ -82,7 +81,7 @@ print(result.stop_reason) # why the run stopped
### Continue A Conversation
-Use a `session_key` when you want history to carry across turns. Different session keys are isolated from each other:
+Use a `session_key` when you want history to carry across turns. Different session keys keep separate conversation histories:
```python
await bot.run("My name is Alice.", session_key="user:alice")
@@ -91,7 +90,7 @@ result = await bot.run("What is my name?", session_key="user:alice")
print(result.content)
```
-This is the SDK equivalent of giving each user, task, eval case, or workflow its own conversation thread.
+This gives each task or workflow its own conversation thread. Keys do not isolate workspace files, tools, credentials, or long-term memory: sessions in one agent workspace share `USER.md`, `SOUL.md`, and `memory/MEMORY.md`. For separate users or tenants, use separate configured instances and appropriate process/file permissions; see [Multiple Instances](multiple-instances.md).
### Stream A Long Answer
@@ -109,7 +108,7 @@ Streaming returns structured events, so you can also observe tool calls, reasoni
## Complete Starter Script
-Save this as `sdk_demo.py` after `nanobot agent -m "Hello!"` works:
+Save this as `sdk_demo.py` after your configured model has returned a normal reply:
```python
import asyncio
@@ -260,7 +259,7 @@ result = await bot.run("Think deeply about this bug", model_preset="reasoning")
`model` and `model_preset` are mutually exclusive.
-For first setup, prefer named presets in `config.json`. Mixing an API key from one provider with a model ID from another is the most common first-run failure. For the exact difference between `provider`, `model`, `apiKey`, and `apiBase`, see [Providers: Provider, Model, API Key, and Base URL](providers.md#provider-model-api-key-and-base-url). If a run fails before the SDK does anything interesting, confirm the same provider and model work with `nanobot agent -m "Hello!"` first.
+For first setup, create named presets in **Settings → Models**; the SDK reads those saved presets from `config.json`. Mixing an API key from one provider with a model ID from another is the most common first-run failure. For the exact difference between `provider`, `model`, `apiKey`, and `apiBase`, see [Providers: Provider, Model, API Key, and Base URL](providers.md#provider-model-api-key-and-base-url). If a run fails before the SDK does anything interesting, confirm the same provider and model work with `nanobot agent -m "Hello!"` first.
### Isolate conversations with `session_key`
@@ -381,6 +380,23 @@ result = await bot.run(
print(result.content)
```
+### Persist memory in a short-lived script
+
+Saved session history and curated long-term memory are different. The SDK does not start the gateway scheduler, so creating or closing `Nanobot` does not schedule Dream. Compaction archives a conversation into `memory/history.jsonl`; it does not itself update `USER.md` or `memory/MEMORY.md`.
+
+Before closing a script that should contribute material to Dream:
+
+```python
+async with Nanobot.from_config() as bot:
+ await bot.run("For release notes, use concise bullet points.", session_key="sdk:notes")
+ await bot.runtime.compact_session("sdk:notes")
+ print(bot.memory.read_history(session_key="sdk:notes"))
+```
+
+Then use `/dream` in a running WebUI or TUI connected to the same configured agent workspace, wait for completion, and inspect `/dream-log`. Scheduled Dream also processes this archive while the matching gateway runs and Dream is enabled. `await bot.run("/dream")` only returns the command acknowledgement; it is not an awaited Dream-completion API for short-lived scripts.
+
+For application-owned durable text, `bot.memory.write(text)` writes `memory/MEMORY.md` directly and `bot.memory.read()` reads it back. Writing replaces the whole file; it does not merge preferences or create a Dream audit entry. See [Memory](memory.md) for review and correction workflows.
+
### Attach hooks for observability
Hooks are an advanced escape hatch. Use them when you want custom logging, metrics, tracing, or output post-processing without modifying nanobot internals:
diff --git a/docs/quick-start.md b/docs/quick-start.md
index 184dedc0e..54d073354 100644
--- a/docs/quick-start.md
+++ b/docs/quick-start.md
@@ -114,14 +114,26 @@ 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`.
-## Choose One Next Step
+## Continue with nanobot
-After the first reply works, add one capability and test again:
+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:
+
+```text
+$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](./webui.md) |
-| Connect a chat platform | Open **Settings → Channels**, then use [Chat Apps](./chat-apps.md) for platform prerequisites |
+| Connect a chat platform | Open **Channels**, then use [Chat Apps](./chat-apps.md) for platform prerequisites |
| Change or add a model | Open **Settings → Models**; use the [Provider Cookbook](./provider-cookbook.md) for a recipe |
| Add web search, voice, or image generation | Use the matching WebUI Settings page, then consult [Configuration](./configuration.md) for advanced fields |
| Add an App or MCP integration | Open **Apps** or follow [Configure MCP Tools](./guides/configure-mcp-tools.md) |
@@ -180,6 +192,9 @@ On Windows, the managed-environment form is `& "$HOME\.nanobot\venv\Scripts\pyth
## Manual Configuration Fallback
+<details>
+<summary>Manual configuration</summary>
+
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:
@@ -208,6 +223,8 @@ A generic OpenAI-compatible setup has this shape:
Replace the provider, endpoint, and model together. Do not pair a credential from one service with a model ID from another. See [Provider Cookbook](./provider-cookbook.md) for hosted, OAuth, company, and local examples, and [Configuration](./configuration.md) for exact fields.
+</details>
+
## Updating
Upgrade with the same method you used to install:
@@ -248,6 +265,6 @@ nanobot agent -m "Hello!"
| `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 **Settings → Channels**, then run `nanobot channels status` |
+| WebUI works but a chat app does not | Check **Channels**, then run `nanobot channels status` |
Continue with the ordered [Troubleshooting guide](./troubleshooting.md) if the cause is still unclear.
diff --git a/docs/start-without-technical-background.md b/docs/start-without-technical-background.md
index bbeaac0c7..aa5776d02 100644
--- a/docs/start-without-technical-background.md
+++ b/docs/start-without-technical-background.md
@@ -45,7 +45,18 @@ The result should start with `Python 3.11` or a newer number. If the command is
## 2. Prepare Your Model Details
-nanobot does not create an AI provider account for you. Before setup, have these details nearby:
+A chat website account is not automatically an API credential. nanobot needs a supported provider connection: an API key, a supported sign-in flow, or a local model server. Check the chosen service's billing and available models before using it.
+
+If you do not have a provider yet, here is one API-based example:
+
+1. Create an account at [OpenRouter](https://openrouter.ai/).
+2. Open its [API keys page](https://openrouter.ai/settings/keys) and create a key. Keep it private; you will paste it into nanobot's provider form.
+3. Choose a model from the [model catalog](https://openrouter.ai/models), 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](https://openrouter.ai/docs/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](./provider-cookbook.md#recipe-ollama-local-model) 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.
@@ -97,7 +108,7 @@ On SSH, a computer without a desktop, an existing configuration, or an older nan
## 5. Get the First Reply
-Leave the WebUI terminal open. If the browser did not open automatically, visit `http://127.0.0.1:8765`.
+Leave the WebUI terminal open. 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.
Send this message:
@@ -111,23 +122,35 @@ The first-run address is local to your computer. It is not automatically availab
## 6. Add One Thing at a Time
-Do not configure every feature immediately. Choose one next goal:
+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](./quick-start.md#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 → Manage providers** |
-| Connect Telegram, Discord, Slack, Feishu, WeChat, or another chat app | Open **Settings → Channels**, choose the platform, and follow its connection steps |
+| 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 | Start a new chat, choose the project workspace, and review the access setting before sending the task |
+| Work with project files | Follow [Your first file task](#your-first-file-task), then see [Workspace and Access](./webui.md#workspace-and-access) |
-Repository docs show the current development version. If your stable package does not yet show **Settings → Channels**, use the [Chat Apps guide](./chat-apps.md) or update to a release that includes it.
+Repository docs show the current development version. If your stable package does not yet show **Channels**, use the [Chat Apps guide](./chat-apps.md) 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 return to the terminal, press `Ctrl+C`, and run `nanobot webui` again.
For a chat platform's account, bot, token, or permission prerequisites, use the [Chat Apps guide](./chat-apps.md). For local models and provider-specific recipes, use the [Provider Cookbook](./provider-cookbook.md).
+## 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](./webui.md#apps).
+
+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](./multiple-instances.md).
+
## If Something Fails
Run these commands one at a time:
@@ -143,7 +166,7 @@ nanobot agent -m "Hello!"
| `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 | Open `http://127.0.0.1:8765` yourself and keep the terminal running |
+| Browser does not open | Copy the complete login link printed by the launcher, including the fragment after `#`, and keep the terminal running |
| 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 |
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 8c6ab164d..a6cfe7848 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -33,18 +33,11 @@ If `nanobot agent -m "Hello!"` fails, fix that before debugging WebUI, Telegram,
## Empty topics after a WebUI restart
-The Restart button in WebUI settings does not create a conversation or add messages
-to an existing conversation. Reopening WebUI or reconnecting to the gateway also
-does not save a topic until a message or another session action creates it.
+The Restart button in WebUI settings does not create a conversation or add messages to an existing conversation. Reopening WebUI or reconnecting to the gateway also does not save a topic until a message or another session action creates it.
-Older gateway versions could save an empty topic when the Restart button had no
-current chat. Update the gateway to stop creating these topics. Existing topics
-are not deleted by the update; check their contents before removing them. A typed
-`/restart` command remains part of that chat's display history.
+Older gateway versions could save an empty topic when the Restart button had no current chat. Update the gateway to stop creating these topics. Existing topics are not deleted by the update; check their contents before removing them. A typed `/restart` command remains part of that chat's display history.
-If settings stay disabled after a restart while another tab has reconnected,
-reload the affected page. Updated WebUI clients track restart completion per tab,
-so one tab cannot leave another tab waiting by clearing the shared restart marker.
+If settings stay disabled after a restart while another tab has reconnected, reload the affected page. Updated WebUI clients track restart completion per tab, so one tab cannot leave another tab waiting by clearing the shared restart marker.
## Session storage overlaps the workspace
@@ -101,7 +94,7 @@ Use the same Python command for install checks and module fallback. On macOS/Lin
| `curl: command not found` | The macOS/Linux one-command installer could not download the script. Install curl, or use a manual isolated install such as `uv tool install nanobot-ai` or `pipx install nanobot-ai`. |
| `irm` is not recognized | PowerShell could not run the download helper. Use manual install: `uv tool install nanobot-ai`, `pipx install nanobot-ai`, or `py -m pip install nanobot-ai` inside an environment you control. |
| Could not download `raw.githubusercontent.com` | Your network, proxy, or firewall blocked the installer script download. Use manual install from PyPI, or configure your proxy and rerun the command. |
-| `nanobot: command not found` | Use the module form, for example `python -m nanobot ...`, `python3 -m nanobot ...`, or `py -m nanobot ...`. Reinstall with the same Python command, or add that Python's scripts directory to `PATH`. |
+| `nanobot: command not found` | With the recommended installer, reuse its printed full command; with uv/pipx, use `uv tool run --from nanobot-ai nanobot ...` / `pipx run --spec nanobot-ai nanobot ...`. For a pip install, use `<installing-python> -m nanobot ...` from that same environment. A system `python` or `py` may not contain the isolated installation. |
| `No module named nanobot` | You are running a different Python than the one used for installation. Run `python -m pip show nanobot-ai`, `python3 -m pip show nanobot-ai`, or `py -m pip show nanobot-ai`, matching the command that installed nanobot. |
| `pip is not available` | When the installer uses a virtual environment, it tries `python -m ensurepip --upgrade`. If that fails, install pip for that Python, or use a Python installer/distribution that includes pip. |
| `externally-managed-environment` | Your system Python blocks global pip installs. Use the one-command installer, `uv tool install nanobot-ai`, `pipx install nanobot-ai`, or create a virtual environment; do not add `--break-system-packages` for nanobot. |
@@ -262,6 +255,11 @@ For a system-level or custom service, use `sudo systemctl edit <unit>` instead.
## WebUI Problems
+Run `nanobot webui` to prepare the local WebSocket channel and open the browser. Finish model setup in **Settings → Models**.
+
+<details>
+<summary>Manual WebSocket configuration</summary>
+
The packaged WebUI is served by the WebSocket channel.
Minimal config:
@@ -288,6 +286,8 @@ Open:
http://127.0.0.1:8765
```
+</details>
+
For first access, copy the complete login link printed by `nanobot webui`, including the fragment after `#`. In WSL, open that link in your Windows browser if automatic opening fails. The plain page address does not sign in a new browser.
If accessing from another device, bind the WebSocket channel to `0.0.0.0` and set `token` or `tokenIssueSecret`. The WebSocket channel refuses public binds without a token or token issue secret.
@@ -316,7 +316,7 @@ Then check:
|---|---|
| Bot never replies | Gateway is not running, the channel is not enabled, or the bot/app token is wrong. |
| Unknown sender ignored | Configure `allowFrom`, pairing, or the channel-specific allow list. |
-| Telegram shows a saved configuration but cannot complete a live check | The token is saved. Confirm the gateway can reach `api.telegram.org`, or open **Settings → Channels → Telegram → Advanced → Network proxy** and enter an HTTP or SOCKS proxy. |
+| Telegram shows a saved configuration but cannot complete a live check | The token is saved. Confirm the gateway can reach `api.telegram.org`, or open **Channels → Telegram → Advanced → Network proxy** and enter an HTTP or SOCKS proxy. |
| Telegram rejects the token | Copy the current token from BotFather or regenerate it. |
| Telegram receives no messages | Confirm the channel is enabled, the gateway is running, and the sender is paired or listed in `allowFrom`. |
| Discord replies missing | Enable Message Content intent and invite the bot with the required permissions. |
diff --git a/docs/websocket.md b/docs/websocket.md
index ce5de191e..8d0d212c2 100644
--- a/docs/websocket.md
+++ b/docs/websocket.md
@@ -16,6 +16,8 @@ Nanobot can act as a WebSocket server, allowing external clients (web apps, CLIs
### 1. Configure
+For normal browser setup, run `nanobot webui`; the launcher prepares the local channel and opens the WebUI. Configure models in **Settings → Models**. The listener and protocol fields below are for custom clients and deployments and have no graphical editor.
+
The WebSocket channel is enabled by default. Add only the fields you want to override under `channels.websocket`:
```json
@@ -25,6 +27,7 @@ The WebSocket channel is enabled by default. Add only the fields you want to ove
"host": "127.0.0.1",
"port": 8765,
"path": "/",
+ "tokenIssuePath": "/auth/token",
"tokenIssueSecret": "your-webui-password",
"websocketRequiresToken": true,
"allowFrom": ["*"],
@@ -34,34 +37,58 @@ The WebSocket channel is enabled by default. Add only the fields you want to ove
}
```
-### 2. Start nanobot
+### 2. Apply the configuration
+
+Replace `your-webui-password` with a private secret before using the configuration. Restart the gateway that owns this config if it is already running. If none is running, start it with the same installation and config:
```bash
nanobot gateway
```
-You should see:
+Keep it running while connecting clients from another terminal.
-```text
-WebSocket server listening on ws://127.0.0.1:8765/
-```
+### 3. Obtain a token and connect
+
+The secret above authorizes token issuance; it is not itself an issued connection token. Each WebSocket connection needs a new single-use token. Choose either client below. Both use the `/auth/token` path configured in step 1.
-### 3. Connect a client
+With `curl` and `websocat` installed:
```bash
-# Using websocat
-websocat ws://127.0.0.1:8765/?client_id=alice
+# Replace the example secret with the value saved in your config.
+curl --fail -H "Authorization: Bearer your-webui-password" http://127.0.0.1:8765/auth/token
+# Copy the returned token into the URL; keep the whole URL quoted.
+websocat "ws://127.0.0.1:8765/?client_id=alice&token=TOKEN_FROM_RESPONSE"
+```
+
+After the `ready` event, send `{"content":"Hello nanobot!"}`. Obtain another token before reconnecting. Do not share the secret or the token URL.
+
+Alternatively, save and run this Python example in an environment with `websockets` installed. It asks for the configured secret, obtains its own token, and prints server events until you press Ctrl+C:
+
+```python
+import asyncio
+import json
+from getpass import getpass
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+import websockets
+
+request = Request(
+ "http://127.0.0.1:8765/auth/token",
+ headers={"Authorization": "Bearer " + getpass("WebSocket token-issue secret: ")},
+)
+with urlopen(request, timeout=10) as response:
+ token = json.load(response)["token"]
-# Using Python
-import asyncio, json, websockets
async def main():
- async with websockets.connect("ws://127.0.0.1:8765/?client_id=alice") as ws:
- ready = json.loads(await ws.recv())
- print(ready) # {"event": "ready", "chat_id": "...", "client_id": "alice"}
+ query = urlencode({"client_id": "alice", "token": token})
+ async with websockets.connect("ws://127.0.0.1:8765/?" + query) as ws:
+ print(json.loads(await ws.recv())) # ready event
await ws.send(json.dumps({"content": "Hello nanobot!"}))
- reply = json.loads(await ws.recv())
- print(reply["text"])
+ async for frame in ws:
+ print(json.loads(frame))
+
asyncio.run(main())
```
@@ -394,7 +421,7 @@ Legacy clients that only send plain text or `{"content": ...}` keep working unch
### Security boundary
-`chat_id` is a *capability*: anyone holding a valid WebSocket auth credential and the chat_id can attach to that conversation and see its output. This is safe for nanobot's local, single-user model. Multi-tenant deployments should namespace chat_ids per user (or introduce a per-tenant auth gate) — nanobot does not do this today.
+`chat_id` is a *capability*: anyone holding a valid WebSocket auth credential and the chat_id can attach to that conversation and see its output. This is safe for nanobot's local, single-user model. Namespacing chat IDs alone does not enforce ownership. An application serving multiple users must authorize access before forwarding requests; separate instances and appropriate host permissions are needed when workspace files, memory, and tools must also be isolated. Nanobot does not provide per-user WebSocket authorization.
## Security Notes
@@ -402,7 +429,7 @@ Legacy clients that only send plain text or `{"content": ...}` keep working unch
- **Defense in depth**: `allowFrom` is checked at both the HTTP handshake level and the message level.
- **chat_id as capability**: see [Multi-chat multiplexing](#multi-chat-multiplexing). Auth on the WebSocket handshake is the single line of defense; callers who pass it can attach to any chat_id they know.
- **TLS enforcement**: When SSL is enabled, TLSv1.2 is the minimum allowed version.
-- **Default-secure**: `websocketRequiresToken` defaults to `true`. Explicitly set it to `false` only on trusted networks.
+- **Default-secure**: `websocketRequiresToken` defaults to `true`. Use `false` only for deliberate loopback-only development without authentication, as shown below.
## Media Files
@@ -413,13 +440,15 @@ Outbound `message` events may include a `media` field containing local filesyste
## Common Patterns
-### Trusted local network (no auth)
+### Loopback-only development (no auth)
+
+Use this only for local clients on the same trusted machine, without forwarding the port. Remove any existing static token, token-issue secret, or trusted-proxy authentication settings if deliberately switching to this mode. Binding all interfaces (`0.0.0.0` or `::`) requires configured authentication and is rejected without it.
```json
{
"channels": {
"websocket": {
- "host": "0.0.0.0",
+ "host": "127.0.0.1",
"port": 8765,
"websocketRequiresToken": false,
"allowFrom": ["*"],
diff --git a/docs/webui.md b/docs/webui.md
index 05f1595fc..5ea680939 100644
--- a/docs/webui.md
+++ b/docs/webui.md
@@ -34,7 +34,10 @@ The browser signs in automatically using the generated credential in the launch
If no provider is configured, follow the **Next step** prompt to open **Settings → Models**. Errors for a configured provider appear with that prompt.
-Manual config still works. Same-machine localhost WebUI access can run without a browser password. Set `tokenIssueSecret` when you intentionally expose the WebUI beyond localhost or want a browser password:
+<details>
+<summary>Manual configuration for the local WebUI</summary>
+
+Manual config still works. Same-machine localhost WebUI access can run without a browser password. Set `tokenIssueSecret` when you intentionally expose the WebUI beyond localhost or want a browser password. These listener and authentication fields have no graphical editor:
```json
{
@@ -49,8 +52,16 @@ Manual config still works. Same-machine localhost WebUI access can run without a
}
```
+</details>
+
The WebUI is served by the WebSocket channel on port `8765` by default. The gateway health endpoint, `18790` by default, is not the browser UI.
+## Sharing access
+
+The WebUI is an administration interface for one nanobot instance. Signed-in WebUI users can work with its saved topics and manage models, channels, Apps, automations, and settings within the gateway's supported capabilities. There are no per-user roles or private topic ownership boundaries. Remote package installation has an additional restriction described under [LAN Access](#lan-access); that restriction does not turn other WebUI users into read-only users.
+
+Share WebUI access only with people you trust to administer the same agent. To give someone chat access without the administration interface, connect a [chat platform](./chat-apps.md) and configure its access policy. Channel approval still does not create a separate agent or memory store. For separate clients or users whose data must not mix, use [separate instances](./multiple-instances.md).
+
## First 10 Minutes
Use the WebUI as the primary setup surface:
@@ -58,7 +69,7 @@ Use the WebUI as the primary setup surface:
1. Open **Settings → Models** and configure a provider, credential, and active model preset.
2. Send `Hello!` in a new topic to prove the selected model works.
3. Start a separate topic before project work, then choose the intended workspace and access mode.
-4. Add only one capability next: a chat channel in **Settings → Channels**, a web/voice/image provider in **Settings**, or an App/MCP integration in **Apps**.
+4. Add only one capability next: a chat channel in **Channels**, a web/voice/image provider in **Settings**, or an App/MCP integration in **Apps**.
5. Restart when the WebUI shows a restart requirement, then test that capability with the smallest possible request.
This path avoids hand-editing `config.json` for normal setup. Use the reference docs when you need an option the WebUI does not expose or when you manage config as code.
@@ -170,6 +181,8 @@ Selecting a project does not replace the configured agent workspace. The two pat
| Relative file paths and shell working directory | Long-term memory and history |
| The normal read/write boundary in Restricted mode | Custom skills and instance state |
+A new topic separates conversation history; a project selection changes the file working directory. Neither creates a separate long-term memory store. Project switching can therefore carry preferences and facts learned in other topics into the new project. Use [separate instances](./multiple-instances.md) when client or user data must stay separate; see [Memory](./memory.md) for how shared memory is maintained.
+
Project-local `SOUL.md` and `USER.md` files are ignored, and the agent workspace's `AGENTS.md` is not inherited by a separately selected project. When the selected project is the configured agent workspace, both roles naturally use the same directory.
The access control in the composer controls the local capability level for the chat. It does not bypass your gateway, provider, shell sandbox, or operating system configuration; it only selects among the capabilities that are already available to the current topic.
@@ -192,7 +205,7 @@ For image generation, configure an image provider first and then use the WebUI i
## Channels
-Open **Settings → Channels** to connect chat apps without assembling JSON by hand. Search for a platform, open its setup panel, and follow the fields or QR flow shown for that channel. The guided setup can:
+Open **Channels** to connect chat apps without assembling JSON by hand. Search for a platform, open its setup panel, and follow the fields or QR flow shown for that channel. The guided setup can:
- install missing optional channel support when the WebUI is running locally;
- collect platform credentials while preserving previously saved values;
@@ -291,6 +304,9 @@ Plain HTTP is enough for basic WebUI access, but browsers expose microphone capt
Remote WebUI clients with a valid token can view and use Apps and installed skills. Actions that install missing nanobot support packages or third-party marketplace skills are blocked by default. To let trusted remote administrators perform those installations through the WebUI, opt in explicitly:
+<details>
+<summary>Manual configuration</summary>
+
```json
{
"tools": {
@@ -299,6 +315,8 @@ Remote WebUI clients with a valid token can view and use Apps and installed skil
}
```
+</details>
+
Use this only for a private deployment where every authenticated WebUI user is trusted to change nanobot's Python environment and install workspace skill instructions or scripts. If you publish the WebUI through Nginx, Caddy, Cloudflare Tunnel, or a similar service, treat it as remote access and leave package and skill installs disabled unless that is intentional.
Optional feature installs use pip's configured package index, including `PIP_INDEX_URL`. skills.sh marketplace installs use `npx` instead.
diff --git a/hatch_build.py b/hatch_build.py
index 3d7bc05aa..3bec76066 100644
--- a/hatch_build.py
+++ b/hatch_build.py
@@ -1,10 +1,11 @@
-"""Hatch build hook that bundles the webui (Vite) into nanobot/web/dist.
+"""Hatch build hook that bundles the WebUI and nanobot skill documentation.
Triggered automatically by `python -m build` (and any other hatch-driven build)
so published wheels and sdists ship a fresh webui without requiring developers
-to remember `cd webui && bun run build` beforehand.
+to remember `cd webui && bun run build` beforehand. Documentation from docs/ is
+copied into the nanobot-document skill on every build, including editable installs.
-Behavior:
+WebUI behavior:
- Skips for editable installs (`pip install -e .`). Editable mode is for Python
development; webui contributors use `cd webui && bun run dev` (Vite HMR) and
@@ -21,6 +22,7 @@ Behavior:
from __future__ import annotations
import os
+import shutil
import sys
from pathlib import Path
from types import ModuleType
@@ -43,6 +45,27 @@ class WebUIBuildHook(BuildHookInterface):
def initialize(self, version: str, build_data: dict) -> None: # noqa: D401
root = Path(self.root)
+ docs_dir = root / "docs"
+ references_dir = root / "nanobot" / "skills" / "nanobot-document" / "references"
+ if not (docs_dir / "README.md").is_file():
+ raise RuntimeError("[nanobot-document] docs/README.md is required to bundle documentation")
+ # Refresh generated files without removing directories that Windows
+ # editors or file watchers may hold open during editable installs.
+ current_docs: set[Path] = set()
+ for source in docs_dir.rglob("*.md"):
+ relative = source.relative_to(docs_dir)
+ if relative.parts[0] in {"plans", "superpowers"}:
+ continue
+ current_docs.add(relative)
+ destination = references_dir / relative
+ destination.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copyfile(source, destination)
+ for generated in references_dir.rglob("*.md"):
+ if generated.relative_to(references_dir) not in current_docs:
+ generated.unlink()
+ build_data.setdefault("artifacts", []).append(
+ "nanobot/skills/nanobot-document/references/**/*.md"
+ )
webui_dir = root / "webui"
package_json = webui_dir / "package.json"
dist_dir = root / "nanobot" / "web" / "dist"
diff --git a/nanobot/agent/skills.py b/nanobot/agent/skills.py
index 9b565285b..e862826bf 100644
--- a/nanobot/agent/skills.py
+++ b/nanobot/agent/skills.py
@@ -243,7 +243,9 @@ class SkillsLoader:
continue
resolved_root = root.expanduser().resolve()
- if use_relative_roots:
+ # Directory tools need the real built-in root; only read_file resolves
+ # workspace-relative skills/<name>/... aliases to bundled resources.
+ if use_relative_roots and source != "builtin":
display_root = Path("plugins" if source == "plugin" else "skills")
else:
display_root = resolved_root
diff --git a/nanobot/skills/README.md b/nanobot/skills/README.md
index fa603fb8c..5c9ac6c50 100644
--- a/nanobot/skills/README.md
+++ b/nanobot/skills/README.md
@@ -24,3 +24,6 @@ These skills are adapted from [OpenClaw](https://github.com/openclaw/openclaw)'s
| `tmux` | Remote-control tmux sessions |
| `clawhub` | Search and install skills from ClawHub registry |
| `skill-creator` | Create new skills |
+| `nanobot-document` | Explain nanobot usage, configuration, and troubleshooting from bundled docs |
+
+`nanobot-document/references/` is generated from the root `docs/` directory by the Hatch build hook for wheels, source distributions, and editable installs. Edit `docs/` rather than the generated copies; rerun the build or editable install to refresh them. Source distributions also include `docs/` so wheels built from them retain the same documentation.
diff --git a/nanobot/skills/nanobot-document/SKILL.md b/nanobot/skills/nanobot-document/SKILL.md
new file mode 100644
index 000000000..e219aa2f6
--- /dev/null
+++ b/nanobot/skills/nanobot-document/SKILL.md
@@ -0,0 +1,23 @@
+---
+name: nanobot-document
+description: "Answer nanobot usage, configuration, and troubleshooting questions from its bundled documentation."
+---
+
+# nanobot Documentation
+
+Use the documentation in `references/` beside this skill. It ships with the installed version of nanobot. Load only the material needed for the user's question.
+
+| Topic | Entry point |
+|---|---|
+| Setup | [Quick start](references/quick-start.md) |
+| WebUI | [WebUI](references/webui.md) |
+| Provider setup | [Provider cookbook](references/provider-cookbook.md) |
+| Provider/model behavior | [Providers](references/providers.md) |
+| Exact fields and defaults | [Configuration](references/configuration.md) |
+| Chat apps and integrations | [Task guides](references/guides/README.md) |
+| Errors | [Troubleshooting](references/troubleshooting.md) |
+| Other topics | [Documentation index](references/README.md) |
+
+Prefer documented WebUI steps when the setting has a graphical control, unless headless or config-file setup is requested. Configuration examples are partial snippets to merge unless stated otherwise.
+
+Bundled docs match this installation's source and may be newer than the stable release. For latest-release questions or missing bundled docs, consult the [published documentation](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview) and make any version mismatch explicit. Links leaving `references/` refer to repository files that may not be bundled.
diff --git a/pyproject.toml b/pyproject.toml
index b30989d80..da9efdc28 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -94,6 +94,7 @@ olostep = [
"olostep>=0.1.0; python_version < '3.14'",
]
dev = [
+ "hatchling",
"pytest>=9.0.0,<10.0.0",
"pytest-asyncio>=1.3.0,<2.0.0",
"aiohttp>=3.9.0,<4.0.0",
@@ -154,6 +155,7 @@ exclude = ["nanobot/channels/*/tests/**"]
[tool.hatch.build.targets.sdist]
include = [
+ "docs/**/*.md",
"nanobot/",
"nanobot/web/dist/",
"hatch_build.py",
@@ -162,7 +164,7 @@ include = [
"THIRD_PARTY_NOTICES.md",
"pyproject.toml",
]
-exclude = ["nanobot/channels/*/tests/**"]
+exclude = ["nanobot/channels/*/tests/**", "docs/plans/**", "docs/superpowers/**"]
[tool.ruff]
line-length = 100
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index 68b98f7e2..7428ee616 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -128,7 +128,10 @@ function Get-NanobotCommand {
switch ($script:NanobotRunner) {
"uv" { return "uv tool run --from $InstallTarget nanobot" }
"pipx" { return "pipx run --spec $InstallTarget nanobot" }
- "python" { return "$script:NanobotPython -m nanobot" }
+ "python" {
+ $QuotedPython = "'" + $script:NanobotPython.Replace("'", "''") + "'"
+ return "& $QuotedPython -m nanobot"
+ }
default { return "nanobot" }
}
}
diff --git a/tests/agent/test_skills_loader.py b/tests/agent/test_skills_loader.py
index 91cb7e3ab..ef3bc6c5b 100644
--- a/tests/agent/test_skills_loader.py
+++ b/tests/agent/test_skills_loader.py
@@ -8,6 +8,8 @@ from pathlib import Path
import pytest
from nanobot.agent.skills import SkillsLoader
+from nanobot.agent.tools.filesystem import ListDirTool, WriteFileTool
+from nanobot.agent.tools.search import GrepTool
def _write_skill(
@@ -298,7 +300,7 @@ def test_disabled_skills_excluded_from_build_skills_summary(tmp_path: Path) -> N
assert "beta" in summary
-def test_build_skills_summary_uses_relative_roots_in_agent_workspace(tmp_path: Path) -> None:
+def test_build_skills_summary_keeps_builtin_root_absolute_in_agent_workspace(tmp_path: Path) -> None:
workspace = tmp_path / "ws"
workspace_skills = workspace / "skills"
workspace_skills.mkdir(parents=True)
@@ -309,14 +311,45 @@ def test_build_skills_summary_uses_relative_roots_in_agent_workspace(tmp_path: P
summary = SkillsLoader(workspace, builtin_skills_dir=builtin).build_skills_summary()
assert str(workspace_skills) not in summary
- assert str(builtin) not in summary
+ assert f"### Built-in skills (`{builtin.resolve()}`)" in summary
assert str(workspace_path) not in summary
assert str(builtin_path) not in summary
- assert summary.count("(`skills`)") == 2
+ assert summary.count("(`skills`)") == 1
assert "`alpha/SKILL.md`" in summary
assert "`beta/SKILL.md`" in summary
+async def test_builtin_summary_root_supports_restricted_reference_search(tmp_path: Path) -> None:
+ workspace = tmp_path / "ws"
+ workspace.mkdir()
+ builtin = tmp_path / "builtin"
+ _write_skill(builtin, "documentation", body="# Documentation")
+ references = builtin / "documentation" / "references"
+ references.mkdir()
+ guide = references / "usage.md"
+ guide.write_text("Choose a timezone", encoding="utf-8")
+ summary = SkillsLoader(workspace, builtin_skills_dir=builtin).build_skills_summary()
+ heading = next(line for line in summary.splitlines() if line.startswith("### Built-in skills"))
+ reference_path = str(Path(heading.split("`")[1]) / "documentation" / "references")
+ options = {
+ "workspace": workspace,
+ "allowed_dir": workspace,
+ "restrict_to_workspace": True,
+ "extra_read_allowed_dirs": [builtin],
+ }
+
+ listing = await ListDirTool(**options).execute(path=reference_path)
+ matches = await GrepTool(**options).execute(
+ pattern="timezone", path=reference_path, glob="*.md", output_mode="files_with_matches",
+ )
+
+ assert "usage.md" in listing
+ assert "usage.md" in matches
+ rejected = await WriteFileTool(**options).execute(path=str(guide), content="replace")
+ assert rejected.is_error
+ assert guide.read_text(encoding="utf-8") == "Choose a timezone"
+
+
def test_build_skills_summary_keeps_absolute_roots_for_selected_project(tmp_path: Path) -> None:
workspace = tmp_path / "ws"
workspace_skills = workspace / "skills"
diff --git a/tests/test_documentation_build.py b/tests/test_documentation_build.py
new file mode 100644
index 000000000..e5161f44c
--- /dev/null
+++ b/tests/test_documentation_build.py
@@ -0,0 +1,103 @@
+"""Documentation stays available across installs and rebuilds."""
+
+import ctypes
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+from zipfile import ZipFile
+
+import pytest
+
+from hatch_build import WebUIBuildHook
+
+
+def test_editable_install_refreshes_skill_documentation(tmp_path: Path) -> None:
+ docs = tmp_path / "docs"
+ (docs / "guides").mkdir(parents=True)
+ (docs / "README.md").write_text("Documentation index", encoding="utf-8")
+ guide = docs / "guides" / "setup.md"
+ guide.write_text("Setup instructions", encoding="utf-8")
+ hook = WebUIBuildHook(
+ str(tmp_path), {}, None, {}, "", "wheel",
+ SimpleNamespace(display_info=lambda message: None),
+ )
+ build_data = {}
+ hook.initialize("editable", build_data)
+
+ references = tmp_path / "nanobot/skills/nanobot-document/references"
+ assert (references / "README.md").read_bytes() == (docs / "README.md").read_bytes()
+ assert (references / "guides/setup.md").read_bytes() == guide.read_bytes()
+
+ guide.unlink()
+ (docs / "README.md").write_text("Updated index", encoding="utf-8")
+ hook.initialize("editable", {})
+
+ assert not (references / "guides/setup.md").exists()
+ assert (references / "README.md").read_text(encoding="utf-8") == "Updated index"
+
+
[email protected](sys.platform != "win32", reason="Windows directory handles")
+def test_editable_install_refreshes_docs_with_open_reference_directory(tmp_path: Path) -> None:
+ docs = tmp_path / "docs"
+ docs.mkdir()
+ (docs / "README.md").write_text("Documentation index", encoding="utf-8")
+ hook = WebUIBuildHook(
+ str(tmp_path), {}, None, {}, "", "wheel",
+ SimpleNamespace(display_info=lambda message: None),
+ )
+ hook.initialize("editable", {})
+ references = tmp_path / "nanobot/skills/nanobot-document/references"
+
+ kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+ kernel32.CreateFileW.restype = ctypes.c_void_p
+ # Allow file updates while holding the directory against removal, as an
+ # editor or file watcher can do while rebuilding an editable install.
+ handle = kernel32.CreateFileW(
+ ctypes.c_wchar_p(str(references)), 1, 3, None, 3, 0x02000000, None,
+ )
+ assert handle != ctypes.c_void_p(-1).value, ctypes.WinError(ctypes.get_last_error())
+ try:
+ (docs / "README.md").write_text("Updated index", encoding="utf-8")
+ hook.initialize("editable", {})
+ finally:
+ kernel32.CloseHandle(ctypes.c_void_p(handle))
+
+ assert (references / "README.md").read_text(encoding="utf-8") == "Updated index"
+
+
[email protected]("ignore_references", [False, True])
+def test_wheel_bundles_documentation_once(tmp_path: Path, ignore_references: bool) -> None:
+ repository = Path(__file__).resolve().parents[1]
+ (tmp_path / "docs").mkdir()
+ (tmp_path / "docs/README.md").write_text("Documentation index", encoding="utf-8")
+ (tmp_path / "nanobot").mkdir()
+ (tmp_path / "nanobot/__init__.py").write_text("", encoding="utf-8")
+ shutil.copyfile(repository / "nanobot/build_info.py", tmp_path / "nanobot/build_info.py")
+ shutil.copyfile(repository / "hatch_build.py", tmp_path / "hatch_build.py")
+ (tmp_path / "pyproject.toml").write_text(
+ '[project]\nname = "documentation-build-test"\nversion = "0.0.0"\n'
+ '[tool.hatch.build]\ninclude = ["nanobot/**/*.py", "nanobot/skills/**/*.md"]\n'
+ '[tool.hatch.build.hooks.custom]\n'
+ '[tool.hatch.build.targets.wheel]\npackages = ["nanobot"]\n',
+ encoding="utf-8",
+ )
+ if ignore_references:
+ (tmp_path / ".gitignore").write_text(
+ "/nanobot/skills/nanobot-document/references/\n", encoding="utf-8",
+ )
+ result = subprocess.run(
+ [sys.executable, "-c", "import hatchling.build; hatchling.build.build_wheel('dist')"],
+ cwd=tmp_path,
+ env={**os.environ, "NANOBOT_SKIP_WEBUI_BUILD": "1"},
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+ assert result.returncode == 0, result.stdout + result.stderr
+ with ZipFile(next((tmp_path / "dist").glob("*.whl"))) as wheel:
+ bundled_index = "nanobot/skills/nanobot-document/references/README.md"
+ assert wheel.namelist().count(bundled_index) == 1
+ assert wheel.read(bundled_index) == b"Documentation index"
diff --git a/webui/README.md b/webui/README.md
index 53506c9e4..ccd35a465 100644
--- a/webui/README.md
+++ b/webui/README.md
@@ -20,6 +20,11 @@ The source app is built with Vite + React 18 + TypeScript + Tailwind 3 + shadcn/
```text
webui/ source tree (this directory)
nanobot/web/dist/ build output served by the gateway
+webui/src/components/settings/ model, capability, and system settings
+webui/src/lib/ transport, API clients, and shared types
+webui/src/tests/ frontend test setup and integration tests
+nanobot/channels/*/webui/ channel-owned interface code
+nanobot/channels/*/tests/webui/ channel interface tests
```
## Develop the WebUI (Vite HMR)
@@ -42,7 +47,7 @@ From the repository root:
nanobot webui --dev
```
-The command safely prepares the local WebSocket channel, starts both the gateway and Vite, and opens `http://127.0.0.1:5173`. Vite proxies to the configured WebSocket channel and applies frontend changes with HMR. Press Ctrl+C in that terminal to stop both processes.
+The command safely prepares the local WebSocket channel, starts both the gateway and Vite, and opens `http://127.0.0.1:5173`. Vite proxies HTTP requests to the gateway and applies frontend changes with HMR; the application WebSocket connects directly to the gateway. Ctrl+C stops Vite and releases this gateway client. An on-demand gateway stops when its last interactive client exits; a persistent gateway keeps running.
Use `--no-open` to skip opening a browser. `--dev` is foreground-only and cannot be combined with `--background`.
@@ -78,7 +83,7 @@ bun run dev
Then open `http://127.0.0.1:5173`.
-By default the dev server proxies `/api`, `/webui`, `/auth`, and WebSocket traffic to `http://127.0.0.1:8765`.
+By default Vite proxies the HTTP paths `/api`, `/webui`, and `/auth` to `http://127.0.0.1:8765`. The application WebSocket connects directly to the URL returned by the gateway bootstrap response (`ws_url`); Vite does not proxy that connection.
If your gateway listens on a non-default port, point the dev server at it:
@@ -86,6 +91,8 @@ If your gateway listens on a non-default port, point the dev server at it:
NANOBOT_API_URL=http://127.0.0.1:9000 bun run dev
```
+This variable sets the HTTP target. Check the bootstrap response's `ws_url` when HTTP works but chat cannot connect: that address must be reachable by the browser. For a reverse proxy, configure the gateway's `channels.websocket.publicWsUrl` as described in [WebSocket deployment](../docs/websocket.md), rather than adding a Vite WebSocket proxy. If authentication is enabled, use the launcher's full login link or sign in with the configured bootstrap secret.
+
## Build for packaged runtime
You usually do not need to run this by hand: `python -m build` invokes the WebUI build automatically when packaging the wheel.
@@ -103,9 +110,13 @@ The gateway picks up the new bundle on the next restart.
```bash
cd webui
+bun run lint
bun run test
+bun run build
```
+`lint` runs ESLint; `test` runs Vitest, including channel-owned frontend tests; `build` runs TypeScript checking and produces the production bundle. Keep tests near the changed behavior and exercise settings save/reload in the browser. Browser-only preferences stay in the frontend; persistent configuration and security policy belong to the Python gateway. When changing that boundary, also run the relevant Python tests from [CONTRIBUTING.md](../CONTRIBUTING.md).
+
## Acknowledgements
- [`agent-chat-ui`](https://github.com/langchain-ai/agent-chat-ui) for UI and interaction inspiration across the chat surface.