History

Bifang 13fc139437 Initial cmomit: replace with new code		2026-06-24 15:05:19 +08:00
..
public/brand	Initial cmomit: replace with new code	2026-06-24 15:05:19 +08:00
src	Initial cmomit: replace with new code	2026-06-24 15:05:19 +08:00
.gitignore	Initial cmomit: replace with new code	2026-06-24 15:05:19 +08:00
README.md	Initial cmomit: replace with new code	2026-06-24 15:05:19 +08:00
bun.lock	Initial cmomit: replace with new code	2026-06-24 15:05:19 +08:00
components.json	Initial cmomit: replace with new code	2026-06-24 15:05:19 +08:00
eslint.config.js	Initial cmomit: replace with new code	2026-06-24 15:05:19 +08:00
index.html	Initial cmomit: replace with new code	2026-06-24 15:05:19 +08:00
package-lock.json	Initial cmomit: replace with new code	2026-06-24 15:05:19 +08:00
package.json	Initial cmomit: replace with new code	2026-06-24 15:05:19 +08:00
postcss.config.js	Initial cmomit: replace with new code	2026-06-24 15:05:19 +08:00
tailwind.config.js	Initial cmomit: replace with new code	2026-06-24 15:05:19 +08:00
tsconfig.build.json	Initial cmomit: replace with new code	2026-06-24 15:05:19 +08:00
tsconfig.json	Initial cmomit: replace with new code	2026-06-24 15:05:19 +08:00
vite.config.ts	Initial cmomit: replace with new code	2026-06-24 15:05:19 +08:00

README.md

nanobot WebUI Source

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. 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 and docs/README.md.

Pick a Path

Goal	Start with	Opens at
Use the bundled browser UI	`docs/webui.md`	`http://127.0.0.1:8765`
Use the WebUI from another device	`docs/webui.md#lan-access`	`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

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

webui/                 source tree (this directory)
../webui/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

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 ../webui/dist in this project

The gateway picks up the new bundle on the next restart.

Test

cd webui
bun run test

Acknowledgements

agent-chat-ui for UI and interaction inspiration across the chat surface.