diff --git a/README.md b/README.md index 3f980225..9776318d 100644 --- a/README.md +++ b/README.md @@ -359,7 +359,7 @@ Need help with `PATH`, API keys, provider/model matching, or JSON errors? See th ## 🌐 WebUI -The WebUI ships **inside the published wheel** — no extra build step. Just enable the WebSocket channel and open it in your browser. +The WebUI ships **inside the published wheel** — no extra build step. It is the browser workbench for chat sessions, workspace controls, Apps, Skills, Automations, and settings. For the full user guide, see [`docs/webui.md`](./docs/webui.md).

nanobot webui preview @@ -381,12 +381,12 @@ nanobot gateway **3. Open the WebUI** -Visit [`http://127.0.0.1:8765`](http://127.0.0.1:8765) in your browser. To open it from another device on your LAN, see [WebUI docs → LAN access](./webui/README.md#access-from-another-device-lan). +Visit [`http://127.0.0.1:8765`](http://127.0.0.1:8765) in your browser. 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. > [!TIP] -> Working on the WebUI itself? Check out [`webui/README.md`](./webui/README.md) for the Vite dev server (HMR) workflow. +> Working on the WebUI itself? Check out [`webui/README.md`](./webui/README.md) for the source-tree, Vite dev server, build, and test workflow. ## 🏗️ Architecture diff --git a/docs/README.md b/docs/README.md index 53281a45..9b4ef7b9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,7 +16,7 @@ If you find a docs mistake, outdated command, or confusing step, please open an |---|---|---| | 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/README.md`](../webui/README.md), and [`deployment.md`](./deployment.md) | +| 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) | ## Start Here @@ -38,7 +38,7 @@ If a local `nanobot agent` session can already answer normally, you can also ask | Next goal | Read | First check | |---|---|---| -| Use nanobot in a browser | [`../webui/README.md`](../webui/README.md) | Enable WebSocket, run `nanobot gateway`, open `http://127.0.0.1:8765` | +| Use nanobot in a browser | [`webui.md`](./webui.md) | Enable WebSocket, run `nanobot gateway`, open `http://127.0.0.1:8765` | | 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` | | Understand before operating long-term | [`concepts.md`](./concepts.md) | Know what config, workspace, gateway, sessions, memory, and tools mean | @@ -48,7 +48,7 @@ If a local `nanobot agent` session can already answer normally, you can also ask | Goal | Read | Outcome | |---|---|---| -| Open the bundled browser UI | [`../webui/README.md`](../webui/README.md) | WebUI on port `8765`, or Vite HMR when developing the frontend | +| Open the bundled browser UI | [`webui.md`](./webui.md) | WebUI on port `8765`, chat workspace, Apps, Skills, Automations, and settings | | Connect Telegram, Discord, WeChat, Slack, and other apps | [`chat-apps.md`](./chat-apps.md) | A gateway-backed chat channel with access control | | Use slash commands and periodic tasks | [`chat-commands.md`](./chat-commands.md) | Pairing, model presets, heartbeat tasks, and chat-side controls | | Generate images | [`image-generation.md`](./image-generation.md) | Image provider config, WebUI image mode, and artifact behavior | diff --git a/docs/architecture.md b/docs/architecture.md index 665fad1c..97c7afe5 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -108,7 +108,8 @@ WebUI source lives in `webui/`. The production build is written to `nanobot/web/ Useful docs: -- [`../webui/README.md`](../webui/README.md) for WebUI use and development; +- [`webui.md`](./webui.md) for the WebUI user guide; +- [`../webui/README.md`](../webui/README.md) for frontend source development; - [`websocket.md`](./websocket.md) for protocol details. ## Tools diff --git a/docs/deployment.md b/docs/deployment.md index e076a8f1..0c398880 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -54,7 +54,7 @@ Restart the deployed process after editing `config.json`. Long-running processes > } > ``` > -> When the WebSocket `host` is `0.0.0.0`, the channel refuses to start unless `token` or `tokenIssueSecret` is also configured — see [`webui/README.md`](../webui/README.md) for details. +> When the WebSocket `host` is `0.0.0.0`, the channel refuses to start unless `token` or `tokenIssueSecret` is also configured. See [`webui.md#lan-access`](./webui.md#lan-access) for details. ### Docker Compose diff --git a/docs/quick-start.md b/docs/quick-start.md index 2e1aa15d..9f7daea3 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -271,7 +271,7 @@ Exit interactive mode with `exit`, `quit`, `/exit`, `/quit`, `:q`, or `Ctrl+D`. | 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/README.md`](../webui/README.md) | +| Open the bundled browser UI | [`webui.md`](./webui.md) | | Connect Telegram, Discord, WeChat, Slack, Email, 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) | diff --git a/docs/start-without-technical-background.md b/docs/start-without-technical-background.md index f604e9f0..c2b009d2 100644 --- a/docs/start-without-technical-background.md +++ b/docs/start-without-technical-background.md @@ -393,7 +393,7 @@ nanobot gateway To stop the WebUI later, return to the gateway terminal and press `Ctrl+C`. -If `nanobot` is not found, run `python -m nanobot gateway`, `python3 -m nanobot gateway`, or `py -m nanobot gateway`, matching the Python command that worked earlier. More details are in [`../webui/README.md`](../webui/README.md). +If `nanobot` is not found, run `python -m nanobot gateway`, `python3 -m nanobot gateway`, or `py -m nanobot gateway`, matching the Python command that worked earlier. More details are in [`webui.md`](./webui.md). ### Connect a Chat App diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 3c19fa02..8a736a0e 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -205,7 +205,7 @@ http://127.0.0.1:8765 If accessing from another device, bind the WebSocket channel to `0.0.0.0` and set `token` or `tokenIssueSecret`. The WebSocket channel refuses public binds without a token or token issue secret. -See [`../webui/README.md`](../webui/README.md) for LAN and development setup. +See [`webui.md#lan-access`](./webui.md#lan-access) for LAN setup and [`../webui/README.md`](../webui/README.md) for frontend development. ## Chat App Problems diff --git a/docs/webui.md b/docs/webui.md new file mode 100644 index 00000000..82eb12dd --- /dev/null +++ b/docs/webui.md @@ -0,0 +1,168 @@ +# WebUI + +The WebUI is nanobot's browser workbench. Use it after a basic CLI reply already +works, when you want a persistent chat workspace, visible agent activity, +workspace controls, Apps, Skills, settings, and Automations in one place. + +The published `nanobot-ai` wheel already includes the WebUI bundle. You only need +the `webui/` source directory when you are changing the frontend itself. + +## Open the WebUI + +First confirm your provider and model can answer: + +```bash +nanobot agent -m "Hello!" +``` + +Then merge the WebSocket channel into your existing `~/.nanobot/config.json`: + +```json +{ "channels": { "websocket": { "enabled": true } } } +``` + +If you are new to JSON snippets, see +[`start-without-technical-background.md#how-to-merge-json-snippets`](./start-without-technical-background.md#how-to-merge-json-snippets). + +Start the gateway: + +```bash +nanobot gateway +``` + +Leave the gateway running and open +[`http://127.0.0.1:8765`](http://127.0.0.1:8765). 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. + +## What It Is For + +| Area | Use it for | +|---|---| +| Chat | Start, switch, search, fork, and delete browser sessions | +| Agent activity | See thinking, tool calls, file activity, command output, and generated artifacts in context | +| 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 | +| 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 agent turns | +| Settings | Adjust models, providers, image generation, voice, web tools, runtime, and safety options | + +## Chat Workspace + +The sidebar is the session switcher. A session keeps its own history, title, +workspace metadata, and linked automations. Use a new session when you want a +separate context; use fork when you want to continue from an existing point +without changing the original thread. + +The message timeline shows both user-visible replies and agent activity. Long +tool or reasoning sections can be expanded when you need the details. + +## Workspace and Access + +Use the workspace picker before starting project-specific work. This gives the +agent the right project context for file paths, shell commands, and session +metadata. + +The access control in the composer controls the local capability level for the +chat. It does not bypass your gateway, provider, shell sandbox, or operating +system configuration; it only selects among the capabilities that are already +available to this WebUI session. + +## Composer + +The composer supports plain messages, image attachments, voice input when +transcription is configured, slash commands, and `@` mentions for installed Apps +or MCP presets. The model badge shows the current model or preset and links back +to model settings when setup is incomplete. + +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. + +## Apps + +Open Apps from the sidebar or settings navigation to manage integrations that +nanobot can call from a chat. CLI Apps install local adapters that nanobot runs +on your machine; they do not modify the native apps themselves. MCP presets add +predefined MCP server configurations. + +After an App or MCP preset is available, mention it from the composer with `@` +to attach that capability to the next message. + +## Skills + +The Skills view shows the skill instructions available to the agent, including +built-in skills and workspace-provided skills. Check this view when you want to +know whether nanobot already has a focused workflow for a task before you ask it +to perform that task. + +## Automations + +Automations are scheduled agent turns. They should be created from the chat, +channel, or session where they are supposed to run so nanobot keeps the correct +target context. + +Use the Automations view to: + +- Filter by all, active, paused, needs-attention, or system jobs. +- Search by task name, message, linked chat, schedule, or status. +- Sort by next run, last run, updated time, or name. +- Run now, pause or resume, edit, or delete user-created automations. +- Inspect protected system automations without changing them. + +Search accepts plain text and field filters such as `name:backup`, +`chat:WeChat`, `schedule:09:30`, `cron:"0 23 * * *"`, and `status:paused`. + +An automation without a linked chat cannot be enabled or run from the WebUI, +because nanobot would not know where to deliver the scheduled turn. Recreate it +from the target chat or channel so the automation has complete context. + +## 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. + +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 +the relevant control. + +## LAN Access + +To open the WebUI from another device on the same network, bind the WebSocket +channel to all interfaces and set a token or token issue secret: + +```json +{ + "channels": { + "websocket": { + "enabled": true, + "host": "0.0.0.0", + "port": 8765, + "tokenIssueSecret": "your-secret-here" + } + } +} +``` + +The gateway refuses to start with `host` set to `"0.0.0.0"` unless `token` or +`tokenIssueSecret` is configured. After the gateway starts, open +`http://:8765` from the other device and enter the secret in the login +form. + +## Troubleshooting + +If the page does not open, check these in order: + +1. `nanobot agent -m "Hello!"` works in the same Python environment. +2. The WebSocket channel is enabled in `~/.nanobot/config.json`. +3. `nanobot gateway` is still running. +4. You are opening port `8765`, not the gateway health port. +5. LAN access uses `host: "0.0.0.0"` and a token or token issue secret. + +For detailed diagnostics, see +[`troubleshooting.md#webui-problems`](./troubleshooting.md#webui-problems). +For frontend development, see [`../webui/README.md`](../webui/README.md). diff --git a/webui/README.md b/webui/README.md index 2730a272..998ea02b 100644 --- a/webui/README.md +++ b/webui/README.md @@ -1,6 +1,10 @@ -# nanobot WebUI +# nanobot WebUI Source -The WebUI is the browser workbench served by `nanobot gateway`. If you installed `nanobot-ai` from PyPI, the WebUI bundle is already included; this `webui/` source tree is only needed when you are changing the frontend. +This directory contains the React/TypeScript source for the nanobot WebUI. If +you installed `nanobot-ai` from PyPI and only want to use the bundled browser UI, +read the user guide in [`docs/webui.md`](../docs/webui.md). You do not need +Node.js, Bun, Vite, or anything in this directory unless you are changing the +frontend. For the project overview, install guide, and general docs map, see the root [`README.md`](../README.md) and [`docs/README.md`](../docs/README.md). @@ -8,46 +12,14 @@ For the project overview, install guide, and general docs map, see the root [`RE | Goal | Start with | Opens at | |---|---|---| -| Use the bundled browser UI | [Just want to use the WebUI?](#just-want-to-use-the-webui) | `http://127.0.0.1:8765` | -| Use the WebUI from another device | [Access from another device (LAN)](#access-from-another-device-lan) | `http://:8765` | +| Use the bundled browser UI | [`docs/webui.md`](../docs/webui.md) | `http://127.0.0.1:8765` | +| Use the WebUI from another device | [`docs/webui.md#lan-access`](../docs/webui.md#lan-access) | `http://:8765` | | Change WebUI source code | [Develop the WebUI (Vite HMR)](#develop-the-webui-vite-hmr) | `http://127.0.0.1:5173` | | Debug setup failures | [`docs/troubleshooting.md#webui-problems`](../docs/troubleshooting.md#webui-problems) | Diagnosis order and common fixes | -## Just want to use the WebUI? - -If you installed nanobot via `python -m pip install nanobot-ai`, the WebUI is **already bundled** in the wheel. You do **not** need Node.js, Bun, Vite, or anything in this directory unless you are changing the WebUI source code. - -First prove the provider path: - -```bash -nanobot agent -m "Hello!" -``` - -If the shell cannot find `nanobot`, use the module form from the same Python environment: - -```bash -python -m nanobot agent -m "Hello!" -``` - -Then merge this WebSocket snippet into your existing `~/.nanobot/config.json` instead of replacing the whole file: - -```json -{ "channels": { "websocket": { "enabled": true } } } -``` - -If you are new to JSON snippets, see [`docs/start-without-technical-background.md#how-to-merge-json-snippets`](../docs/start-without-technical-background.md#how-to-merge-json-snippets). - -Start the gateway: - -```bash -nanobot gateway -``` - -Leave this terminal running while you use the WebUI. Closing it stops the browser UI and WebSocket connection. - -Open [`http://127.0.0.1:8765`](http://127.0.0.1:8765). The gateway's `18790` port is only the health endpoint, not the browser UI. For setup failures, use [`docs/troubleshooting.md`](../docs/troubleshooting.md#webui-problems). - -This `webui/` tree is for people **changing the WebUI source code**. It is built with Vite + React 18 + TypeScript + Tailwind 3 + shadcn/ui, talks to the gateway over the WebSocket multiplex protocol, and reads session metadata from the embedded REST surface on the same port. +The source app is built with Vite + React 18 + TypeScript + Tailwind 3 + +shadcn/ui. It talks to the gateway over the WebSocket multiplex protocol and +reads session metadata from the embedded REST surface on the same port. ## Layout @@ -104,27 +76,6 @@ If your gateway listens on a non-default port, point the dev server at it: NANOBOT_API_URL=http://127.0.0.1:9000 bun run dev ``` -### Access from another device (LAN) - -To use the WebUI from another device on the same network, set `host` to `"0.0.0.0"` and configure a `token` or `tokenIssueSecret` in `~/.nanobot/config.json`: - -```json -{ - "channels": { - "websocket": { - "enabled": true, - "host": "0.0.0.0", - "port": 8765, - "tokenIssueSecret": "your-secret-here" - } - } -} -``` - -The gateway will refuse to start if `host` is `"0.0.0.0"` and neither `token` nor `tokenIssueSecret` is set. - -Then open `http://:8765` on the other device. The WebUI will show an authentication form where you enter the secret. It is saved in your browser so you only need to enter it once. - ## Build for packaged runtime You usually do not need to run this by hand: `python -m build` invokes the WebUI build automatically when packaging the wheel.