2026-07-08 15:23:34 +08:00
|
|
|
# How to Use an AI Agent WebUI with nanobot
|
|
|
|
|
|
|
|
|
|
nanobot includes a browser WebUI for persistent chat sessions, visible agent
|
|
|
|
|
activity, workspace controls, Apps, MCP presets, Skills, settings, and
|
|
|
|
|
Automations.
|
|
|
|
|
|
|
|
|
|
## What you will build
|
|
|
|
|
|
|
|
|
|
- a local browser workbench
|
|
|
|
|
- one persistent chat session
|
2026-07-09 00:04:30 +08:00
|
|
|
- a visible timeline of agent messages, tool calls, and file edit diffs
|
2026-07-08 15:23:34 +08:00
|
|
|
- a gateway-backed WebSocket connection
|
|
|
|
|
|
|
|
|
|
## When to use this
|
|
|
|
|
|
|
|
|
|
Use the WebUI when you want a local AI agent interface that is easier to operate
|
|
|
|
|
than a terminal, especially for project work, file attachments, model switching,
|
|
|
|
|
workspace selection, Apps, Skills, and scheduled automations.
|
|
|
|
|
|
|
|
|
|
## Install
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
python -m pip install nanobot-ai
|
|
|
|
|
nanobot onboard --wizard
|
|
|
|
|
nanobot agent -m "Hello!"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The published wheel already includes the WebUI bundle. You only need the
|
|
|
|
|
`webui/` source directory when changing the frontend.
|
|
|
|
|
|
|
|
|
|
## Minimal working example
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
nanobot webui
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The launcher checks setup, enables the local WebSocket channel after
|
|
|
|
|
confirmation, starts the gateway, and opens the browser.
|
|
|
|
|
|
2026-07-09 00:04:30 +08:00
|
|
|
When nanobot edits a file, the WebUI activity timeline can show the changed
|
|
|
|
|
line counts, a unified diff, and an **Open file** action for a read-only
|
|
|
|
|
preview. File previews use the chat's current workspace access mode: restricted
|
|
|
|
|
access stays inside the selected workspace, while Full Access can preview files
|
|
|
|
|
outside the workspace when the gateway allows it.
|
|
|
|
|
|
2026-07-08 15:23:34 +08:00
|
|
|
## Production notes
|
|
|
|
|
|
|
|
|
|
- Use `nanobot webui --background` when you do not want to keep a terminal open.
|
|
|
|
|
- Use `nanobot gateway status`, `logs`, `restart`, and `stop` to manage a
|
|
|
|
|
background gateway.
|
|
|
|
|
- If you expose the WebUI beyond localhost, set a token issue secret and review
|
|
|
|
|
workspace/tool access.
|
|
|
|
|
|
|
|
|
|
## Security notes
|
|
|
|
|
|
|
|
|
|
- The first-run WebUI path binds to `127.0.0.1` by default.
|
|
|
|
|
- Do not expose the WebUI on a LAN or public host without an intentional access
|
|
|
|
|
model.
|
|
|
|
|
- Keep file and shell tools scoped to the workspace before inviting other users.
|
|
|
|
|
|
|
|
|
|
## Troubleshooting
|
|
|
|
|
|
|
|
|
|
- The WebUI is served by the WebSocket channel on port `8765` by default.
|
|
|
|
|
- The gateway health endpoint is separate from the browser UI.
|
|
|
|
|
- If the page opens but messages fail, check provider setup with
|
|
|
|
|
`nanobot agent -m "Hello!"`.
|
|
|
|
|
|
|
|
|
|
## Related nanobot docs
|
|
|
|
|
|
|
|
|
|
- [Nanobot WebUI](../webui.md)
|
|
|
|
|
- [Quick Start](../quick-start.md)
|
|
|
|
|
- [WebSocket protocol](../websocket.md)
|
|
|
|
|
- [Configuration](../configuration.md)
|
