Your lightweight open-source personal agent.
Python agent-frameworkai-agentai-agentschatbotchatopsdiscord-botllm-agentsllmslocal-llmmcpmodel-context-protocolmulti-agentopenai-compatibleopenclawpersonal-ai-assistantpythonself-hostedtelegram-bot-ai-assistantwebuiworkflow-automation
docs: add webui user guide
chengyongruc6ea5aecff63
diff --git a/README.md b/README.mdindex 3f9802250..9776318d7 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).<p align="center"><img src="images/nanobot_webui.png" alt="nanobot webui preview" width="900">@@ -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.## ποΈ Architecturediff --git a/docs/README.md b/docs/README.mdindex 53281a459..9b4ef7b96 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.mdindex 665fad1c4..97c7afe5d 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.## Toolsdiff --git a/docs/deployment.md b/docs/deployment.mdindex e076a8f1b..0c398880d 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 Composediff --git a/docs/quick-start.md b/docs/quick-start.mdindex 2e1aa15db..9f7daea3c 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.mdindex f604e9f09..c2b009d29 100644--- a/docs/start-without-technical-background.md+++ b/docs/start-without-technical-background.md@@ -393,7 +393,7 @@ nanobot gatewayTo 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 Appdiff --git a/docs/troubleshooting.md b/docs/troubleshooting.mdindex 3c19fa025..8a736a0ee 100644--- a/docs/troubleshooting.md+++ b/docs/troubleshooting.md@@ -205,7 +205,7 @@ http://127.0.0.1:8765If 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 Problemsdiff --git a/docs/webui.md b/docs/webui.mdnew file mode 100644index 000000000..82eb12dda--- /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://<your-ip>: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.mdindex 2730a2721..998ea02b2 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://<your-ip>: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://<your-ip>: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://<your-ip>: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 runtimeYou usually do not need to run this by hand: `python -m build` invokes the WebUI build automatically when packaging the wheel.