4a58b83acc
* docs: make onboarding friendlier for beginners * docs: build clearer documentation paths Maintainer edit: turn the onboarding follow-up into a layered docs structure for first-time setup, provider selection, troubleshooting, CLI reference, and source-level architecture. This keeps quick start focused while giving advanced users precise reference paths. * docs: render architecture flow with mermaid Maintainer edit: replace the ASCII architecture sketch with a GitHub-rendered Mermaid flowchart so the core runtime path is easier to scan in the PR and README docs. * docs: recommend model presets for model config Maintainer edit: make named modelPresets the primary model configuration path and expand fallback preset examples so string fallbacks are clearly preset names, not raw model IDs. * docs: document api base urls and langfuse setup Maintainer edit: explain when users need apiBase/base URL in quick start and provider docs, and add Langfuse tracing setup with troubleshooting links. * docs: use python module pip consistently Maintainer edit: keep install commands tied to the active Python interpreter by using python -m pip in the Azure optional dependency notes too. * docs: add non-technical getting started path Maintainer edit: add a wizard-first guide for users without terminal or JSON background, including a text TUI menu example and links from the main docs entrypoints. * docs: avoid hard-wrapped prose in user docs Maintainer edit: unwrap ordinary prose across user-facing documentation while preserving markdown structure, code blocks, tables, lists, and prompt/template files. * docs: keep desktop list continuations nested Maintainer edit: preserve list nesting after unwrapping prose in the desktop WebUI sync guide. * docs: add one-command installer Maintainer edit: add auditable macOS/Linux and Windows install scripts that install nanobot-ai and start the onboarding wizard, then document the commands in the main onboarding entrypoints. * docs: add installer dry run mode Maintainer edit: add --dry-run to the one-command installer scripts so users can preview Python detection, install source, pip command, and wizard behavior without changing their environment. * docs: clean installer error output Maintainer edit: make PowerShell installer failures print a concise Error: message instead of Write-Error call-site details. * docs: add provider setup cookbook Maintainer edit: add pasteable provider recipes for common hosted, local, fallback, runtime switching, and Langfuse setups, then link the cookbook from onboarding and troubleshooting entrypoints. * docs: address review feedback * docs: clarify reader paths * docs: explain terminal basics for beginners * docs: clarify wizard navigation * docs: avoid duplicate onboarding steps * docs: add setup status check * docs: explain status output * docs: remove provider recommendation wording * docs: explain status diagnostics * docs: reduce hard-wrapped guidance * docs: migrate config examples to presets * docs: clarify python command fallbacks * docs: improve installer failure recovery * docs: expand install troubleshooting * docs: cover installer download failures * docs: put stable install paths first * docs: add bundled webui quick path * docs: clarify provider-neutral setup * docs: clarify gateway setup for chat surfaces * docs: improve docs navigation paths * docs: add configuration quick jump * docs: clarify provider secret variables * chore: request PR review acknowledgement Empty commit: please read the PR review comments and reply on the PR to confirm that you have received them. This commit intentionally changes no files; it exists only to notify the remote Codex run so it can end its active goal. * docs: add README start here guide * docs: avoid provider recommendation wording * docs: guide next steps after first reply * docs: explain merging JSON snippets * docs: add CLI command chooser * docs: add configuration task map * docs: add deployment readiness guide * docs: simplify WebUI entry paths * docs: add provider recipe chooser * docs: fix provider factual references Update OpenRouter and LongCat model examples, align Bedrock guidance, and make fallback snippets schema-valid. Also correct group policy wording and image-generation provider lists to match the current code. * fix: keep PowerShell installer from closing caller shell * docs: mention self-guided configuration
4.6 KiB
nanobot WebUI
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.
For the project overview, install guide, and general docs map, see the root README.md and docs/README.md.
Pick a Path
| Goal | Start with | Opens at |
|---|---|---|
| Use the bundled browser UI | Just want to use the WebUI? | http://127.0.0.1:8765 |
| Use the WebUI from another device | Access from another device (LAN) | http://<your-ip>:8765 |
| Change WebUI source code | Develop the WebUI (Vite HMR) | http://127.0.0.1:5173 |
| Debug setup failures | 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:
nanobot agent -m "Hello!"
If the shell cannot find nanobot, use the module form from the same Python environment:
python -m nanobot agent -m "Hello!"
Then merge this WebSocket snippet into your existing ~/.nanobot/config.json instead of replacing the whole file:
{ "channels": { "websocket": { "enabled": true } } }
If you are new to JSON snippets, see docs/start-without-technical-background.md#how-to-merge-json-snippets.
Start the gateway:
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. The gateway's 18790 port is only the health endpoint, not the browser UI. For setup failures, use docs/troubleshooting.md.
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.
Layout
webui/ source tree (this directory)
nanobot/web/dist/ build output served by the gateway
Develop the WebUI (Vite HMR)
1. Install nanobot from source
From the repository root:
python -m pip install -e .
Editable installs intentionally skip the WebUI bundle step — Vite HMR is faster than rebuilding
dist/on every change.
2. Enable the WebSocket channel
In ~/.nanobot/config.json, merge:
{ "channels": { "websocket": { "enabled": true } } }
3. Start the gateway
In one terminal:
nanobot gateway
4. Start the WebUI dev server
In another terminal:
cd webui
bun install # npm install also works
bun run dev
Then open http://127.0.0.1:5173.
By default the dev server proxies /api, /webui, /auth, and WebSocket traffic to http://127.0.0.1:8765.
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:
{
"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 runtime
You usually do not need to run this by hand: python -m build invokes the WebUI build automatically when packaging the wheel.
If you want to preview the production bundle locally without rebuilding the wheel:
cd webui
bun run build # writes to ../nanobot/web/dist
The gateway picks up the new bundle on the next restart.
Test
cd webui
bun run test
Acknowledgements
agent-chat-uifor UI and interaction inspiration across the chat surface.