docs: reorganize documentation around user workflows (#4916)
This commit is contained in:
chengyongru
@@ -101,13 +101,13 @@ For older updates, see the [release archive](./docs/release-archive.md) or [GitH
|
||||
## 📦 Install
|
||||
|
||||
> [!IMPORTANT]
|
||||
> If you want the newest features and experiments, install from source.
|
||||
>
|
||||
> 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:
|
||||
|
||||
Prerequisites: Python 3.11 or newer. Git is only needed for a source install; Node.js/Bun are only needed if you are developing the WebUI itself.
|
||||
Prerequisites: Python 3.11 or newer. Git is only needed for a source install. Published packages already include the WebUI; a current-source install needs `bun` or `npm` to build it.
|
||||
|
||||
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.
|
||||
|
||||
@@ -125,7 +125,7 @@ Windows PowerShell:
|
||||
irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex
|
||||
```
|
||||
|
||||
The default command installs or upgrades `nanobot-ai` from PyPI, then starts `nanobot onboard --wizard`. It avoids system-wide pip installs by using an active virtual environment, `uv`, `pipx`, or a managed venv under `~/.nanobot/venv`. If Quick Start finishes, skip the manual initialize/configure steps below and go straight to **Open the WebUI**.
|
||||
The default command installs or upgrades `nanobot-ai` from PyPI, then starts `nanobot onboard --wizard`. It avoids system-wide pip installs by using an active virtual environment, `uv`, `pipx`, or a managed venv under `~/.nanobot/venv`. If Quick Start finishes, skip the manual initialize/configure steps below and go straight to **Open the WebUI**. The installer also prints the exact command it used to run nanobot; reuse that full command below if `nanobot` is not on `PATH`.
|
||||
|
||||
To preview the plan without changing your environment, pass `--dry-run`; combine it with `--dev` when you want to preview the main-branch install.
|
||||
|
||||
@@ -165,18 +165,24 @@ If pip reports `externally-managed-environment` on macOS or Linux, use the one-c
|
||||
|
||||
**Install from source**
|
||||
|
||||
`bun` or `npm` must be available. From an activated virtual environment:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/HKUDS/nanobot.git
|
||||
cd nanobot
|
||||
python -m pip install -e .
|
||||
python -m pip install .
|
||||
```
|
||||
|
||||
On Windows, if pip reports that it cannot launch `npm`, run `cd webui`, `npm.cmd install --package-lock=false`, `npm.cmd run build`, and `cd ..` in order, then retry the install. Contributors who need an editable checkout should follow [`CONTRIBUTING.md`](./CONTRIBUTING.md) and [`webui/README.md`](./webui/README.md).
|
||||
|
||||
Verify the install:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
**1. Initialize**
|
||||
@@ -246,13 +252,13 @@ For another provider, the same config shape still applies:
|
||||
|
||||
**3. Open the WebUI**
|
||||
|
||||
Start the browser workbench:
|
||||
The stable-compatible path is:
|
||||
|
||||
```bash
|
||||
nanobot webui
|
||||
nanobot gateway
|
||||
```
|
||||
|
||||
`nanobot webui` prepares the local WebSocket channel if needed, starts the gateway, and opens `http://127.0.0.1:8765`. It binds the first-run WebUI to `127.0.0.1` by default, so it is not exposed to your LAN. Prefer not to keep a terminal open? Use `nanobot webui --background`, then manage the gateway with `nanobot gateway status`, `logs`, `restart`, and `stop`.
|
||||
Leave the terminal open and visit `http://127.0.0.1:8765`. Current source versions also provide `nanobot webui`, which prepares the local WebSocket channel if needed, starts the gateway, and opens the browser automatically. The first-run WebUI binds to `127.0.0.1` by default, so it is not exposed to your LAN. Prefer not to keep a terminal open? Use `nanobot gateway --background`, then manage it with `nanobot gateway status`, `logs`, `restart`, and `stop`.
|
||||
|
||||
For manual or terminal-only setup, test one CLI message:
|
||||
|
||||
@@ -292,7 +298,7 @@ The WebUI ships **inside the published wheel** — no extra build step. It is th
|
||||
nanobot webui
|
||||
```
|
||||
|
||||
The command enables the local WebSocket channel after confirmation, starts the gateway, and opens [`http://127.0.0.1:8765`](http://127.0.0.1:8765). To open it from another device on your LAN, see [WebUI docs -> LAN access](./docs/webui.md#lan-access).
|
||||
On current source versions, the command enables the local WebSocket channel after confirmation, starts the gateway, and opens [`http://127.0.0.1:8765`](http://127.0.0.1:8765). If your installed stable release does not include `nanobot webui`, run `nanobot gateway` and open that address manually. To open it from another device on your LAN, see [WebUI docs -> LAN access](./docs/webui.md#lan-access).
|
||||
|
||||
The WebUI is served by the WebSocket channel on port `8765` by default. The gateway's `18790` port is for the health endpoint, not the browser UI.
|
||||
|
||||
|
||||
+60
-126
@@ -1,150 +1,84 @@
|
||||
# nanobot Docs
|
||||
# nanobot Documentation
|
||||
|
||||
For published release documentation, visit [nanobot.wiki](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview). The pages in this directory track the current repository and may describe features that have not reached the published site yet.
|
||||
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.
|
||||
|
||||
If you have never used a terminal or edited a config file before, start with [`start-without-technical-background.md`](./start-without-technical-background.md). Otherwise, start with [`quick-start.md`](./quick-start.md), open the browser workbench with `nanobot webui`, and use terminal checks when you need lower-level diagnosis.
|
||||
|
||||
Most JSON examples in these docs are snippets to merge into `~/.nanobot/config.json`, not full replacement files.
|
||||
|
||||
Provider examples are concrete walkthroughs, not rankings or endorsements. Use the provider whose key, endpoint, and model ID you actually control.
|
||||
|
||||
If you find a docs mistake, outdated command, or confusing step, please open an issue: <https://github.com/HKUDS/nanobot/issues>.
|
||||
|
||||
## Pick a Track
|
||||
|
||||
| You are | Start with | Then use |
|
||||
|---|---|---|
|
||||
| New to terminals and config files | [`start-without-technical-background.md`](./start-without-technical-background.md) | [`troubleshooting.md`](./troubleshooting.md) if the first reply fails |
|
||||
| Comfortable pasting commands and JSON | [`quick-start.md`](./quick-start.md) | [`provider-cookbook.md`](./provider-cookbook.md) for pasteable provider setups |
|
||||
| Operating a long-running bot | [`concepts.md`](./concepts.md) | [`chat-apps.md`](./chat-apps.md), [`webui.md`](./webui.md), and [`deployment.md`](./deployment.md) |
|
||||
| Integrating or extending nanobot | [`architecture.md`](./architecture.md) | [`configuration.md`](./configuration.md), [`openai-api.md`](./openai-api.md), [`python-sdk.md`](./python-sdk.md), [`development.md`](./development.md), and [`channel-plugin-guide.md`](./channel-plugin-guide.md) |
|
||||
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).
|
||||
|
||||
## Start Here
|
||||
|
||||
| Goal | Read | Outcome |
|
||||
| Your situation | Read this | You are done when... |
|
||||
|---|---|---|
|
||||
| Start with no technical background | [`start-without-technical-background.md`](./start-without-technical-background.md) | One-command setup, terminal basics, config, API keys, and the first reply |
|
||||
| Install and get the first reply | [`quick-start.md`](./quick-start.md) | A working CLI agent and a known-good config path |
|
||||
| Understand how the pieces fit | [`concepts.md`](./concepts.md) | Mental model for config, workspace, gateway, channels, tools, memory, and sessions |
|
||||
| Choose or change a model provider | [`providers.md`](./providers.md) | Correct provider/model pairing without reading the full config reference |
|
||||
| Copy a provider setup recipe | [`provider-cookbook.md`](./provider-cookbook.md) | Pasteable OpenRouter, OpenAI, Anthropic, local model, fallback, and Langfuse setups |
|
||||
| Fix a first-run or runtime problem | [`troubleshooting.md`](./troubleshooting.md) | A diagnosis order and targeted checks for common failures |
|
||||
| Terminals, Python, or API keys are new to you | [Beginner walkthrough](./start-without-technical-background.md) | The browser can send `Hello!` and receive a reply |
|
||||
| You are comfortable running commands | [Install and Quick Start](./quick-start.md) | `nanobot status` is healthy and the WebUI or CLI can get one reply |
|
||||
| Something already failed | [Troubleshooting](./troubleshooting.md) | You have isolated the problem to install, config, model, gateway, channel, or tool access |
|
||||
|
||||
## Task Guides
|
||||
The recommended first-run path is:
|
||||
|
||||
Use these pages when you know the workflow you want and do not want to scan the
|
||||
full reference first.
|
||||
1. Install nanobot.
|
||||
2. Choose **Quick Start** in `nanobot onboard --wizard`.
|
||||
3. Run `nanobot gateway` and open `http://127.0.0.1:8765`.
|
||||
4. Send `Hello!` before configuring anything else.
|
||||
|
||||
Most people do not need to edit JSON for the first run. The wizard handles the initial provider, model, and local WebUI settings. Current source versions also provide `nanobot webui` to start the gateway and open the browser in one step. After the WebUI opens, use **Settings** for models and built-in capabilities, **Settings → Channels** for chat apps, and **Apps** for CLI App or MCP integrations.
|
||||
|
||||
## Add One Capability
|
||||
|
||||
Pick the row that matches what you want to accomplish next:
|
||||
|
||||
| Goal | Guide |
|
||||
|---|---|
|
||||
| Build a personal AI agent | [`guides/build-a-personal-ai-agent.md`](./guides/build-a-personal-ai-agent.md) |
|
||||
| Run a self-hosted AI agent | [`guides/self-hosted-ai-agent.md`](./guides/self-hosted-ai-agent.md) |
|
||||
| Use a browser AI agent WebUI | [`guides/ai-agent-webui.md`](./guides/ai-agent-webui.md) |
|
||||
| Connect an AI agent to chat apps | [`guides/chat-app-ai-agent.md`](./guides/chat-app-ai-agent.md) |
|
||||
| Run long-running agent tasks | [`guides/long-running-ai-agent.md`](./guides/long-running-ai-agent.md) |
|
||||
| Schedule or trigger agent turns | [`automations.md`](./automations.md) |
|
||||
| Add long-term agent memory | [`guides/ai-agent-memory.md`](./guides/ai-agent-memory.md) |
|
||||
| Add MCP tools to an agent | [`guides/mcp-tools-for-ai-agents.md`](./guides/mcp-tools-for-ai-agents.md) |
|
||||
| Run an agent from Python | [`guides/python-ai-agent-sdk.md`](./guides/python-ai-agent-sdk.md) |
|
||||
| Expose an OpenAI-compatible agent API | [`guides/openai-compatible-agent-api.md`](./guides/openai-compatible-agent-api.md) |
|
||||
| Deploy a long-running agent gateway | [`guides/deploy-nanobot-gateway.md`](./guides/deploy-nanobot-gateway.md) |
|
||||
| Learn the browser workbench | [WebUI](./webui.md) |
|
||||
| Connect Telegram, Discord, Slack, Feishu, WeChat, Email, or another chat app | [Chat Apps](./chat-apps.md) |
|
||||
| Choose a hosted, OAuth, company, or local model | [Provider Cookbook](./provider-cookbook.md) |
|
||||
| Add model fallbacks | [Configure Model Fallback](./guides/configure-model-fallback.md) |
|
||||
| Enable web search | [Configure Web Search](./guides/configure-web-search.md) |
|
||||
| Add an MCP tool server | [Configure MCP Tools](./guides/configure-mcp-tools.md) |
|
||||
| Generate images | [Image Generation](./image-generation.md) |
|
||||
| Schedule work or create a local trigger | [Automations](./automations.md) |
|
||||
| Understand and manage long-term memory | [Memory](./memory.md) |
|
||||
| Run nanobot continuously | [Deployment](./deployment.md) |
|
||||
| Run separate bots or workspaces | [Multiple Instances](./multiple-instances.md) |
|
||||
| Call nanobot from Python | [Python SDK](./python-sdk.md) |
|
||||
| Expose an OpenAI-compatible endpoint | [OpenAI-Compatible API](./openai-api.md) |
|
||||
|
||||
Platform-specific chat guides:
|
||||
[`Telegram`](./guides/telegram-ai-agent.md),
|
||||
[`Discord`](./guides/discord-ai-agent.md),
|
||||
[`Slack`](./guides/slack-ai-agent.md),
|
||||
[`Feishu`](./guides/feishu-ai-agent.md),
|
||||
[`WhatsApp`](./guides/whatsapp-ai-agent.md),
|
||||
[`WeChat`](./guides/wechat-ai-agent.md),
|
||||
[`QQ`](./guides/qq-ai-agent.md),
|
||||
[`Email`](./guides/email-ai-agent.md), and
|
||||
[`Mattermost`](./guides/mattermost-ai-agent.md).
|
||||
For shorter, outcome-focused walkthroughs, browse the [task guide index](./guides/README.md).
|
||||
|
||||
Configuration guides:
|
||||
[`MCP tools`](./guides/configure-mcp-tools.md),
|
||||
[`web search`](./guides/configure-web-search.md),
|
||||
[`model fallback`](./guides/configure-model-fallback.md),
|
||||
[`OpenAI-compatible providers`](./guides/configure-openai-compatible-provider.md),
|
||||
[`Langfuse`](./guides/configure-langfuse-observability.md),
|
||||
[`local security`](./guides/secure-local-ai-agent.md), and
|
||||
[`gateway deployment`](./guides/deploy-nanobot-gateway.md).
|
||||
## Operate nanobot
|
||||
|
||||
## After the First Reply Works
|
||||
|
||||
Do not configure everything at once. Pick one next surface:
|
||||
|
||||
If a local `nanobot agent` session can already answer normally, you can also ask nanobot to help configure itself: have it read the relevant docs, inspect your current config, make one specific next change, and tell you when to run `/restart`.
|
||||
|
||||
| Next goal | Read | First check |
|
||||
|---|---|---|
|
||||
| Use nanobot in a browser | [`webui.md`](./webui.md) | Run `nanobot webui` and open the local browser workbench |
|
||||
| Talk through a chat app | [`chat-apps.md`](./chat-apps.md) | Merge one channel snippet, run `nanobot channels status`, keep `nanobot gateway` running |
|
||||
| Change provider or add fallbacks | [`provider-cookbook.md`](./provider-cookbook.md) | Keep `modelPresets` named and set `agents.defaults.modelPreset` |
|
||||
| Call nanobot from Python | [`python-sdk.md`](./python-sdk.md) | Reuse the same config/workspace from code, then run or stream one agent turn |
|
||||
| Understand before operating long-term | [`concepts.md`](./concepts.md) | Know what config, workspace, gateway, sessions, memory, and tools mean |
|
||||
| Diagnose a new failure | [`troubleshooting.md`](./troubleshooting.md) | Start with `nanobot status`, then `nanobot agent -m "Hello!"` |
|
||||
|
||||
## Use nanobot
|
||||
|
||||
| Goal | Read | Outcome |
|
||||
|---|---|---|
|
||||
| Open the bundled browser UI | [`webui.md`](./webui.md) | `nanobot webui`, chat workspace, Apps, Skills, Automations, and settings |
|
||||
| Connect Telegram, Discord, WeChat, Slack, Email, Mattermost, or another chat app | [`chat-apps.md`](./chat-apps.md) | A gateway-backed chat channel with access control |
|
||||
| Use automations | [`automations.md`](./automations.md) | Scheduled automations, local triggers, heartbeat, WebUI management, and delivery behavior |
|
||||
| Use slash commands | [`chat-commands.md`](./chat-commands.md) | Pairing, model presets, local triggers, heartbeat tasks, and chat-side controls |
|
||||
| Generate images | [`image-generation.md`](./image-generation.md) | Image provider config, WebUI image mode, and artifact behavior |
|
||||
| Run several isolated bots | [`multiple-instances.md`](./multiple-instances.md) | Separate configs, workspaces, ports, and sessions |
|
||||
| Deploy outside a terminal | [`deployment.md`](./deployment.md) | Docker, systemd user services, and macOS LaunchAgent setup |
|
||||
| Join agent communities | [`agent-social-network.md`](./agent-social-network.md) | External agent-community setup |
|
||||
| Need | Read |
|
||||
|---|---|
|
||||
| Commands and flags | [CLI Reference](./cli-reference.md) |
|
||||
| In-chat slash commands | [In-Chat Commands](./chat-commands.md) |
|
||||
| Config, workspace, gateway, sessions, tools, and memory in plain language | [Concepts](./concepts.md) |
|
||||
| Provider/model matching and selection | [Providers and Models](./providers.md) |
|
||||
| Setup and runtime diagnosis | [Troubleshooting](./troubleshooting.md) |
|
||||
| Older development highlights | [Release Archive](./release-archive.md) |
|
||||
|
||||
## Reference
|
||||
|
||||
| Area | Read | Best for |
|
||||
|---|---|---|
|
||||
| Full configuration schema | [`configuration.md`](./configuration.md) | Exact fields, defaults, provider tables, web tools, MCP, security, and runtime options |
|
||||
| CLI commands | [`cli-reference.md`](./cli-reference.md) | Command names, common flags, and entrypoints |
|
||||
| Architecture | [`architecture.md`](./architecture.md) | Source-level runtime map for core flow, providers, channels, tools, WebUI, memory, security, and extension points |
|
||||
| Release archive | [`release-archive.md`](./release-archive.md) | Older release and daily update highlights moved out of the README |
|
||||
| Development | [`development.md`](./development.md) | Contributor notes for adding providers and transcription adapters |
|
||||
| Memory | [`memory.md`](./memory.md) | Session history, Dream consolidation, memory files, and versioning |
|
||||
| Observability | [`configuration.md#langfuse-observability`](./configuration.md#langfuse-observability) | Langfuse tracing setup and required environment variables |
|
||||
| WebSocket protocol | [`websocket.md`](./websocket.md) | Custom clients, token issuance, multiplexed chats, media, and protocol events |
|
||||
| OpenAI-compatible API | [`openai-api.md`](./openai-api.md) | `/v1/chat/completions`, `/v1/models`, file uploads, and SDK-compatible usage |
|
||||
| Python SDK | [`python-sdk.md`](./python-sdk.md) | SDK 101, sessions, streaming, model overrides, runtime helpers, and hooks |
|
||||
| Runtime self-inspection | [`my-tool.md`](./my-tool.md) | Inspecting and tuning the current agent run |
|
||||
Use reference pages to look up an exact option after you know what you are trying to configure:
|
||||
|
||||
## Fast Lookup
|
||||
|
||||
| Need | Jump to |
|
||||
| Area | Reference |
|
||||
|---|---|
|
||||
| Provider/model resolution order | [`providers.md#provider-resolution`](./providers.md#provider-resolution) |
|
||||
| Model presets and fallback chains | [`providers.md#model-presets`](./providers.md#model-presets) and [`providers.md#fallback-models`](./providers.md#fallback-models) |
|
||||
| Langfuse environment variables | [`configuration.md#langfuse-observability`](./configuration.md#langfuse-observability) |
|
||||
| WebSocket/WebUI protocol details | [`websocket.md`](./websocket.md) |
|
||||
| OpenAI-compatible API usage | [`openai-api.md`](./openai-api.md) |
|
||||
| Python SDK usage | [`python-sdk.md`](./python-sdk.md) |
|
||||
| Scheduled automations and local triggers | [`automations.md`](./automations.md) |
|
||||
| Multiple configs, workspaces, and ports | [`multiple-instances.md`](./multiple-instances.md) |
|
||||
| Security, sandboxing, and SSRF controls | [`configuration.md#security`](./configuration.md#security) |
|
||||
| Channel plugin development | [`channel-plugin-guide.md`](./channel-plugin-guide.md) |
|
||||
| Every configuration field and default | [Configuration](./configuration.md) |
|
||||
| Provider and model behavior | [Providers and Models](./providers.md) |
|
||||
| Chat channel prerequisites and manual JSON | [Chat Apps](./chat-apps.md) |
|
||||
| WebSocket authentication and wire protocol | [WebSocket](./websocket.md) |
|
||||
| Python SDK classes, events, sessions, and hooks | [Python SDK](./python-sdk.md) |
|
||||
| OpenAI-compatible HTTP routes and payloads | [OpenAI-Compatible API](./openai-api.md) |
|
||||
| Runtime self-inspection and tuning | [My Tool](./my-tool.md) |
|
||||
|
||||
## Extend nanobot
|
||||
Configuration examples are usually snippets to merge into `~/.nanobot/config.json`, not complete replacement files. The docs use camelCase because nanobot writes config that way. Keep real API keys, bot tokens, and passwords out of issues and public logs.
|
||||
|
||||
| Goal | Read | Outcome |
|
||||
|---|---|---|
|
||||
| Add a provider or transcription adapter | [`development.md`](./development.md) | A registry/schema-aligned implementation path |
|
||||
| Add a chat channel plugin | [`channel-plugin-guide.md`](./channel-plugin-guide.md) | A packaged channel discovered through entry points |
|
||||
| Add custom MCP servers | [`configuration.md#mcp-model-context-protocol`](./configuration.md#mcp-model-context-protocol) | External tools exposed to the agent through MCP |
|
||||
| Tune tool safety | [`configuration.md#security`](./configuration.md#security) | Shell sandboxing, workspace restriction, and SSRF policy |
|
||||
## Extend or Contribute
|
||||
|
||||
## Reading Strategy
|
||||
These pages explain implementation and extension points. You do not need them to install or operate nanobot.
|
||||
|
||||
Use the docs in this order when you are unsure where to go:
|
||||
| Goal | Read |
|
||||
|---|---|
|
||||
| Understand source ownership and runtime flow | [Architecture](./architecture.md) |
|
||||
| Set up a development environment | [Development](./development.md) and [CONTRIBUTING.md](../CONTRIBUTING.md) |
|
||||
| Add a channel package | [Channel Plugin Guide](./channel-plugin-guide.md) |
|
||||
| Build the WebUI source | [WebUI Development](../webui/README.md) |
|
||||
|
||||
1. If terminal commands or config files are new to you, [`start-without-technical-background.md`](./start-without-technical-background.md) explains the setup words and uses one concrete provider example so there is only one decision at a time.
|
||||
2. [`quick-start.md`](./quick-start.md) proves installation, config loading, and provider access.
|
||||
3. [`concepts.md`](./concepts.md) explains the runtime model so later pages are easier to scan.
|
||||
4. [`provider-cookbook.md`](./provider-cookbook.md) gives pasteable provider, fallback, local model, and Langfuse recipes.
|
||||
5. A task guide, such as [`chat-apps.md`](./chat-apps.md), [`image-generation.md`](./image-generation.md), or [`deployment.md`](./deployment.md), gets one workflow working.
|
||||
6. [`configuration.md`](./configuration.md) is the source of truth when you need a specific field, default value, or advanced option.
|
||||
7. [`troubleshooting.md`](./troubleshooting.md) helps isolate whether a failure is install, config, provider, gateway, channel, or tool related.
|
||||
If a command or screen no longer matches these docs, please [open an issue](https://github.com/HKUDS/nanobot/issues) with your nanobot version, operating system, and the page that needs correction.
|
||||
|
||||
+20
-6
@@ -26,11 +26,23 @@ nanobot agent -m "Hello!"
|
||||
|
||||
If that fails, fix installation, config, provider, or model setup first with [`quick-start.md`](./quick-start.md), [`providers.md`](./providers.md), and [`troubleshooting.md`](./troubleshooting.md). Chat apps require `nanobot gateway` to stay running after the channel is configured.
|
||||
|
||||
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.
|
||||
## Recommended Setup in the WebUI
|
||||
|
||||
For normal local setup, let the WebUI write and validate the channel config:
|
||||
|
||||
1. Run `nanobot webui`.
|
||||
2. Open **Settings → 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.
|
||||
|
||||
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.
|
||||
|
||||
The sections below explain what each chat platform requires and provide manual config for deployments that manage `config.json` directly.
|
||||
|
||||
> [!NOTE]
|
||||
> If you are upgrading from a version where chat app SDKs were installed by default,
|
||||
@@ -47,7 +59,9 @@ codes.
|
||||
> nanobot keeps the saved settings, but stops loading that channel after the
|
||||
> next restart.
|
||||
|
||||
## Common Setup Pattern
|
||||
## 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.
|
||||
|
||||
Every chat app uses the same shape:
|
||||
|
||||
|
||||
+2
-2
@@ -64,9 +64,9 @@ That flow is the same whether the message starts in the CLI, WebUI, Telegram, Di
|
||||
| CLI interactive | `nanobot agent` | Terminal chat with persistent session history |
|
||||
| Gateway | `nanobot gateway` | Chat apps, WebUI, heartbeat, Dream, and long-running service mode |
|
||||
| OpenAI-compatible API | `nanobot serve` | Programmatic access through `/v1/chat/completions` |
|
||||
| WebUI | `nanobot gateway` plus WebSocket channel | Browser workbench served by the WebSocket channel on port `8765` |
|
||||
| WebUI | `nanobot webui` | Prepare the local WebUI, start the gateway, and open the browser workbench |
|
||||
|
||||
The gateway health endpoint is on `gateway.port` (`18790` by default). The browser WebUI is served by the WebSocket channel (`8765` by default), not by the health endpoint.
|
||||
The WebUI launcher is the normal browser entry point. Underneath, the gateway keeps the WebSocket channel and other long-running services alive. The gateway health endpoint is on `gateway.port` (`18790` by default); the browser WebUI is served on `8765` by default, not by the health endpoint.
|
||||
|
||||
## Provider and Model Selection
|
||||
|
||||
|
||||
@@ -4,6 +4,8 @@ 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.
|
||||
|
||||
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).
|
||||
|
||||
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.
|
||||
@@ -11,7 +13,7 @@ The generated `config.json` uses camelCase keys such as `apiKey` and `intervalS`
|
||||
For setup and runtime failures, follow the diagnosis order in [`troubleshooting.md`](./troubleshooting.md) before changing multiple config areas at once.
|
||||
|
||||
> [!NOTE]
|
||||
> If your config file is older than the current schema, you can refresh it without overwriting your existing values: run `nanobot onboard`, then answer `N` when asked whether to overwrite the config. nanobot will merge in missing default fields and keep your current settings.
|
||||
> If your config file is older than the current schema, run `nanobot onboard --refresh`. nanobot adds missing default fields while preserving your existing values.
|
||||
|
||||
## Configuration Guides
|
||||
|
||||
@@ -47,9 +49,9 @@ the focused guides first and come back here for exact fields and defaults.
|
||||
| Control access and pairing | [Pairing](#pairing) |
|
||||
| Tune gateway jobs, sessions, and tools | [Gateway Heartbeat](#gateway-heartbeat), [Auto Compact](#auto-compact), [Unified Session](#unified-session), [Tool Hint Max Length](#tool-hint-max-length) |
|
||||
|
||||
## Where to Edit First
|
||||
## Where a Setting Lives
|
||||
|
||||
If you are not sure where a setting belongs, start from the task you are trying to complete. Most changes touch one config section and one verification command.
|
||||
If the WebUI does not expose the option you need, start from the task below. Most advanced changes touch one config section and one verification command.
|
||||
|
||||
| Task | First keys to check | Verify with | Deep dive |
|
||||
|---|---|---|---|
|
||||
|
||||
+15
-11
@@ -1,21 +1,20 @@
|
||||
# nanobot Guides
|
||||
# nanobot Task Guides
|
||||
|
||||
These guides are short task entry points. Use them when you know what you want
|
||||
to build, then follow the linked reference docs for complete option tables and
|
||||
edge cases.
|
||||
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.
|
||||
|
||||
## Build and operate
|
||||
## Start and Use
|
||||
|
||||
| Goal | Guide |
|
||||
|---|---|
|
||||
| Build a personal AI agent | [Build a personal AI agent](./build-a-personal-ai-agent.md) |
|
||||
| Run a self-hosted AI agent | [Self-hosted AI agent](./self-hosted-ai-agent.md) |
|
||||
| Use the browser workbench | [AI agent WebUI](./ai-agent-webui.md) |
|
||||
| Run long-running tasks | [Long-running AI agent](./long-running-ai-agent.md) |
|
||||
| Add memory | [AI agent memory](./ai-agent-memory.md) |
|
||||
| Deploy a gateway | [Deploy a long-running nanobot AI agent gateway](./deploy-nanobot-gateway.md) |
|
||||
| Run a self-hosted AI agent | [Self-hosted AI agent](./self-hosted-ai-agent.md) |
|
||||
| Run a sustained goal | [Long-running AI agent](./long-running-ai-agent.md) |
|
||||
| Add long-term memory | [AI agent memory](./ai-agent-memory.md) |
|
||||
|
||||
## Connect and integrate
|
||||
## 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.
|
||||
|
||||
| Goal | Guide |
|
||||
|---|---|
|
||||
@@ -29,10 +28,15 @@ edge cases.
|
||||
| Connect QQ | [QQ AI agent](./qq-ai-agent.md) |
|
||||
| Connect Email | [Email AI agent](./email-ai-agent.md) |
|
||||
| Connect Mattermost | [Mattermost AI agent](./mattermost-ai-agent.md) |
|
||||
|
||||
## Integrate from Code
|
||||
|
||||
| Goal | Guide |
|
||||
|---|---|
|
||||
| Run from Python | [Python AI agent SDK](./python-ai-agent-sdk.md) |
|
||||
| Expose `/v1/chat/completions` | [OpenAI-compatible agent API](./openai-compatible-agent-api.md) |
|
||||
|
||||
## Configure
|
||||
## Configure and Operate
|
||||
|
||||
| Goal | Guide |
|
||||
|---|---|
|
||||
|
||||
@@ -21,10 +21,10 @@ private DMs, team channels, group chats, email threads, or bot workspaces.
|
||||
```bash
|
||||
python -m pip install nanobot-ai
|
||||
nanobot onboard --wizard
|
||||
nanobot agent -m "Hello!"
|
||||
nanobot webui
|
||||
```
|
||||
|
||||
Then choose one platform guide:
|
||||
Send `Hello!` in the WebUI before adding a channel. Then choose one platform guide for the bot/account prerequisites:
|
||||
|
||||
- [Telegram AI agent](./telegram-ai-agent.md)
|
||||
- [Discord AI agent](./discord-ai-agent.md)
|
||||
@@ -38,28 +38,31 @@ Then choose one platform guide:
|
||||
|
||||
## Minimal working example
|
||||
|
||||
Every channel follows the same pattern:
|
||||
Use the guided channel setup:
|
||||
|
||||
1. Get the platform token, login state, webhook, or mailbox credentials.
|
||||
2. Merge the channel snippet into `~/.nanobot/config.json`.
|
||||
3. Prefer pairing for DM-capable channels: omit `allowFrom`, then approve the
|
||||
first DM's pairing code.
|
||||
4. For channels without pairing, such as Email, keep access narrow with
|
||||
`allowFrom` or platform-specific allow lists.
|
||||
5. Check status:
|
||||
2. Open **Settings → 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.
|
||||
|
||||
Check status from the terminal when you need a lower-level confirmation:
|
||||
|
||||
```bash
|
||||
nanobot channels status
|
||||
```
|
||||
|
||||
6. Start the gateway:
|
||||
The `nanobot webui` command already runs the gateway. For a chat-only or server deployment, start it directly:
|
||||
|
||||
```bash
|
||||
nanobot gateway
|
||||
```
|
||||
|
||||
7. Send a test DM, approve the pairing code when prompted, then send the test
|
||||
message again.
|
||||
Use the full [Chat Apps reference](../chat-apps.md) when you manage `config.json` directly or need platform-specific advanced settings.
|
||||
|
||||
## Production notes
|
||||
|
||||
@@ -80,8 +83,7 @@ nanobot gateway
|
||||
|
||||
- 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 it with
|
||||
`/pairing approve <code>` before expecting normal replies.
|
||||
- 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 group replies are unexpected, review that channel's group policy.
|
||||
|
||||
@@ -6,7 +6,7 @@ through the Model Context Protocol.
|
||||
## What you will build
|
||||
|
||||
- a working nanobot agent
|
||||
- one MCP server entry in `~/.nanobot/config.json`
|
||||
- one MCP integration configured through Apps or `~/.nanobot/config.json`
|
||||
- a restricted set of MCP tools exposed to the model
|
||||
|
||||
## When to use this
|
||||
@@ -27,7 +27,15 @@ remote HTTP endpoint.
|
||||
|
||||
## Minimal working example
|
||||
|
||||
Add this to `~/.nanobot/config.json`:
|
||||
For local interactive setup:
|
||||
|
||||
1. Run `nanobot webui` and open **Apps**.
|
||||
2. Choose a known integration preset, or add a custom stdio, HTTP, or SSE server.
|
||||
3. Limit the enabled tools when the server exposes more than the task needs.
|
||||
4. Save and restart when prompted.
|
||||
5. Mention the integration with `@` in the next message and ask for a small test action.
|
||||
|
||||
For manual or deployment-managed config, add this to `~/.nanobot/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
|
||||
@@ -7,7 +7,7 @@ providers.
|
||||
## What you will build
|
||||
|
||||
- web tools enabled in nanobot
|
||||
- one search provider selected in `config.json`
|
||||
- one search provider selected in the WebUI or `config.json`
|
||||
- optional web fetch settings for page reading
|
||||
|
||||
## When to use this
|
||||
@@ -28,7 +28,15 @@ provider, API key, proxy, fetch behavior, or SSRF allowlist.
|
||||
|
||||
## Minimal working example
|
||||
|
||||
Use the default search provider:
|
||||
For local interactive setup:
|
||||
|
||||
1. Run `nanobot webui`.
|
||||
2. Open **Settings → Web**.
|
||||
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.
|
||||
|
||||
For manual or deployment-managed config, use the default search provider:
|
||||
|
||||
```json
|
||||
{
|
||||
|
||||
@@ -2,10 +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. Enable it in `~/.nanobot/config.json`, configure a supported image provider, then restart the gateway.
|
||||
The feature is disabled by default. Open **Settings → Image**, choose a configured provider and model, enable image generation, save, and restart when prompted. 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** if it is not already configured.
|
||||
2. Open **Settings → Image**.
|
||||
3. Select the provider and image model, then enable image generation.
|
||||
4. Save, restart when prompted, and ask for a simple test image.
|
||||
|
||||
**Manual config**
|
||||
|
||||
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.
|
||||
|
||||
```json
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
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** in the WebUI to add provider credentials, create a model preset, and select the active model. Use the JSON below for manual deployments, local endpoints, provider-specific fields, or diagnosis.
|
||||
|
||||
For every setup, answer three questions:
|
||||
|
||||
1. Which provider owns the credential or endpoint?
|
||||
|
||||
+170
-270
@@ -1,153 +1,197 @@
|
||||
# Install and Quick Start
|
||||
|
||||
This page gets one local nanobot reply working. After that, you can add the WebUI, chat apps, local models, web search, MCP, deployment, or custom plugins.
|
||||
This guide has one goal: get a normal nanobot reply in your browser. Do not add chat apps, MCP servers, fallback models, or deployment until this path works.
|
||||
|
||||
If you have never used a terminal or edited a config file before, use [`start-without-technical-background.md`](./start-without-technical-background.md) first. This page assumes you are comfortable pasting commands and editing JSON snippets.
|
||||
If terminals, Python, or API keys are unfamiliar, use the [beginner walkthrough](./start-without-technical-background.md), which explains each term and screen.
|
||||
|
||||
## Before You Start
|
||||
These repository docs follow current `main`. The recommended installer uses the stable package, so a newly documented WebUI screen may not appear until the next release. Each advanced guide also provides a CLI or manual config path.
|
||||
|
||||
You need:
|
||||
## What You Need
|
||||
|
||||
- Python 3.11 or newer.
|
||||
- One LLM provider, company endpoint, subscription endpoint, or local model server you can call. The examples below use a generic OpenAI-compatible `custom` provider so the compact path does not recommend one hosted service; any supported provider works when the key, provider name, and model ID match.
|
||||
- Git only if you install from source.
|
||||
- Node.js or Bun only if you are developing the WebUI itself.
|
||||
- Access to one supported AI provider, company endpoint, or local model server.
|
||||
- The credential, endpoint URL, and model ID required by that service. Local providers such as Ollama may not require a key.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Repository docs may describe features that are available first in source. Install from PyPI or `uv` for the stable day-to-day release; install from source when you want the newest repository behavior or plan to contribute.
|
||||
Git is only needed for a source install. The published package already contains the WebUI. A current-source install needs `bun` or `npm` so its WebUI bundle can be built.
|
||||
|
||||
## 1. Install
|
||||
## 1. Install nanobot
|
||||
|
||||
Pick one install method.
|
||||
The recommended installer keeps nanobot out of the system Python environment and opens the setup wizard when installation finishes.
|
||||
|
||||
**One-command setup:**
|
||||
**macOS / Linux**
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh
|
||||
```
|
||||
|
||||
On Windows PowerShell:
|
||||
**Windows PowerShell**
|
||||
|
||||
```powershell
|
||||
irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex
|
||||
```
|
||||
|
||||
The default command installs or upgrades `nanobot-ai` from PyPI, then starts `nanobot onboard --wizard`. It avoids system-wide pip installs by using an active virtual environment, `uv`, `pipx`, or a managed venv under `~/.nanobot/venv`. If Quick Start finishes, go straight to [Open the WebUI](#5-open-the-webui).
|
||||
The installer chooses an active virtual environment, `uv`, `pipx`, or a managed environment under `~/.nanobot/venv`. It installs the stable PyPI release unless you explicitly pass `--dev`. At the end it prints the exact command it used to run nanobot; if `nanobot` is not on `PATH`, reuse that full command in the examples below.
|
||||
|
||||
To preview the plan without changing your environment, pass `--dry-run`; combine it with `--dev` when you want to preview the main-branch install.
|
||||
If you prefer to inspect the scripts first, open [`install.sh`](../scripts/install.sh) or [`install.ps1`](../scripts/install.ps1).
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dry-run
|
||||
```
|
||||
## 2. Complete Quick Start
|
||||
|
||||
```powershell
|
||||
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dry-run
|
||||
```
|
||||
The installer opens `nanobot onboard --wizard`. Choose **Quick Start** and follow the prompts:
|
||||
|
||||
To install the current `main` branch instead, pass `--dev`:
|
||||
1. Choose the provider or endpoint that owns your credential.
|
||||
2. Enter its API key or base URL when requested.
|
||||
3. Enter a model ID that the same provider can run.
|
||||
4. Let Quick Start enable the local WebUI.
|
||||
5. Set a WebUI password and review the summary.
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dev
|
||||
```
|
||||
Quick Start creates or updates:
|
||||
|
||||
```powershell
|
||||
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dev
|
||||
```
|
||||
| Path | Purpose |
|
||||
|---|---|
|
||||
| `~/.nanobot/config.json` | Provider, model, WebUI, channel, tool, and runtime settings |
|
||||
| `~/.nanobot/workspace/` | Sessions, memory, skills, automations, and generated files |
|
||||
|
||||
If `curl` or `irm` is unavailable, or GitHub raw downloads are blocked on your network, use one of the manual install methods below.
|
||||
|
||||
If you prefer to inspect the script first, open [`../scripts/install.sh`](../scripts/install.sh) or [`../scripts/install.ps1`](../scripts/install.ps1).
|
||||
|
||||
**Stable release with `uv`:**
|
||||
|
||||
```bash
|
||||
uv tool install nanobot-ai
|
||||
nanobot --version
|
||||
```
|
||||
|
||||
**Stable release with pip:**
|
||||
|
||||
```bash
|
||||
python -m pip install nanobot-ai
|
||||
nanobot --version
|
||||
```
|
||||
|
||||
Use pip only inside an environment you control. 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 create a virtual environment first.
|
||||
|
||||
**Latest source checkout:**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/HKUDS/nanobot.git
|
||||
cd nanobot
|
||||
python -m pip install -e .
|
||||
nanobot --version
|
||||
```
|
||||
|
||||
If your shell cannot find `nanobot` after a pip install, run the module form:
|
||||
|
||||
```bash
|
||||
python -m nanobot --version
|
||||
python -m nanobot onboard
|
||||
```
|
||||
|
||||
On Windows, `~` in the docs means your user profile directory, for example `C:\Users\you`.
|
||||
|
||||
The docs use `python` in commands. If your system exposes Python 3.11+ as `python3` or `py`, use that command in the same place, for example `python3 -m pip install nanobot-ai` or `py -m nanobot --version`.
|
||||
|
||||
## 2. Initialize
|
||||
|
||||
Skip this section if the one-command setup already started the wizard and Quick Start finished there.
|
||||
|
||||
```bash
|
||||
nanobot onboard
|
||||
```
|
||||
|
||||
Use the wizard if you prefer prompts instead of editing JSON by hand:
|
||||
If the installer did not open the wizard, run it yourself:
|
||||
|
||||
```bash
|
||||
nanobot onboard --wizard
|
||||
```
|
||||
|
||||
Initialization creates:
|
||||
Current source versions also provide `nanobot webui`. When run without a usable model, that launcher offers the same Quick Start flow before starting the browser.
|
||||
|
||||
| Path | What it is |
|
||||
|------|------------|
|
||||
| `~/.nanobot/config.json` | Main settings file for providers, models, channels, tools, gateway, and API |
|
||||
| `~/.nanobot/workspace/` | Agent workspace for memory, sessions, heartbeat tasks, skills, and artifacts |
|
||||
## 3. Check the Setup
|
||||
|
||||
If you already have a config, `nanobot onboard` can refresh missing default fields without overwriting your existing values. Use `nanobot onboard --refresh` to do the same refresh without an interactive prompt.
|
||||
```bash
|
||||
nanobot status
|
||||
```
|
||||
|
||||
## 3. Configure a Provider
|
||||
You want:
|
||||
|
||||
Skip this section if you already configured provider and model settings in the wizard.
|
||||
- a check mark for **Config** and **Workspace**;
|
||||
- the model or preset you selected;
|
||||
- a configured state for the provider used by that model.
|
||||
|
||||
Open `~/.nanobot/config.json`. Add or merge these blocks into the file created by `nanobot onboard`; do not replace the whole file unless you want to reset the config.
|
||||
Most other providers can say `not set`. This command validates local setup but does not call the model.
|
||||
|
||||
**API key:**
|
||||
## 4. Get the First Reply
|
||||
|
||||
```bash
|
||||
nanobot gateway
|
||||
```
|
||||
|
||||
Quick Start has already prepared the local WebSocket channel. Leave the gateway terminal open and visit `http://127.0.0.1:8765`; the first-run WebUI is bound to localhost, so other devices on your network cannot reach it. On current source versions, you can run `nanobot webui` instead to perform the local WebUI checks, start the gateway, and open the browser automatically.
|
||||
|
||||
Send:
|
||||
|
||||
```text
|
||||
Hello!
|
||||
```
|
||||
|
||||
Any normal assistant answer is success. It proves that nanobot can load the config, reach the selected model, use the workspace, and serve the browser UI.
|
||||
|
||||
Leave the terminal open while using the WebUI. If you prefer a managed background process, stop the foreground process with `Ctrl+C`, then run:
|
||||
|
||||
```bash
|
||||
nanobot gateway --background
|
||||
nanobot gateway status
|
||||
```
|
||||
|
||||
Use `nanobot gateway logs`, `restart`, and `stop` to manage that background gateway.
|
||||
|
||||
## Terminal-Only Check
|
||||
|
||||
If you do not want the browser or need to isolate a WebUI problem, send one message directly:
|
||||
|
||||
```bash
|
||||
nanobot agent -m "Hello!"
|
||||
```
|
||||
|
||||
Then start an interactive terminal chat with:
|
||||
|
||||
```bash
|
||||
nanobot agent
|
||||
```
|
||||
|
||||
In interactive mode, `Enter` sends and `Alt+Enter` inserts a newline. Exit with `exit`, `/exit`, `:q`, or `Ctrl+D`.
|
||||
|
||||
## Choose One Next Step
|
||||
|
||||
After the first reply works, add one capability and test again:
|
||||
|
||||
| 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 |
|
||||
| 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) |
|
||||
| Schedule agent work | Read [Automations](./automations.md) |
|
||||
| Run continuously or remotely | Read [Deployment](./deployment.md) |
|
||||
| Integrate from code | Use the [Python SDK](./python-sdk.md) or [OpenAI-Compatible API](./openai-api.md) |
|
||||
|
||||
## Other Install Methods
|
||||
|
||||
Use one method, then continue at [Complete Quick Start](#2-complete-quick-start).
|
||||
|
||||
**uv**
|
||||
|
||||
```bash
|
||||
uv tool install nanobot-ai
|
||||
nanobot onboard --wizard
|
||||
```
|
||||
|
||||
**pip in a virtual environment**
|
||||
|
||||
```bash
|
||||
python -m pip install nanobot-ai
|
||||
nanobot onboard --wizard
|
||||
```
|
||||
|
||||
If pip reports `externally-managed-environment`, use the recommended installer, `uv tool install nanobot-ai`, `pipx install nanobot-ai`, or create a virtual environment. Do not force a system-wide install.
|
||||
|
||||
**Current source**
|
||||
|
||||
`bun` or `npm` must be available. Activate a virtual environment first, then run:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/HKUDS/nanobot.git
|
||||
cd nanobot
|
||||
python -m pip install .
|
||||
nanobot onboard --wizard
|
||||
```
|
||||
|
||||
On Windows, if `python -m pip install .` reports that it cannot launch `npm`, run `cd webui`, `npm.cmd install --package-lock=false`, `npm.cmd run build`, and `cd ..` in order, then retry the install.
|
||||
|
||||
The source path follows current `main` and can be newer than the published package. A non-editable install triggers the build hook that bundles the current WebUI. For editable Python or frontend development, follow [`../CONTRIBUTING.md`](../CONTRIBUTING.md) and [`../webui/README.md`](../webui/README.md).
|
||||
|
||||
If the package is installed but the shell cannot find `nanobot`, use the runner that owns the installation. The recommended installer prints the exact command to reuse. Common forms are:
|
||||
|
||||
```bash
|
||||
uv tool run --from nanobot-ai nanobot --version
|
||||
pipx run --spec nanobot-ai nanobot --version
|
||||
~/.nanobot/venv/bin/python -m nanobot --version
|
||||
```
|
||||
|
||||
On Windows, the managed-environment form is `& "$HOME\.nanobot\venv\Scripts\python.exe" -m nanobot --version`. Replace `--version` with `onboard --wizard`, `gateway`, or any other arguments you need. Use plain `python -m nanobot` only when that Python executable belongs to the environment where nanobot was installed.
|
||||
|
||||
## Manual Configuration Fallback
|
||||
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"custom": {
|
||||
"apiKey": "your-api-key",
|
||||
"apiKey": "${PROVIDER_API_KEY}",
|
||||
"apiBase": "https://api.example.com/v1"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Model preset:**
|
||||
|
||||
```json
|
||||
{
|
||||
},
|
||||
"modelPresets": {
|
||||
"primary": {
|
||||
"label": "Primary",
|
||||
"provider": "custom",
|
||||
"model": "model-id-from-your-provider",
|
||||
"maxTokens": 8192,
|
||||
"contextWindowTokens": 65536,
|
||||
"temperature": 0.1
|
||||
"model": "model-id-from-your-provider"
|
||||
}
|
||||
},
|
||||
"agents": {
|
||||
@@ -158,192 +202,48 @@ Open `~/.nanobot/config.json`. Add or merge these blocks into the file created b
|
||||
}
|
||||
```
|
||||
|
||||
The provider and model inside a preset must match. The snippet above is only an example. For another provider, replace these values together:
|
||||
|
||||
| Replace | Where |
|
||||
|---|---|
|
||||
| Provider config key, such as `custom` | `providers.<provider>` |
|
||||
| API key or environment variable | `providers.<provider>.apiKey` |
|
||||
| Preset provider name | `modelPresets.primary.provider` |
|
||||
| Model ID | `modelPresets.primary.model` |
|
||||
| Endpoint URL, only when needed | `providers.<provider>.apiBase` |
|
||||
|
||||
Direct `agents.defaults.provider` and `agents.defaults.model` still work for existing configs, but named presets are the recommended path because they also power `/model` switching and fallback chains. For provider-specific examples across direct, gateway, OAuth, cloud, and local setups, see [`providers.md`](./providers.md).
|
||||
|
||||
**What about `apiBase` / base URL?**
|
||||
|
||||
`apiBase` is the HTTP base URL of the provider endpoint, not the model name. Most hosted providers in nanobot already know their default endpoint, so you usually only set `apiKey` and a model preset. Set `apiBase` when you are using:
|
||||
|
||||
- `custom` for a third-party or self-hosted OpenAI-compatible API;
|
||||
- a local OpenAI-compatible server such as Ollama, vLLM, or LM Studio;
|
||||
- a provider-specific alternate endpoint, regional endpoint, proxy, or subscription endpoint.
|
||||
|
||||
Examples:
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"custom": {
|
||||
"apiKey": "${CUSTOM_API_KEY}",
|
||||
"apiBase": "https://api.example.com/v1"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"ollama": {
|
||||
"apiBase": "http://localhost:11434/v1"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If the provider's docs say the endpoint is `/v1`, include `/v1` in `apiBase`. The model ID still belongs in the active `modelPresets` entry.
|
||||
|
||||
If you prefer not to store secrets in `config.json`, reference an environment variable and set it before starting nanobot:
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"custom": {
|
||||
"apiKey": "${PROVIDER_API_KEY}",
|
||||
"apiBase": "https://api.example.com/v1"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 4. Check the Setup
|
||||
|
||||
```bash
|
||||
nanobot status
|
||||
```
|
||||
|
||||
This should show the config path, workspace path, active model or preset, and provider summary. It does not send a message to the model, so use it as a quick config check before the first real request.
|
||||
|
||||
Read it like this:
|
||||
|
||||
| Status line | What you want |
|
||||
|---|---|
|
||||
| `Config` | A check mark. |
|
||||
| `Workspace` | A check mark. |
|
||||
| `Model` | The model or preset you expect. |
|
||||
| Provider list | Most providers can say `not set`; the provider used by the active preset should show a check mark, OAuth status, or local URL. |
|
||||
|
||||
## 5. Open the WebUI
|
||||
|
||||
Start the browser workbench:
|
||||
|
||||
```bash
|
||||
nanobot webui
|
||||
```
|
||||
|
||||
`nanobot webui` prepares the local WebSocket channel and WebUI bootstrap secret if needed, starts the gateway, and opens `http://127.0.0.1:8765`. First-run WebUI setup binds to `127.0.0.1` by default, so it is not exposed to your LAN. Use `nanobot webui --background` when you want the gateway to keep running without an open terminal.
|
||||
|
||||
## 6. Test One CLI Message
|
||||
|
||||
Use this path if you skipped Quick Start, declined the WebSocket channel, or want a terminal-only check.
|
||||
|
||||
Run a one-shot CLI message:
|
||||
|
||||
```bash
|
||||
nanobot agent -m "Hello!"
|
||||
```
|
||||
|
||||
A successful first run proves that:
|
||||
|
||||
- the `nanobot` command is installed;
|
||||
- `~/.nanobot/config.json` can be loaded;
|
||||
- the selected provider and model can answer;
|
||||
- the default workspace can be created and used.
|
||||
|
||||
The reply text itself will vary. Any normal assistant answer means the install, config, provider, model, and workspace path are all usable.
|
||||
|
||||
If that works, start an interactive CLI chat:
|
||||
|
||||
```bash
|
||||
nanobot agent
|
||||
```
|
||||
|
||||
After the interactive session can answer normally, nanobot can help with its own next setup step. Ask it to read the relevant docs, inspect your current `~/.nanobot/config.json`, and make one concrete change such as enabling WebUI, adding a provider preset, or configuring one chat channel. When nanobot says the config is updated, run `/restart` in the chat or restart the nanobot process manually so long-running processes reload `config.json`.
|
||||
|
||||
Example prompt:
|
||||
|
||||
```text
|
||||
Read docs/quick-start.md, docs/providers.md, and docs/configuration.md in this checkout.
|
||||
Then update ~/.nanobot/config.json to add a model preset named "primary" for my provider.
|
||||
Tell me exactly what changed and whether I need to run /restart.
|
||||
```
|
||||
|
||||
In interactive mode, `Enter` sends the current message. Press `Alt+Enter` to add a newline before sending.
|
||||
|
||||
Exit interactive mode with `exit`, `quit`, `/exit`, `/quit`, `:q`, or `Ctrl+D`.
|
||||
|
||||
## 7. Choose Your Next Step
|
||||
|
||||
| Want to... | Go to |
|
||||
|---|---|
|
||||
| Understand config, workspace, gateway, channels, memory, and tools | [`concepts.md`](./concepts.md) |
|
||||
| Copy another provider or local model setup | [`provider-cookbook.md`](./provider-cookbook.md) |
|
||||
| Understand provider/model matching | [`providers.md`](./providers.md) |
|
||||
| Open the bundled browser UI | [`webui.md`](./webui.md) |
|
||||
| Connect Telegram, Discord, WeChat, Slack, Email, Mattermost, or another chat app | [`chat-apps.md`](./chat-apps.md) |
|
||||
| Configure web search, MCP, security, memory, gateway, or runtime settings | [`configuration.md`](./configuration.md) |
|
||||
| Run with Docker, systemd, or LaunchAgent | [`deployment.md`](./deployment.md) |
|
||||
| Debug a failure | [`troubleshooting.md`](./troubleshooting.md) |
|
||||
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.
|
||||
|
||||
## Updating
|
||||
|
||||
**pip:**
|
||||
Upgrade with the same method you used to install:
|
||||
|
||||
```bash
|
||||
python -m pip install -U nanobot-ai
|
||||
nanobot --version
|
||||
```
|
||||
# Recommended installer
|
||||
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh
|
||||
|
||||
If pip reports `externally-managed-environment`, upgrade with the same isolated method you used to install nanobot, such as `uv tool upgrade nanobot-ai`, `pipx upgrade nanobot-ai`, or the managed venv created by the one-command installer.
|
||||
|
||||
**uv:**
|
||||
|
||||
```bash
|
||||
# Or one of these
|
||||
uv tool upgrade nanobot-ai
|
||||
nanobot --version
|
||||
```
|
||||
|
||||
**pipx:**
|
||||
|
||||
```bash
|
||||
pipx upgrade nanobot-ai
|
||||
nanobot --version
|
||||
python -m pip install -U nanobot-ai
|
||||
```
|
||||
|
||||
**Source checkout:**
|
||||
For a source checkout:
|
||||
|
||||
```bash
|
||||
git pull
|
||||
python -m pip install -e .
|
||||
nanobot --version
|
||||
python -m pip install .
|
||||
```
|
||||
|
||||
If you use WhatsApp from a source checkout, keep the optional dependencies installed:
|
||||
Then check `nanobot --version`. Run `nanobot onboard --refresh` when you want to add newly introduced default fields while preserving existing settings.
|
||||
|
||||
## If the First Reply Fails
|
||||
|
||||
Do not change several settings at once. Start with:
|
||||
|
||||
```bash
|
||||
nanobot plugins enable whatsapp
|
||||
nanobot --version
|
||||
nanobot status
|
||||
nanobot agent -m "Hello!"
|
||||
```
|
||||
|
||||
## First-Run Troubleshooting
|
||||
| Symptom | First check |
|
||||
|---|---|
|
||||
| `nanobot: command not found` | Reuse the installer command or method-specific runner described under [Other Install Methods](#other-install-methods) |
|
||||
| JSON parse error | Check commas and braces; remember that docs examples are usually snippets |
|
||||
| `401` or invalid API key | Verify the selected provider owns that key and remove accidental spaces |
|
||||
| Model not found | Use a model ID available from the provider selected in the active preset |
|
||||
| CLI works but WebUI does not open | Use port `8765`, not gateway health port `18790` |
|
||||
| WebUI works but a chat app does not | Check **Settings → Channels**, then run `nanobot channels status` |
|
||||
|
||||
| Symptom | What to check |
|
||||
|---------|---------------|
|
||||
| `nanobot: command not found` | Use `python -m nanobot ...`, or add your Python scripts directory to `PATH`. |
|
||||
| `ModuleNotFoundError: nanobot` | Confirm you installed into the same Python environment that is running the command. |
|
||||
| JSON parse errors | Check commas and braces in `~/.nanobot/config.json`; examples above are partial snippets to merge. |
|
||||
| Authentication or 401 errors | Check that the API key is valid, copied without spaces, and placed under the provider you selected. |
|
||||
| Provider/model errors | Make sure the active preset uses the provider that owns your API key and that the model exists there. |
|
||||
| The CLI works but a chat app does not reply | First keep `nanobot gateway` running, then follow [`chat-apps.md`](./chat-apps.md). |
|
||||
| WebUI does not open | Run `nanobot webui`; the browser UI uses port `8765`, not the gateway health port `18790`. |
|
||||
|
||||
For a fuller diagnosis flow, see [`troubleshooting.md`](./troubleshooting.md).
|
||||
Continue with the ordered [Troubleshooting guide](./troubleshooting.md) if the cause is still unclear.
|
||||
|
||||
@@ -1,76 +1,62 @@
|
||||
# Start Without Technical Background
|
||||
|
||||
This page is for you if you have never used a terminal, edited a JSON file, or configured an AI model before.
|
||||
This walkthrough is for people who have not used a terminal, API key, or JSON config file before. The goal is only to get one reply in a browser. You do not need to understand nanobot's architecture or edit its config by hand.
|
||||
|
||||
The goal is small: get one local nanobot reply in your browser. Do not connect Telegram, Discord, Docker, local models, or deployment yet. Those are easier after the first reply works.
|
||||
## What You Will Need
|
||||
|
||||
## What You Are Setting Up
|
||||
- A Windows, macOS, or Linux computer.
|
||||
- Python 3.11 or newer.
|
||||
- An account or endpoint that can run an AI model.
|
||||
- The API key, login, endpoint, and model name required by that service. A local model such as Ollama may not require an API key.
|
||||
|
||||
You only need these words for Quick Start:
|
||||
An API key is password-like. Do not post it in an issue, screenshot, chat, or public config file.
|
||||
|
||||
| Word | Plain meaning |
|
||||
## A Few Useful Words
|
||||
|
||||
| Word | Meaning |
|
||||
|---|---|
|
||||
| Terminal | A text window where you paste commands and press Enter. |
|
||||
| Command | One line of text you run in the terminal. |
|
||||
| API key | A password-like token from an AI provider. Do not share it publicly. |
|
||||
| Config file | The settings file nanobot reads when it starts. |
|
||||
| Wizard | An interactive terminal menu that edits the config file for you. |
|
||||
| Browser UI | The local web page where you chat with nanobot. |
|
||||
| Terminal | A text window where you paste a command and press Enter |
|
||||
| Command | One instruction typed into the terminal |
|
||||
| Provider | The service or local server that runs the AI model |
|
||||
| Model ID | The exact model name expected by that provider |
|
||||
| API key | A secret credential that lets software call the provider |
|
||||
| Wizard | A question-and-answer setup menu |
|
||||
| WebUI | The local browser page where you use nanobot |
|
||||
|
||||
## 1. Open a Terminal
|
||||
## 1. Install Python
|
||||
|
||||
You will paste commands into a terminal. Copy only the command text inside each code block; do not copy the ``` marks.
|
||||
Download Python from [python.org](https://www.python.org/downloads/) if you do not already have version 3.11 or newer. On Windows, enable **Add python.exe to PATH** if the installer shows that option.
|
||||
|
||||
| System | How to open it |
|
||||
Open a terminal:
|
||||
|
||||
| System | How |
|
||||
|---|---|
|
||||
| Windows | Press `Win`, type `PowerShell`, then open **Windows PowerShell**. |
|
||||
| macOS | Press `Command` + `Space`, type `Terminal`, then press `Enter`. |
|
||||
| Linux | Open your app launcher, search for `Terminal`, then open it. |
|
||||
| Windows | Press `Win`, type `PowerShell`, and open Windows PowerShell |
|
||||
| macOS | Press `Command+Space`, type `Terminal`, and press Enter |
|
||||
| Linux | Open your application menu and search for Terminal |
|
||||
|
||||
When the terminal opens, click inside it, paste the command, and press `Enter`. If a command prints text and returns to a prompt, that is usually normal.
|
||||
|
||||
## 2. Install Python
|
||||
|
||||
Install Python 3.11 or newer from [python.org](https://www.python.org/downloads/).
|
||||
|
||||
On Windows, enable **Add python.exe to PATH** during installation if the installer shows that option.
|
||||
|
||||
In that terminal, check Python:
|
||||
Check Python:
|
||||
|
||||
```bash
|
||||
python --version
|
||||
```
|
||||
|
||||
If Windows says `python` is not found, close and reopen PowerShell. If it still does not work, try:
|
||||
The result should start with `Python 3.11` or a newer number. If the command is not found, close and reopen the terminal. You can also try `python3 --version` on macOS/Linux or `py --version` on Windows.
|
||||
|
||||
```bash
|
||||
py --version
|
||||
```
|
||||
## 2. Prepare Your Model Details
|
||||
|
||||
If `py` works but `python` does not, replace `python` with `py` in the commands below.
|
||||
nanobot does not create an AI provider account for you. Before setup, have these details nearby:
|
||||
|
||||
If macOS or Linux says `python` is not found, try:
|
||||
1. The provider or company endpoint name.
|
||||
2. Its API key, if it requires one.
|
||||
3. Its base URL, if its documentation gives you one.
|
||||
4. A model ID your account can use.
|
||||
|
||||
```bash
|
||||
python3 --version
|
||||
```
|
||||
The provider, credential, endpoint, and model must belong together. For example, an API key from one provider usually cannot call a model name copied from a different provider.
|
||||
|
||||
If `python3` works but `python` does not, replace `python` with `python3` in the manual commands below. The one-command installer already checks both `python3` and `python`.
|
||||
## 3. Install nanobot
|
||||
|
||||
## 3. Get a Provider API Key
|
||||
|
||||
nanobot does not create AI accounts or API keys for you. Use an AI provider account, company endpoint, subscription endpoint, or local model server that you already control. If the provider has an OpenAI-compatible base URL in its docs, keep that nearby too.
|
||||
|
||||
For the setup path:
|
||||
|
||||
1. Open your provider's API key page.
|
||||
2. Create or copy an API key.
|
||||
3. Keep the key private.
|
||||
4. Keep the provider's base URL nearby if the provider docs show one.
|
||||
|
||||
## 4. Install nanobot
|
||||
|
||||
The easiest path is the one-command installer. It installs or upgrades nanobot, then starts the setup wizard. On macOS and Linux it avoids system-wide pip installs by using an active virtual environment, `uv`, `pipx`, or a managed venv under `~/.nanobot/venv`.
|
||||
Copy the command for your system, paste it into the terminal, and press Enter. Copy only the text inside the code block.
|
||||
|
||||
**macOS / Linux**
|
||||
|
||||
@@ -84,75 +70,13 @@ curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.
|
||||
irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex
|
||||
```
|
||||
|
||||
These commands install the stable PyPI package. To preview what the installer would do without changing your environment, pass `--dry-run`:
|
||||
The installer downloads the stable nanobot package into an isolated Python environment and opens the setup wizard. It can take a few minutes on the first run. When it finishes, it prints the exact command it used to run nanobot. Keep that command: if `nanobot` is not found later, reuse the whole printed command instead of switching to a different Python command.
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dry-run
|
||||
```
|
||||
If your organization blocks downloaded install scripts, use the [alternative install methods](./quick-start.md#other-install-methods) or ask your administrator to review the scripts first.
|
||||
|
||||
```powershell
|
||||
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dry-run
|
||||
```
|
||||
## 4. Follow Quick Start
|
||||
|
||||
Use the development installer only when a maintainer asks you to test the current `main` branch:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dev
|
||||
```
|
||||
|
||||
```powershell
|
||||
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dev
|
||||
```
|
||||
|
||||
If the command says `curl` or `irm` is not found, or it cannot download from GitHub, use one of the manual install commands below.
|
||||
|
||||
If `uv` is installed, use:
|
||||
|
||||
```bash
|
||||
uv tool install nanobot-ai
|
||||
```
|
||||
|
||||
If you prefer pip, use it only inside an environment you control:
|
||||
|
||||
```bash
|
||||
python -m pip install nanobot-ai
|
||||
```
|
||||
|
||||
If pip reports `externally-managed-environment` on macOS or Linux, go back to the one-command installer, use `uv tool install nanobot-ai`, use `pipx install nanobot-ai`, or create a virtual environment first.
|
||||
|
||||
Then check that nanobot is installed:
|
||||
|
||||
```bash
|
||||
nanobot --version
|
||||
```
|
||||
|
||||
If the terminal cannot find `nanobot`, use the module form:
|
||||
|
||||
```bash
|
||||
python -m nanobot --version
|
||||
```
|
||||
|
||||
Use `python3 -m nanobot --version` or `py -m nanobot --version` if that is the Python command that worked in step 2.
|
||||
|
||||
## 5. Run the Setup Wizard
|
||||
|
||||
The one-command installer starts this for you after installation. If you installed manually, run:
|
||||
|
||||
```bash
|
||||
nanobot onboard --wizard
|
||||
```
|
||||
|
||||
If `nanobot` is not found, run:
|
||||
|
||||
```bash
|
||||
python -m nanobot onboard --wizard
|
||||
```
|
||||
|
||||
Use `python3 -m nanobot onboard --wizard` or `py -m nanobot onboard --wizard` if that is the Python command that worked in step 2.
|
||||
|
||||
The wizard is a terminal menu. It is not a graphical app, but it lets you choose options instead of hand-editing every JSON field.
|
||||
|
||||
You will see a menu like this:
|
||||
The wizard shows a menu similar to:
|
||||
|
||||
```text
|
||||
> What would you like to do?
|
||||
@@ -161,259 +85,97 @@ You will see a menu like this:
|
||||
[X] Exit
|
||||
```
|
||||
|
||||
Move through the wizard like this:
|
||||
Choose **Quick Start**. Use the arrow keys to highlight an option and press `Enter`.
|
||||
|
||||
| When you see | Do this |
|
||||
|---|---|
|
||||
| A menu | Use the arrow keys to highlight an option, then press `Enter`. |
|
||||
| The provider menu | Choose the company or service you want to use. |
|
||||
| An endpoint menu | Choose the standard API or subscription plan endpoint that matches your key. |
|
||||
| An API key field | Paste the key, then press `Enter`. |
|
||||
| A provider base URL field | Paste the provider base URL from its docs, then press `Enter`. |
|
||||
| The Model ID field | Paste a model name from your provider, then press `Enter`. |
|
||||
| A back option in Advanced Settings | Choose it to return to the previous menu. |
|
||||
The wizard asks for only the information needed for the first reply:
|
||||
|
||||
For the first setup, choose `[Q] Quick Start`. It configures the recommended local browser UI and default AI settings for you. Use `Advanced Settings` later only if you need a chat app, a tool setup, or provider-specific fields.
|
||||
1. Choose your provider.
|
||||
2. Choose an endpoint option if the provider offers several plans.
|
||||
3. Paste the API key if asked.
|
||||
4. Enter the base URL if asked.
|
||||
5. Enter a model ID.
|
||||
6. Confirm the local WebUI setup.
|
||||
7. Choose a WebUI password.
|
||||
8. Review the summary and save.
|
||||
|
||||
1. Choose `[Q] Quick Start`.
|
||||
2. Choose the provider you want to use.
|
||||
3. Choose the endpoint if the wizard asks, such as Standard API, Coding Plan, Token Plan, or Step Plan.
|
||||
4. Paste your API key if the wizard asks for one.
|
||||
5. Paste the provider base URL if the wizard asks for one.
|
||||
6. Paste a model ID that provider can run.
|
||||
7. Confirm that Quick Start should configure the local WebUI.
|
||||
8. Set the WebUI password when prompted.
|
||||
9. Review the Quick Start summary. The wizard saves and exits when Quick Start finishes.
|
||||
When you paste a password or API key, the terminal may hide the characters. That is normal.
|
||||
|
||||
The recommended path configures the local WebUI, requires a WebUI password, and writes default AI settings. You do not need to choose a separate chat app for the first run.
|
||||
|
||||
If you already know that you need custom headers, provider-specific request fields, a chat app, or tools, choose `Advanced Settings` instead. [`provider-cookbook.md`](./provider-cookbook.md) has copyable examples for several common provider setups. After you change advanced settings, a save option appears in the main menu. Choose `[S] Save and Exit`.
|
||||
|
||||
The wizard creates or updates:
|
||||
|
||||
| Path | Meaning |
|
||||
|---|---|
|
||||
| `~/.nanobot/config.json` | Settings file. |
|
||||
| `~/.nanobot/workspace/` | Working folder for memory, sessions, and generated files. |
|
||||
|
||||
If Quick Start finished successfully, skip to [Open the WebUI](#7-open-the-webui). The next two sections are only for manual setup.
|
||||
|
||||
## Manual Setup: How to Merge JSON Snippets
|
||||
|
||||
Most docs examples are snippets, not whole files. Your `config.json` has one outer `{ ... }`. Add new top-level sections such as `providers`, `modelPresets`, `agents`, or `channels` inside that same outer object.
|
||||
|
||||
Do not paste two separate JSON objects into one file:
|
||||
|
||||
```text
|
||||
{
|
||||
"providers": { "...": "..." }
|
||||
}
|
||||
{
|
||||
"channels": { "...": "..." }
|
||||
}
|
||||
```
|
||||
|
||||
Merge them into one object:
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"custom": {
|
||||
"apiKey": "your-api-key",
|
||||
"apiBase": "https://api.example.com/v1"
|
||||
}
|
||||
},
|
||||
"channels": {
|
||||
"websocket": {
|
||||
"tokenIssueSecret": "your-webui-password",
|
||||
"websocketRequiresToken": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notice the comma after the `providers` block. JSON needs commas between sibling sections, but not after the last section. If this feels hard, use `nanobot onboard --wizard` whenever possible.
|
||||
|
||||
## 6. Manual Setup: Config Fallback
|
||||
|
||||
Use this only if the wizard is unavailable or you prefer opening the file yourself.
|
||||
|
||||
Run `nanobot onboard` first if `~/.nanobot/config.json` does not exist yet.
|
||||
|
||||
Use one of these commands:
|
||||
|
||||
**Windows PowerShell**
|
||||
|
||||
```powershell
|
||||
notepad "$env:USERPROFILE\.nanobot\config.json"
|
||||
```
|
||||
|
||||
**macOS**
|
||||
If the installer finishes without opening the wizard and `nanobot` is available, run:
|
||||
|
||||
```bash
|
||||
open -e ~/.nanobot/config.json
|
||||
nanobot onboard --wizard
|
||||
```
|
||||
|
||||
**Linux**
|
||||
If the terminal cannot find `nanobot`, take the exact command printed by the installer and replace its final arguments with `onboard --wizard`. That command may begin with `uv tool run`, `pipx run`, or the full path to nanobot's private Python environment.
|
||||
|
||||
## 5. Open the Browser
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
xdg-open ~/.nanobot/config.json
|
||||
nanobot gateway
|
||||
```
|
||||
|
||||
If this is a brand-new install and you have not configured anything else yet, replace the file with this minimal config:
|
||||
Leave the terminal open, then open `http://127.0.0.1:8765` in your browser. Enter the WebUI password from the wizard if the browser asks for it. Current source versions also provide `nanobot webui`, which starts the gateway and opens the browser automatically.
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"custom": {
|
||||
"apiKey": "your-api-key",
|
||||
"apiBase": "https://api.example.com/v1"
|
||||
}
|
||||
},
|
||||
"modelPresets": {
|
||||
"primary": {
|
||||
"label": "Primary",
|
||||
"provider": "custom",
|
||||
"model": "model-id-from-your-provider",
|
||||
"maxTokens": 4096,
|
||||
"contextWindowTokens": 65536,
|
||||
"temperature": 0.1
|
||||
}
|
||||
},
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"modelPreset": "primary"
|
||||
}
|
||||
},
|
||||
"channels": {
|
||||
"websocket": {
|
||||
"tokenIssueSecret": "your-webui-password",
|
||||
"websocketRequiresToken": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Replace `your-api-key`, `https://api.example.com/v1`, `model-id-from-your-provider`, and `your-webui-password` with your own values.
|
||||
|
||||
For copyable provider-specific examples, use [`provider-cookbook.md`](./provider-cookbook.md).
|
||||
|
||||
Save the file.
|
||||
|
||||
## 7. Open the WebUI
|
||||
|
||||
First check that nanobot can read the saved setup:
|
||||
|
||||
```bash
|
||||
nanobot status
|
||||
```
|
||||
|
||||
This should show the config file path, workspace path, and the active model or preset. If `nanobot` is not found, use `python -m nanobot status`, `python3 -m nanobot status`, or `py -m nanobot status`, matching the Python command that worked in step 2.
|
||||
|
||||
It is normal for most providers to say `not set`. Only the provider you selected for the active preset needs to look configured.
|
||||
|
||||
Start the local browser UI:
|
||||
|
||||
```bash
|
||||
nanobot webui
|
||||
```
|
||||
|
||||
This starts nanobot and opens `http://127.0.0.1:8765` in your browser. Leave the terminal open while you use the WebUI. Enter the WebUI password you set in the wizard if the browser asks for one.
|
||||
|
||||
Send this first message in the browser:
|
||||
Send this message:
|
||||
|
||||
```text
|
||||
Hello!
|
||||
```
|
||||
|
||||
If that works, nanobot is installed and can call the model. You should see a normal assistant reply in the browser. The exact words will differ, but it should look like this shape:
|
||||
A normal assistant reply means setup is complete. The exact reply does not matter.
|
||||
|
||||
```text
|
||||
Hello! How can I help you today?
|
||||
```
|
||||
The first-run address is local to your computer. It is not automatically available to other computers on your network.
|
||||
|
||||
If `nanobot` is not found, run:
|
||||
## 6. Add One Thing at a Time
|
||||
|
||||
Do not configure every feature immediately. Choose one next goal:
|
||||
|
||||
| Goal | What to do |
|
||||
|---|---|
|
||||
| Change the AI model | Open **Settings → Models** |
|
||||
| Add a provider credential | Open **Settings → Models**, then find the provider |
|
||||
| Connect Telegram, Discord, Slack, Feishu, WeChat, or another chat app | Open **Settings → 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 |
|
||||
|
||||
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.
|
||||
|
||||
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 gateway` 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).
|
||||
|
||||
## If Something Fails
|
||||
|
||||
Run these commands one at a time:
|
||||
|
||||
```bash
|
||||
python -m nanobot webui
|
||||
nanobot --version
|
||||
nanobot status
|
||||
nanobot agent -m "Hello!"
|
||||
```
|
||||
|
||||
Use `python3 -m nanobot webui` or `py -m nanobot webui` if that is the Python command that worked in step 2.
|
||||
|
||||
Once this works, nanobot can help with its own next setup step. In the browser UI, ask it to read these docs and update your current config for one specific goal, then run `/restart` when nanobot tells you the config is ready. For example, ask it to add one provider preset or configure one chat app.
|
||||
|
||||
## 8. If Something Fails
|
||||
|
||||
Do not change many things at once. Check the exact error:
|
||||
|
||||
| Error or symptom | What it usually means |
|
||||
| What you see | What it usually means |
|
||||
|---|---|
|
||||
| `JSON parse error` | The config file has a missing comma, extra comma, or mismatched brace. Copy the example again. |
|
||||
| `401`, `unauthorized`, or `invalid API key` | The API key is wrong, expired, has extra spaces, or was pasted under the wrong provider. |
|
||||
| `model not found` | Your account cannot use the default model. Return to `nanobot onboard --wizard`, choose `Advanced Settings`, then edit `Model Presets`. |
|
||||
| `nanobot: command not found` | The install worked in Python, but your shell cannot find the script. Use `python -m nanobot ...`, `python3 -m nanobot ...`, or `py -m nanobot ...`, matching the Python command that worked earlier. |
|
||||
| No response after editing config | Restart the command. Long-running processes read config when they start. |
|
||||
| `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 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 |
|
||||
|
||||
For a fuller diagnosis path, see [`troubleshooting.md`](./troubleshooting.md).
|
||||
If you ask for help, include your operating system, `nanobot --version`, `nanobot status`, the exact command, and the exact error. Remove every API key, bot token, password, OAuth token, and private account ID first.
|
||||
|
||||
## What Not to Configure Yet
|
||||
Continue with the full [Troubleshooting guide](./troubleshooting.md) for an ordered diagnosis.
|
||||
|
||||
Skip these until the first local message works:
|
||||
|
||||
- `apiBase`: hosted built-in providers often already have default endpoints. You only need `apiBase` for local models, proxies, custom OpenAI-compatible providers, or special regional/subscription endpoints.
|
||||
- chat apps: first prove the local browser UI can answer.
|
||||
- fallback models: useful later, but not needed for the first reply.
|
||||
- Langfuse: useful for observability, but not needed for first setup.
|
||||
|
||||
## Next Steps
|
||||
|
||||
After the first reply works, choose only one next goal. Keep the terminal that runs `nanobot webui` open whenever you use the WebUI. Chat apps use the same gateway service underneath.
|
||||
|
||||
### Open the Browser UI Again
|
||||
## Open nanobot Later
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
nanobot webui
|
||||
```
|
||||
|
||||
Leave that terminal open; the browser should open automatically.
|
||||
|
||||
To stop the WebUI later, return to the gateway terminal and press `Ctrl+C`.
|
||||
|
||||
If `nanobot` is not found, run `python -m nanobot webui`, `python3 -m nanobot webui`, or `py -m nanobot webui`, matching the Python command that worked earlier. More details are in [`webui.md`](./webui.md).
|
||||
|
||||
### Connect a Chat App
|
||||
|
||||
1. Read the section for one app in [`chat-apps.md`](./chat-apps.md).
|
||||
2. Add only that app's config snippet. Merge it into the existing file instead of replacing the whole file.
|
||||
3. Run:
|
||||
|
||||
```bash
|
||||
nanobot channels status
|
||||
nanobot gateway
|
||||
```
|
||||
|
||||
4. Leave the gateway terminal open, then send a message from the allowed account.
|
||||
|
||||
Start with a private chat or a test server. Do not set `allowFrom` to `["*"]` unless you intentionally want anyone who can reach that channel to talk to the bot.
|
||||
|
||||
### Change Models or Add Backups
|
||||
|
||||
Use [`providers.md`](./providers.md) when a provider/model pair fails, and [`provider-cookbook.md`](./provider-cookbook.md) when you want copyable snippets. Keep model choices in `modelPresets`, then select the active one with `agents.defaults.modelPreset`.
|
||||
|
||||
### Ask for Help
|
||||
|
||||
When you ask for help, include:
|
||||
|
||||
- your operating system;
|
||||
- the command you ran;
|
||||
- `nanobot --version`;
|
||||
- `nanobot status`;
|
||||
- whether the browser UI can answer `Hello!`;
|
||||
- the exact error text;
|
||||
- a config snippet with API keys and tokens removed.
|
||||
|
||||
Never paste real API keys, bot tokens, OAuth tokens, or private chat IDs into a public issue or chat.
|
||||
|
||||
If you find a docs mistake, outdated command, or confusing step, please open an issue: <https://github.com/HKUDS/nanobot/issues>.
|
||||
Leave that terminal open and visit `http://127.0.0.1:8765`. To stop nanobot, return to the terminal and press `Ctrl+C`. Use `nanobot gateway --background` only after the normal foreground start works; then manage it with `nanobot gateway status`, `logs`, `restart`, and `stop`.
|
||||
|
||||
+30
-3
@@ -53,6 +53,18 @@ WebUI beyond localhost or want a browser password:
|
||||
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.
|
||||
|
||||
## First 10 Minutes
|
||||
|
||||
Use the WebUI as the primary setup surface after Quick Start:
|
||||
|
||||
1. Send `Hello!` in a new chat to prove the selected model works.
|
||||
2. Open **Settings → Models** and confirm the active model preset.
|
||||
3. Start a separate chat 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**.
|
||||
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.
|
||||
|
||||
## What It Is For
|
||||
|
||||
| Area | Use it for |
|
||||
@@ -62,6 +74,7 @@ gateway health endpoint, `18790` by default, is not the browser UI.
|
||||
| Workspace | Pick the project workspace before asking for file or shell work |
|
||||
| Access | Choose the access mode for local capabilities allowed by your gateway configuration |
|
||||
| Composer | Send text, images, voice input, slash commands, and `@` mentions for Apps or MCP presets |
|
||||
| Channels | Connect and validate chat platforms, install their optional support, and manage saved channel setup |
|
||||
| Apps | Install, test, update, and use local CLI App adapters and MCP presets |
|
||||
| Skills | Inspect available built-in and workspace skills before relying on them |
|
||||
| Automations | Review, search, run, pause, edit, and delete scheduled and local-trigger agent turns |
|
||||
@@ -113,6 +126,20 @@ For image generation, configure an image provider first and then use the WebUI
|
||||
image mode from the composer. See [`image-generation.md`](./image-generation.md)
|
||||
for provider setup and output behavior.
|
||||
|
||||
## 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:
|
||||
|
||||
- install missing optional channel support when the WebUI is running locally;
|
||||
- collect platform credentials while preserving previously saved values;
|
||||
- handle supported QR-based login flows;
|
||||
- validate the connection and show actionable setup errors;
|
||||
- tell you when the gateway needs to restart.
|
||||
|
||||
The platform itself may still require you to create a bot, enable event permissions, copy a token, or configure a webhook. Use [`chat-apps.md`](./chat-apps.md) for those platform-side prerequisites and for manual JSON/reference options.
|
||||
|
||||
Test a new channel with a private DM. When a supported channel sends a pairing code, the WebUI surfaces the pending request so you can approve the sender. Keep access narrow; do not use a wildcard allowlist unless public access is intentional.
|
||||
|
||||
## Apps
|
||||
|
||||
Open Apps from the sidebar to manage tools that nanobot can attach to a chat
|
||||
@@ -194,9 +221,9 @@ with the content that should be delivered.
|
||||
## Settings
|
||||
|
||||
Settings is the control surface for the browser session and gateway-backed
|
||||
runtime configuration. Use it to review or adjust model presets, provider
|
||||
visibility, image generation, voice transcription, web tools, Apps, Automations,
|
||||
Skills, runtime identity, and advanced safety controls.
|
||||
runtime configuration. Use it to review or adjust model presets, providers,
|
||||
image generation, voice transcription, web tools, chat channels, Apps,
|
||||
Automations, Skills, runtime identity, and advanced safety controls.
|
||||
|
||||
Some settings take effect immediately. Runtime settings that affect the gateway
|
||||
or agent process may require a restart; the WebUI shows that requirement next to
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 287 KiB After Width: | Height: | Size: 657 KiB |
Reference in New Issue
Block a user