Nanobot WebUI

repository·main·Indexed 41 days ago

https://github.com/good0007/nanobot-webui

A self-hosted management panel for the nanobot multi-channel AI agent framework. Version 0.3.0 provides a UI for configuring providers, managing IM channels (such as WeChat and Telegram), controlling agent skills, and interacting with agents via real-time WebSocket chat. Built with a FastAPI backend and a React 18 frontend, it includes a CLI for service management and supports deployment via Docker Compose.

Tokens: 13.9K
Snippets: 47
Records: 59
Agent score: 98%

What's inside Nanobot WebUI

Understand the Nanobot WebUI architecture
main
The Nanobot WebUI is structured as a Python package (webui) that integrates a FastAPI backend with a React frontend.
Backend Structure (webui/)
- api/: Contains the FastAPI implementation, including routes for authentication, channels, configuration, cron jobs, MCP, OpenAI proxy, providers, sessions, skills, and users.
- channels/: Contains channel plugins (e.g., weixin.py for WeChat).
- patches/: Contains minimal, non-invasive runtime monkey-patches applied at startup to improve quality-of-life (e.g., mcp_dynamic.py, provider.py).
- utils/: Contains the unified configuration store located at ~/.nanobot/webui_config.json.
Frontend Structure (web/)
- A React 18 + TypeScript application using Vite.
- src/pages/: Contains route-specific components like Chat.tsx, Dashboard.tsx, MCPServers.tsx, and Settings.tsx.
- src/hooks/: Uses TanStack Query for data fetching.
- src/stores/: Uses Zustand for client-side state (auth, chat).
Design Principle
The backend is designed to be non-invasive. It imports nanobot libraries without patching their source code. Any necessary runtime patches in webui/patches/ are applied once at startup before nanobot internals are initialized.
https://github.com/good0007/nanobot-webui/blob/main/README.md
Understand the Nanobot WebUI Project Structure
main
The project is divided into a Python backend package (webui) and a React frontend (web).
Backend (webui/)
- Entrypoint: Use python -m webui to start the application.
- API: Built with FastAPI. Routes are organized by domain (e.g., /api/auth, /api/channels, /api/mcp, /api/skills).
- Plugins: Channel plugins (like WeChat) are registered via entry-points in webui/channels/.
- Patches: The backend uses non-intrusive monkey-patches in webui/patches/ to optimize the runtime experience (e.g., enabling MCP servers or session persistence) without modifying the core nanobot library source code.
- Configuration: WebUI-specific settings are stored in ~/.nanobot/webui_config.json.
Frontend (web/)
- Stack: React 18, TypeScript, Vite, Tailwind CSS, and shadcn/ui.
- State Management: Zustand for client-side state (auth, chat) and TanStack Query for server state.
- Real-time: Uses WebSockets via the /ws/chat endpoint.
- Build: Static assets are compiled via bun run build and located in webui/web/dist/.
https://github.com/good0007/nanobot-webui/blob/main/README_zh.md
Set up Nanobot WebUI for Development
main
To develop on the project, you need Python ≥ 3.11, Bun ≥ 1.0, and uv.
1. Backend Setup: Clone the repo, create a venv with uv, and install in editable mode.
2. Backend Execution: Run uv run nanobot-webui start to start the API and static server.
3. Frontend Setup: In a separate terminal, navigate to the web directory, install dependencies with bun install, and run bun dev to start the dev server at http://localhost:5173 (which proxies /api to the backend).
Production Build: To build frontend assets for production, run bun run build inside the web directory.
```
# Backend
git clone https://github.com/Good0007/nanobot-webui.git
cd nanobot-webui
uv venv
uv pip install -e .
uv run nanobot-webui start

# Frontend (separate terminal)
cd web
bun install
bun dev
```
https://github.com/good0007/nanobot-webui/blob/main/README.md

Run Nanobot WebUI via Docker Compose

main

The recommended way to run in Docker is using Docker Compose. This ensures data persistence by mapping the host's ~/.nanobot directory to the container's /root/.nanobot directory.

Prerequisites: Docker ≥ 24 with the Compose plugin.

services:
  webui:
    image: kangkang223/nanobot-webui:latest
    container_name: nanobot-webui
    volumes:
      - ~/.nanobot:/root/.nanobot   # config & data persistence
    ports:
      - "18780:18780"    # WebUI
    restart: unless-stopped

Commands:

docker compose up -d    # Start in background
docker compose logs -f # View logs
docker compose down     # Stop

Install Nanobot WebUI using uv for isolated environments
main
Use uv tool install to install nanobot-webui into a managed, isolated virtual environment. This prevents conflicts with your system Python or existing nanobot commands. The executable will be linked to ~/.local/bin/.
Upgrade command:
```
uv tool upgrade nanobot-webui
```
```
uv tool install nanobot-webui
```
https://github.com/good0007/nanobot-webui/blob/main/README_zh.md
Deploy Nanobot WebUI with Docker Compose
main
For long-running deployments, use Docker Compose. Ensure Docker ≥ 24 is installed.
Configuration details:
- Data Persistence: Map ~/.nanobot on the host to /root/.nanobot in the container to persist configurations, sessions, and workspace files.
- Default Port: The WebUI listens on 18780.
- Default Credentials: admin / nanobot (change immediately after first login).
Example docker-compose.yml:
```
services:
  webui:
    image: kangkang223/nanobot-webui:latest
    container_name: nanobot-webui
    volumes:
      - ~/.nanobot:/root/.nanobot
    ports:
      - "18780:18780"
    restart: unless-stopped
```
https://github.com/good0007/nanobot-webui/blob/main/README_zh.md
Run Nanobot WebUI with CLI commands
main
Use the nanobot-webui (or the webui alias) command to manage the service.
Default Credentials:
- URL: http://localhost:18780
- Username: admin
- Password: nanobot (change this immediately after first login)
Common Commands:
- nanobot-webui start: Run in foreground (Ctrl-C to stop).
- nanobot-webui start -d: Run as a background daemon (recommended for production).
- nanobot-webui start --port <port>: Specify a custom port.
- nanobot-webui stop: Stop the background service.
- nanobot-webui status: Check service status, PID, and logs.
- nanobot-webui restart: Restart the service.
- nanobot-webui logs: View logs (use -f to follow).
```
nanobot-webui start
nanobot-webui start -d
nanobot-webui start --port 9090
```
https://github.com/good0007/nanobot-webui/blob/main/README_vi.md
Start the Nanobot WebUI backend using uv
main
To start the backend from the project root so that it serves the built web assets, navigate to the parent directory and use the uv run command. This command starts the backend which serves the contents of webui/web/dist/ as static files.
Legacy Command: If you are using an older version, you can use uv run nanobot webui start instead.
```
cd ..
uv run nanobot-webui start
```
https://github.com/good0007/nanobot-webui/blob/main/README.md
Install Nanobot WebUI via pip
main
Install the self-hosted management panel for nanobot using pip. The wheel package includes a pre-compiled React frontend, so Node.js is not required for standard installation.
Upgrade instructions: To avoid conflicts when upgrading from an older version, uninstall the existing package first:
```
pip uninstall -y nanobot-webui
pip install nanobot-webui
```
```
pip install nanobot-webui
```
https://github.com/good0007/nanobot-webui/blob/main/README_zh.md
Run Nanobot WebUI with Docker Compose
main
The recommended way to run in Docker is using Docker Compose. Ensure you map the ~/.nanobot volume to persist configuration and data.
Setup: Create a docker-compose.yml file:
```
services:
  webui:
    image: kangkang223/nanobot-webui:latest
    container_name: nanobot-webui
    volumes:
      - ~/.nanobot:/root/.nanobot
    ports:
      - "18780:18780"
    restart: unless-stopped
```
Commands:
- docker compose up -d: Start in background.
- docker compose logs -f: Follow logs.
- docker compose down: Stop services.
https://github.com/good0007/nanobot-webui/blob/main/README_vi.md
Develop Nanobot WebUI
main
To develop the project, you need Python ≥ 3.11, Bun ≥ 1.0, and uv.
1. Backend Setup (Editable mode):
```
git clone https://github.com/Good0007/nanobot-webui.git
cd nanobot-webui
uv venv
uv pip install -e .
uv run nanobot-webui start
```
2. Frontend Setup (Dev server): In a separate terminal:
```
cd web
bun install
bun dev
```
The frontend dev server runs at http://localhost:5173 and proxies /api requests to the backend at :18780.
3. Production Build:
```
# Build frontend
cd web
bun run build

# Start backend to serve static assets
cd ..
uv run nanobot-webui start
```
```
# Backend setup
uv venv
uv pip install -e .

# Frontend setup
cd web
bun install
bun dev
```
https://github.com/good0007/nanobot-webui/blob/main/README_vi.md
Install Nanobot WebUI via uv
main
For isolated environments, use uv tool install. This installs the nanobot-webui and webui commands into a managed virtual environment and symlinks them to your local bin, keeping them separate from your system Python.
Upgrade Note:
```
uv tool upgrade nanobot-webui
```
```
uv tool install nanobot-webui
```
https://github.com/good0007/nanobot-webui/blob/main/README.md

Nanobot WebUI

What's inside Nanobot WebUI

Understand the Nanobot WebUI architecture

Backend Structure (`webui/`)

Frontend Structure (`web/`)

Design Principle

Understand the Nanobot WebUI Project Structure

Backend (`webui/`)

Frontend (`web/`)

Set up Nanobot WebUI for Development

Run Nanobot WebUI via Docker Compose

Install Nanobot WebUI using uv for isolated environments

Deploy Nanobot WebUI with Docker Compose

Run Nanobot WebUI with CLI commands

Start the Nanobot WebUI backend using uv

Install Nanobot WebUI via pip

Run Nanobot WebUI with Docker Compose

Develop Nanobot WebUI

Install Nanobot WebUI via uv

Nanobot WebUI

What's inside Nanobot WebUI

Backend Structure (webui/)

Frontend Structure (web/)

Design Principle

Backend (webui/)

Frontend (web/)

Backend Structure (`webui/`)

Frontend Structure (`web/`)

Backend (`webui/`)

Frontend (`web/`)