### Install and Start Nanobot WebUI

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Installs the nanobot-webui using pip and starts the service on a specified port. This is the recommended deployment method for a single machine.

```bash
pip install nanobot-webui
nanobot-webui start --port 18780
# Open http://localhost:18780
```

--------------------------------

### Start Nanobot WebUI CLI Examples

Source: https://github.com/good0007/nanobot-webui/blob/main/README.md

Various ways to start the Nanobot WebUI service using the CLI, including foreground, background, custom ports, and specific modes.

```bash
nanobot-webui start                          # foreground (Ctrl-C to stop)
nanobot-webui start --port 9090              # custom port
nanobot-webui start -d                       # background daemon
nanobot-webui start -d --port 9090           # background + custom port
nanobot-webui start --workspace ~/myproject  # override workspace
nanobot-webui start --webui-only             # WebUI only; nanobot managed externally
nanobot-webui start -d --webui-only          # Background + WebUI-only mode
```

--------------------------------

### Loguru Logging Examples

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/architecture.md

Demonstrates how to use the loguru library for different log levels. Ensure loguru is installed and configured.

```python
from loguru import logger

logger.debug("Message: {}", content)
logger.info("User {} logged in", username)
logger.warning("High temperature: {}", temp)
logger.error("Failed to process: {}", error)
```

--------------------------------

### Start nanobot-webui backend for production

Source: https://github.com/good0007/nanobot-webui/blob/main/README.md

Starts the nanobot-webui backend from the project root to serve the built production assets. Legacy compatibility command: uv run nanobot webui start.

```bash
cd ..
uv run nanobot-webui start    # backend serves webui/web/dist/ as static files
```

--------------------------------

### Start nanobot-webui backend

Source: https://github.com/good0007/nanobot-webui/blob/main/README.md

Starts the nanobot-webui backend, serving the API and static files on port 18780. Legacy compatibility command: uv run nanobot webui start.

```bash
uv run nanobot-webui start          # API + static on :18780
```

--------------------------------

### Clone and install nanobot-webui backend

Source: https://github.com/good0007/nanobot-webui/blob/main/README.md

Installs the nanobot-webui backend in editable mode. Requires Python >= 3.11, Bun >= 1.0, and uv.

```bash
git clone https://github.com/Good0007/nanobot-webui.git
cd nanobot-webui
uv venv               # create a virtual env - don't mess with central python install
uv pip install -e .
```

--------------------------------

### Install Nanobot WebUI with uv

Source: https://github.com/good0007/nanobot-webui/blob/main/README_zh.md

Install nanobot-webui using the 'uv tool install' command for an isolated environment. This installs the tool in uv's managed environment and links executables to ~/.local/bin.

```bash
uv tool install nanobot-webui
```

--------------------------------

### Install nanobot-webui

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Install the nanobot WebUI package using pip or uv. The uv installation is recommended for an isolated environment.

```bash
pip install nanobot-webui
```

```bash
uv tool install nanobot-webui  # recommended, isolated environment
```

--------------------------------

### Start Nanobot WebUI Standalone

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/architecture.md

Use this command to start the nanobot core and WebUI in a single process. This is recommended for most users due to its simplicity.

```bash
nanobot-webui start --port 18780
# Starts:
# - Agent loop
# - Channel listeners (WeChat, Telegram, etc.)
# - FastAPI server on :18780
```

--------------------------------

### Start Nanobot WebUI

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/QUICK-REFERENCE.md

Basic command to start the Nanobot WebUI on a specified port. Use the -d flag to run in the background.

```bash
# Start WebUI
nanobot-webui start --port 18780
```

```bash
# Start in background
nanobot-webui start -d --port 18780
```

--------------------------------

### Start Nanobot WebUI Server

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/configuration.md

Command to start the Nanobot WebUI server with various options. Use the --daemon flag to run in the background.

```bash
nanobot-webui start [OPTIONS]
```

--------------------------------

### Install Nanobot WebUI via pip

Source: https://github.com/good0007/nanobot-webui/blob/main/README_zh.md

Install the nanobot-webui package using pip. This is the recommended installation method.

```bash
pip install nanobot-webui
```

--------------------------------

### Start Nanobot WebUI

Source: https://github.com/good0007/nanobot-webui/blob/main/README.md

Starts the Nanobot WebUI. The command combines the WebUI and gateway. You can specify a custom port or run it as a background daemon.

```bash
# Foreground (WebUI + gateway combined)
nanobot-webui start

# Custom port
nanobot-webui start --port 9090

# Background daemon (recommended for long-running deployments)
nanobot-webui start -d

# Optional short alias
webui start
```

--------------------------------

### Start nanobot-webui frontend dev server

Source: https://github.com/good0007/nanobot-webui/blob/main/README.md

Starts the frontend development server on http://localhost:5173. This server proxies API requests to the backend. Requires Bun >= 1.0.

```bash
cd web
bun install
bun dev                              # http://localhost:5173  (proxies /api → :18780)
```

--------------------------------

### Start New Session (JavaScript)

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/websocket-protocol.md

Example of sending a new_session message to the server to clear the chat history and begin a fresh conversation.

```javascript
ws.send(JSON.stringify({
  type: "new_session"
}));
```

--------------------------------

### Start Nanobot WebUI in WebUI-Only Mode

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/architecture.md

Run the WebUI as a separate process without integrated channels. This is useful for managing channels independently and for high-availability setups.

```bash
# Terminal 1: Run nanobot core (managed by systemd)
systemctl start nanobot

# Terminal 2: Run WebUI without channels
nanobot-webui start --webui-only
# Starts only FastAPI + agent WebSocket
# IM channels run in separate nanobot process
```

--------------------------------

### Docker Compose Commands

Source: https://github.com/good0007/nanobot-webui/blob/main/README_zh.md

Commands to manage the Nanobot WebUI Docker Compose setup, including starting, viewing logs, and stopping the services.

```bash
# Pull the latest image and start in the background
docker compose up -d

# View logs
docker compose logs -f

# Stop
docker compose down
```

--------------------------------

### Makefile Commands for Docker

Source: https://github.com/good0007/nanobot-webui/blob/main/README_zh.md

Convenient Makefile targets for managing the Nanobot WebUI Docker setup, including starting, stopping, logging, restarting, building, and releasing Docker images.

```bash
make up             # docker compose up -d
make down           # docker compose down
make logs           # track compose logs
make restart        # docker compose restart
make build          # build local single-architecture image
make release        # buildx push :<pyproject default version> and :latest
make release VERSION=0.2.7.post4  # explicitly specify release version
```

--------------------------------

### Start Nanobot WebUI

Source: https://github.com/good0007/nanobot-webui/blob/main/README_zh.md

Start the Nanobot WebUI. It can be run in the foreground, with a specified port, or in the background for long-term deployment. The default access is http://localhost:18780 with credentials admin/nanobot.

```bash
# Front-end start (WebUI + nanobot gateway integrated)
nanobot-webui start

# Specify port
nanobot-webui start --port 9090

# Background running (recommended for long-term deployment)
nanobot-webui start -d

# Optional short alias
webui start
```

--------------------------------

### Start Nanobot WebUI with Docker Compose

Source: https://github.com/good0007/nanobot-webui/blob/main/README.md

Commands to pull the latest Nanobot WebUI Docker image and start the service in the background using Docker Compose. Also includes a command to view logs.

```bash
# Pull the latest image and start in background
docker compose up -d

# View logs
docker compose logs -f
```

--------------------------------

### Start nanobot-webui CLI

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Launch the nanobot WebUI using its command-line interface. Several aliases are available for convenience.

```bash
nanobot-webui start        # Standalone WebUI CLI
```

```bash
webui start                # Short alias
```

```bash
nanobot webui start        # Subcommand under nanobot CLI
```

--------------------------------

### Main Application Entry Point

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

The main asynchronous function to start the nanobot web UI. It applies patches, starts the web server, and configures logging. Ensure asyncio is used to run this function.

```python
import asyncio
from webui.__main__ import main, _apply_patches

async def run():
    _apply_patches()
    await main(web_port=18780, web_host="0.0.0.0", log_level="DEBUG")

asyncio.run(run())
```

--------------------------------

### webui.__main__.main

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Main application entry point. Starts nanobot core services, FastAPI/Uvicorn server, agent event loop, and IM channel listeners.

```APIDOC
## async main(web_port: int = 18780, web_host: str = "0.0.0.0", workspace: str | None = None, log_level: str = "DEBUG", webui_only: bool = False) -> None

### Description
Main application entry point. Starts nanobot core services, FastAPI/Uvicorn server, agent event loop, and IM channel listeners (unless `webui_only=True`).

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import asyncio
from webui.__main__ import main, _apply_patches

async def run():
    _apply_patches()
    await main(web_port=18780, web_host="0.0.0.0", log_level="DEBUG")

asyncio.run(run())
```

### Response
#### Success Response (None)
None

#### Response Example
None

### Parameters Table
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| web_port | integer | 18780 | HTTP listen port |
| web_host | string | 0.0.0.0 | Bind address |
| workspace | string|None | None | Override workspace path |
| log_level | string | DEBUG | Log level |
| webui_only | bool | False | Skip IM channel startup |
```

--------------------------------

### Start Nanobot WebUI

Source: https://github.com/good0007/nanobot-webui/blob/main/README.md

Starts the Nanobot WebUI service. It can be run in the foreground or as a background daemon, with options to customize the port, workspace, and log level. The `--webui-only` flag is useful when nanobot is managed externally.

```APIDOC
## `nanobot-webui start` — Start the WebUI

### Description
Starts the Nanobot WebUI service. It can be run in the foreground or as a background daemon, with options to customize the port, workspace, and log level. The `--webui-only` flag is useful when nanobot is managed externally.

### Usage
```bash
nanobot-webui start [OPTIONS]
```

### Options
- `-p`, `--port INTEGER`: HTTP port. Defaults to `18780`.
- `--host TEXT`: Bind address. Defaults to `0.0.0.0`.
- `-w`, `--workspace PATH`: Override workspace directory.
- `-c`, `--config PATH`: Path to config file.
- `-d`, `--daemon`: Run in background (daemon mode).
- `-l`, `--log-level TEXT`: Log level: `DEBUG` / `INFO` / `WARNING` / `ERROR`. Defaults to `DEBUG`.
- `--webui-only`: Start only the WebUI HTTP server and agent. IM channels and heartbeat are NOT started. Use this when nanobot is already managed by an external process (e.g. systemd) to avoid two processes competing for the same IM channel connections.

### Examples
```bash
nanobot-webui start
nanobot-webui start --port 9090
nanobot-webui start -d
nanobot-webui start -d --port 9090
nanobot-webui start --workspace ~/myproject
nanobot-webui start --webui-only
nanobot-webui start -d --webui-only
```

### Default Access
Open **http://localhost:18780** — default credentials: **admin / nanobot** — change on first login.
```

--------------------------------

### Start Nanobot WebUI in Daemon Mode

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Starts the nanobot-webui service in daemon mode, allowing it to run in the background. Specifies the log file and PID file locations.

```bash
nanobot-webui start -d --port 18780
# Logs: ~/.nanobot/webui.log
# PID: ~/.nanobot/webui.pid
```

--------------------------------

### Start Nanobot WebUI on a Different Port

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/architecture.md

Command to start the nanobot-webui application on a port other than the default.

```bash
nanobot-webui start --port 9090
```

--------------------------------

### List All Cron Jobs Response Example

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/api-endpoints.md

Example of a successful response when listing all scheduled cron jobs. This shows the structure of a single cron job object.

```json
[
  {
    "id": "uuid-string",
    "name": "Daily summary",
    "enabled": true,
    "schedule": {
      "kind": "cron",
      "expr": "0 9 * * *",
      "tz": "UTC",
      "at_ms": null,
      "every_ms": null
    },
    "payload": {
      "message": "Send daily summary",
      "deliver": true,
      "channel": "telegram",
      "to": "admin_user"
    },
    "state": {
      "next_run_at_ms": 1704067200000,
      "last_run_at_ms": 1704067200000,
      "last_status": "success",
      "last_error": null
    },
    "delete_after_run": false,
    "created_at_ms": 1704067200000,
    "updated_at_ms": 1704067200000
  }
]
```

--------------------------------

### start_api_server(container, host, port)

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Starts the FastAPI/Uvicorn server as an asyncio coroutine. This coroutine runs indefinitely and should be used with `asyncio.gather()` alongside other tasks.

```APIDOC
## async start_api_server(container: ServiceContainer, host: str = "0.0.0.0", port: int = 8080) -> None

Start the FastAPI/Uvicorn server as an asyncio coroutine.

```python
import asyncio
from webui.api.gateway import start_api_server

asyncio.run(start_api_server(container, host="0.0.0.0", port=18780))
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| container | ServiceContainer | — | Service container |
| host | string | 0.0.0.0 | Bind address |
| port | integer | 8080 | HTTP listen port |

This coroutine runs forever; design for `asyncio.gather()` with other tasks.
```

--------------------------------

### GET /api/system/info

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Retrieves general system information.

```APIDOC
## GET /api/system/info

### Description
Retrieves general system information.

### Method
GET

### Endpoint
/api/system/info
```

--------------------------------

### JWT Token Flow Example

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/architecture.md

Illustrates the step-by-step process of JWT token generation, transmission, and validation for user authentication.

```text
1. User logs in at /api/auth/login
   ↓
2. Server creates JWT token:
   {
     "sub": "user-uuid",
     "username": "admin",
     "role": "admin",
     "exp": <7-day-expiry>
   }
3. Token signed with HS256 (secret from webui_secret.key)
   ↓
4. Client stores token in localStorage
5. Client sends token in Authorization header or WebSocket query param
   ↓
6. Server validates token signature and expiry
7. Token rejected if invalid or expired
```

--------------------------------

### run_nanobot()

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Entry point for the `nanobot` command, providing subcommands for WebUI operations such as starting, checking status, and more.

```APIDOC
## run_nanobot() -> None

Entry point for `nanobot` command with WebUI subcommands.

```bash
nanobot webui start
nanobot webui status
```
```

--------------------------------

### Start API Server as Async Coroutine

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Starts the FastAPI/Uvicorn server as an asyncio coroutine. This coroutine runs indefinitely and should be managed within an asyncio event loop, typically using `asyncio.gather()`.

```python
import asyncio
from webui.api.gateway import start_api_server

asyncio.run(start_api_server(container, host="0.0.0.0", port=18780))
```

--------------------------------

### Create New Cron Job Request Body Example

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/api-endpoints.md

Example of the request body structure for creating a new cron job. It includes fields for name, schedule, payload, and deletion behavior.

```json
{
  "name": "string",
  "enabled": "boolean",
  "schedule": {
    "kind": "at|every|cron",
    "at_ms": "integer|null",
    "every_ms": "integer|null",
    "expr": "string|null",
    "tz": "string|null"
  },
  "payload": {
    "message": "string",
    "deliver": "boolean",
    "channel": "string|null",
    "to": "string|null"
  },
  "delete_after_run": "boolean"
}
```

--------------------------------

### Get System Information

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/api-endpoints.md

Fetches general information about the system, including Nanobot and Python versions. Authentication is optional.

```json
{
  "version": "0.3.0",
  "nanobot_version": "0.2.1",
  "python_version": "3.11.0",
  "api_docs": "/api/docs"
}
```

--------------------------------

### Get System Info

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/api-endpoints.md

Retrieves general information about the Nanobot system.

```APIDOC
## GET /api/system/info

### Description
Get system information.

### Method
GET

### Endpoint
/api/system/info

### Response
#### Success Response (200 OK)
- **version** (string) - The current version of the Nanobot WebUI
- **nanobot_version** (string) - The version of the Nanobot backend
- **python_version** (string) - The Python version used by the backend
- **api_docs** (string) - URL to the API documentation

### Response Example
```json
{
  "version": "0.3.0",
  "nanobot_version": "0.2.1",
  "python_version": "3.11.0",
  "api_docs": "/api/docs"
}
```
```

--------------------------------

### run_webui()

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Entry point for standalone `nanobot-webui` or `webui` commands, allowing direct control over the WebUI server, including starting it on a specific port.

```APIDOC
## run_webui() -> None

Entry point for `nanobot-webui` / `webui` standalone commands.

```bash
nanobot-webui start --port 18780
webui start --port 18780
```
```

--------------------------------

### Handle Agent Progress Updates (JavaScript)

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/websocket-protocol.md

Example of handling 'progress' messages received from the server. Logs the progress content and indicates if a tool is being used.

```javascript
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === 'progress') {
    console.log('Progress:', msg.content);
    if (msg.tool_hint) console.log('  → Using a tool');
  }
};
```

--------------------------------

### Environment Variable Denylist Example

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/architecture.md

Lists dangerous environment variables that are blocked by the `exec_env` to prevent security vulnerabilities.

```text
LD_PRELOAD, LD_LIBRARY_PATH, PYTHONPATH, PYTHONSTARTUP,
NODE_PATH, RUBYLIB, RUBYOPT, PERL5LIB, PERLLIB, etc.
```

--------------------------------

### Makefile Shortcuts

Source: https://github.com/good0007/nanobot-webui/blob/main/README.md

Provides convenient shortcuts for common Docker-related tasks when the repository is cloned locally, such as starting, stopping, viewing logs, and building images.

```APIDOC
### `Makefile` shortcuts

If you have the repository cloned, the bundled `Makefile` wraps common tasks:

```bash
make up           # docker compose up -d
make down         # docker compose down
make logs         # follow compose logs
make restart      # docker compose restart
make build        # build local single-arch image
make release      # buildx push :<version-from-pyproject> and :latest
make release VERSION=0.2.7.post4  # override version tag explicitly
```
```

--------------------------------

### Get Agent Configuration

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieve the current configuration settings for the Nanobot agent. Requires an authentication token.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:18780/api/config/agent
```

--------------------------------

### Get Execution Environment Passthrough Variables

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Retrieves a list of environment variable names that should be passed through to the execution tool. Example variables include 'PATH' and 'HOME'.

```python
from webui.utils.webui_config import get_exec_env_passthrough

passthrough = get_exec_env_passthrough()
# Returns: ['PATH', 'HOME', ...]
```

--------------------------------

### Build and Run Nanobot WebUI from Source

Source: https://github.com/good0007/nanobot-webui/blob/main/README.md

Steps to clone the repository, build the Docker image, and run the Nanobot WebUI container.

```bash
git clone https://github.com/Good0007/nanobot-webui.git
cd nanobot-webui

# Build the multi-stage image (bun build → python runtime)
docker build -t nanobot-webui .

# Run
docker run -d \
  --name nanobot-webui \
  -p 18780:18780 \
  -v ~/.nanobot:/root/.nanobot \
  --restart unless-stopped \
  nanobot-webui
```

--------------------------------

### Nanobot CLI Commands

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Common commands for managing the nanobot-webui service, including starting, stopping, checking status, and viewing logs. Also includes commands for channel login.

```bash
nanobot-webui start [--port 18780] [--daemon] [--webui-only]
nanobot-webui stop
nanobot-webui status
nanobot-webui restart
nanobot-webui logs [--follow] [--lines 50]

# Channel login
nanobot channels login weixin
nanobot channels login whatsapp [--force]
```

--------------------------------

### Configure External LLM Providers

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/architecture.md

Example JSON configuration for external LLM providers like OpenAI and a custom provider. This file is located at ~/.nanobot/config.json.

```json
{
  "providers": {
    "openai": {
      "api_key": "sk-வுகளை",
      "api_base": null
    },
    "custom": {
      "api_key": "...",
      "api_base": "https://api.custom.com"
    }
  }
}
```

--------------------------------

### Upgrade Nanobot WebUI via pip

Source: https://github.com/good0007/nanobot-webui/blob/main/README_zh.md

To upgrade, first uninstall the old version and then install the new one to avoid conflicts.

```bash
pip uninstall -y nanobot-webui
pip install nanobot-webui
```

--------------------------------

### Create Custom Provider Response

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/api-endpoints.md

Example response upon successful creation of a custom provider. Note that the API key is masked in the response.

```json
{
  "name": "custom_provider",
  "api_key_masked": "••••••••",
  "api_base": "https://api.custom.com",
  "extra_headers": null,
  "has_key": true,
  "models": [],
  "is_custom": true
}
```

--------------------------------

### Client Message: Start a new session

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/websocket-protocol.md

Format for clearing chat history and starting a new conversation. The server will respond with 'session_info'.

```json
{
  "type": "new_session"
}
```

--------------------------------

### Build and Run Nanobot WebUI Locally with Docker

Source: https://github.com/good0007/nanobot-webui/blob/main/README_zh.md

Instructions for building a local Docker image of Nanobot WebUI from source and running it as a container. This includes cloning the repository, building the image, and starting the container with volume mapping and port forwarding.

```bash
git clone https://github.com/Good0007/nanobot-webui.git
cd nanobot-webui

# Build
docker build -t nanobot-webui .

# Run
docker run -d \
  --name nanobot-webui \
  -p 18780:18780 \
  -v ~/.nanobot:/root/.nanobot \
  --restart unless-stopped \
  nanobot-webui
```

--------------------------------

### Build nanobot-webui production assets

Source: https://github.com/good0007/nanobot-webui/blob/main/README.md

Builds the frontend static assets for production, outputting to web/dist/. These assets are then copied by setup.py.

```bash
cd web
bun run build          # outputs to web/dist/, setup.py copies it to webui/web/dist/
```

--------------------------------

### Initialize UserStore

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Instantiate the `UserStore` class from `webui.api.users` to manage user accounts. The store is thread-safe and uses a default configuration file.

```python
from webui.api.users import UserStore

store = UserStore()
# Creates admin account if needed
```

--------------------------------

### Get Current User Response Body

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/api-endpoints.md

The successful response body for the GET /api/auth/me endpoint, returning the authenticated user's details.

```json
{
  "id": "uuid-string",
  "username": "admin",
  "role": "admin",
  "created_at": "2026-01-01T00:00:00+00:00"
}
```

--------------------------------

### WebSocket Chat Flow: Client Starts New Session

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/websocket-protocol.md

Client requests to start a new session. The server creates a new session and returns its key.

```websocket
Client → Server: {"type": "new_session"}
Server → Client: {"type": "session_info", "session_key": "web:user-id:def456"}
```

--------------------------------

### Docker Compose Setup for Nanobot WebUI

Source: https://github.com/good0007/nanobot-webui/blob/main/README_zh.md

Set up Nanobot WebUI using Docker Compose. This method involves creating a docker-compose.yml file for service definition and then using docker compose commands to manage the container. Data persistence is handled via volume mapping.

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

--------------------------------

### Update Cron Job Request Body Example

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/api-endpoints.md

Example of the request body for updating an existing cron job. All fields are optional, allowing for partial updates.

```json
{
  "name": "string",
  "enabled": "boolean",
  "schedule": { ... },
  "payload": { ... },
  "delete_after_run": "boolean"
}
```

--------------------------------

### webui.api.users.UserStore.__init__

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Initializes the UserStore, which manages user accounts persistently. If no users exist, it creates a default admin account.

```APIDOC
## webui.api.users.UserStore.__init__

### Description
Initialize the user store. Creates default admin account if none exists.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
None

### Endpoint
None

### Request Example
```python
from webui.api.users import UserStore

store = UserStore()
# Creates admin account if needed
```

### Response
#### Success Response (200)
None

#### Response Example
None

### Errors
None explicitly documented.
```

--------------------------------

### Establish WebSocket Connection (JavaScript)

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/websocket-protocol.md

Example of how to establish a WebSocket connection in JavaScript, including handling connection events like open, message, error, and close. Requires an access token from localStorage.

```javascript
const token = localStorage.getItem('access_token');
const ws = new WebSocket(`ws://localhost:18780/ws/chat?token=${token}`);

ws.onopen = () => console.log('Connected');
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  console.log('Server:', msg.type, msg);
};
ws.onerror = (e) => console.error('Error:', e);
ws.onclose = () => console.log('Closed');
```

--------------------------------

### Get Skill Content (GET /api/skills/{name})

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/api-endpoints.md

Retrieves the full content of a specific skill. Requires Admin role authentication. The skill name is provided as a path parameter.

```json
{
  "name": "custom_skill",
  "source": "workspace",
  "content": "def skill():\n    ..."
}
```

--------------------------------

### Legacy CLI Commands for Nanobot WebUI

Source: https://github.com/good0007/nanobot-webui/blob/main/README.md

Demonstrates legacy command-line interface commands for managing the Nanobot service.

```bash
nanobot webui start
nanobot webui status
nanobot webui stop
```

--------------------------------

### List Available Providers

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/QUICK-REFERENCE.md

Fetch a list of all configured providers. Requires an authentication token.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:18780/api/providers
```

--------------------------------

### Initialize ServiceContainer

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Instantiate the main service container with various dependencies. Ensure all required components like config, bus, agent, etc., are provided.

```python
from webui.api.gateway import ServiceContainer
from nanobot.agent.loop import AgentLoop
from nanobot.config.schema import Config

container = ServiceContainer(
    config=config,
    bus=bus,
    agent=agent_loop,
    channels=channel_manager,
    session_manager=session_manager,
    cron=cron_service,
    make_provider=provider_factory,
    webui_only=False
)
```

--------------------------------

### Run Standalone WebUI CLI

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Entry point for `nanobot-webui` or `webui` standalone commands, allowing direct control over the WebUI server.

```bash
nanobot-webui start --port 18780
webui start --port 18780
```

--------------------------------

### GET /api/skills

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Lists all available skills.

```APIDOC
## GET /api/skills

### Description
Lists all available skills.

### Method
GET

### Endpoint
/api/skills
```

--------------------------------

### GET /api/workspace/info

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Retrieves information about the current workspace.

```APIDOC
## GET /api/workspace/info

### Description
Retrieves information about the current workspace.

### Method
GET

### Endpoint
/api/workspace/info
```

--------------------------------

### Configure Nanobot WebUI with Environment Variables

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/QUICK-REFERENCE.md

Environment variables to configure the Nanobot WebUI's port, host, log level, workspace, and configuration file.

```bash
export WEBUI_PORT=18780           # HTTP port
export WEBUI_HOST=0.0.0.0         # Bind address
export WEBUI_LOG_LEVEL=INFO       # Log level
export WEBUI_WORKSPACE=/path/to/ws  # Workspace
export WEBUI_CONFIG=/path/to/config.json  # Config file
export WEBUI_ONLY=false           # Skip channels
```

--------------------------------

### GET /api/sessions

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Lists all active chat sessions.

```APIDOC
## GET /api/sessions

### Description
Lists all active chat sessions.

### Method
GET

### Endpoint
/api/sessions
```

--------------------------------

### GET /api/cron

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Lists all scheduled cron jobs.

```APIDOC
## GET /api/cron

### Description
Lists all scheduled cron jobs.

### Method
GET

### Endpoint
/api/cron
```

--------------------------------

### Run Nanobot CLI Entry Point

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

The primary entry point for the `nanobot` command, enabling access to WebUI subcommands.

```bash
nanobot webui start
nanobot webui status
```

--------------------------------

### GET /api/providers

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Lists all available LLM providers.

```APIDOC
## GET /api/providers

### Description
Lists all available LLM providers.

### Method
GET

### Endpoint
/api/providers
```

--------------------------------

### GET /api/config/s3

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Retrieves the S3 storage configuration.

```APIDOC
## GET /api/config/s3

### Description
Retrieves the S3 storage configuration.

### Method
GET

### Endpoint
/api/config/s3
```

--------------------------------

### GET /api/config/gateway

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Retrieves the server configuration for the gateway.

```APIDOC
## GET /api/config/gateway

### Description
Retrieves the server configuration for the gateway.

### Method
GET

### Endpoint
/api/config/gateway
```

--------------------------------

### GET /api/channels

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Lists all available IM channels and their configurations.

```APIDOC
## GET /api/channels

### Description
Lists all available IM channels and their configurations.

### Method
GET

### Endpoint
/api/channels
```

--------------------------------

### GET /api/config/agent

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Retrieves the current agent settings configuration.

```APIDOC
## GET /api/config/agent

### Description
Retrieves the current agent settings configuration.

### Method
GET

### Endpoint
/api/config/agent
```

--------------------------------

### GET /api/auth/me

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Retrieves information about the currently authenticated user.

```APIDOC
## GET /api/auth/me

### Description
Retrieves information about the currently authenticated user.

### Method
GET

### Endpoint
/api/auth/me
```

--------------------------------

### Docker Compose for Nanobot WebUI

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/QUICK-REFERENCE.md

Set up and run the Nanobot WebUI using Docker Compose, defining service image, environment variables, ports, and volumes.

```yaml
version: '3.8'
services:
  webui:
    image: kangkang223/nanobot-webui:latest
    environment:
      - WEBUI_PORT=18780
      - WEBUI_LOG_LEVEL=INFO
    ports:
      - "18780:18780"
    volumes:
      - ~/.nanobot:/root/.nanobot
    restart: unless-stopped
```

--------------------------------

### Initialize ServiceContainer

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Instantiate the ServiceContainer with necessary services. Use reload_provider to hot-reload the LLM provider.

```python
from webui.api.gateway import ServiceContainer

container = ServiceContainer(
    config=config,
    agent=agent_loop,
    channels=channel_manager,
    # ... other services
)
container.reload_provider()  # Hot-reload LLM provider
```

--------------------------------

### GET /api/workspace/files/{name}

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Reads the content of a specific workspace file.

```APIDOC
## GET /api/workspace/files/{name}

### Description
Reads the content of a specific workspace file.

### Method
GET

### Endpoint
/api/workspace/files/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the file to read.
```

--------------------------------

### GET /api/cron

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/api-endpoints.md

Lists all scheduled cron jobs. Requires administrator authentication.

```APIDOC
## GET /api/cron

### Description
Lists all scheduled cron jobs. Requires administrator authentication.

### Method
GET

### Endpoint
/api/cron

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200 OK)
- **cron jobs** (array) - A list of cron job objects.

### Request Example
None

### Response Example
```json
[
  {
    "id": "uuid-string",
    "name": "Daily summary",
    "enabled": true,
    "schedule": {
      "kind": "cron",
      "expr": "0 9 * * *",
      "tz": "UTC",
      "at_ms": null,
      "every_ms": null
    },
    "payload": {
      "message": "Send daily summary",
      "deliver": true,
      "channel": "telegram",
      "to": "admin_user"
    },
    "state": {
      "next_run_at_ms": 1704067200000,
      "last_run_at_ms": 1704067200000,
      "last_status": "success",
      "last_error": null
    },
    "delete_after_run": false,
    "created_at_ms": 1704067200000,
    "updated_at_ms": 1704067200000
  }
]
```
```

--------------------------------

### Docker Compose with Environment Variables

Source: https://github.com/good0007/nanobot-webui/blob/main/README_zh.md

Example docker-compose.yml demonstrating the use of environment variables to configure Nanobot WebUI, such as port, host, log level, workspace, and config file path.

```yaml
services:
  webui:
    image: kangkang223/nanobot-webui:latest
    container_name: nanobot-webui
    environment:
      - WEBUI_PORT=18780
      - WEBUI_HOST=0.0.0.0
      - WEBUI_LOG_LEVEL=INFO
      # - WEBUI_WORKSPACE=/root/.nanobot/workspace
      # - WEBUI_CONFIG=/root/.nanobot/config.json
      # - WEBUI_ONLY=true
    volumes:
      - ~/.nanobot:/root/.nanobot
    ports:
      - "18780:18780"
    restart: unless-stopped
```

--------------------------------

### webui.utils.webui_config.get_exec_env

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Get environment variables for the exec tool from the web UI configuration.

```APIDOC
## get_exec_env()

### Description
Get environment variables for exec tool.

### Method
Call

### Parameters
None

### Request Example
```python
from webui.utils.webui_config import get_exec_env

env = get_exec_env()
```

### Response
#### Success Response (200)
- **env** (dict[str, str]) - Dict of environment variables
```

--------------------------------

### GET /api/users

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Lists all users in the system. This endpoint is typically restricted to administrators.

```APIDOC
## GET /api/users

### Description
Lists all users in the system. This endpoint is typically restricted to administrators.

### Method
GET

### Endpoint
/api/users
```

--------------------------------

### Manage User Accounts with UserStore

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/README.md

Utilize the UserStore for creating, retrieving, and updating user accounts and passwords.

```python
from webui.api.users import UserStore

store = UserStore()
store.create_user("john", "password123", role="user")
store.get_by_username("john")
store.update_password("user-id", "newpass")
```

--------------------------------

### WebUI Commands

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Provides a set of command-line tools for managing the Nanobot WebUI server, including starting, stopping, checking status, restarting, and viewing logs. It also includes commands for channel login.

```APIDOC
## Commands:

| Command | Purpose |
|---------|---------|
| `nanobot-webui start` | Start WebUI server (foreground or background with `-d`) |
| `nanobot-webui stop` | Stop background daemon |
| `nanobot-webui status` | Show running status and PID |
| `nanobot-webui restart` | Restart background daemon |
| `nanobot-webui logs` | View log file (`-f` to follow) |
| `nanobot channels login <channel>` | Login to a channel (weixin, whatsapp, etc.) |
```

--------------------------------

### GET /api/config/s3

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/api-endpoints.md

Retrieves the S3/OSS storage configuration. Requires Admin role authentication.

```APIDOC
## GET /api/config/s3

### Description
Get S3/OSS storage configuration.

### Method
GET

### Endpoint
/api/config/s3

### Parameters

### Request Body

### Response
#### Success Response (200 OK)
- **enabled** (boolean) - Whether S3/OSS storage is enabled.
- **endpoint_url** (string) - The endpoint URL for S3/OSS.
- **access_key_id** (string) - The access key ID for S3/OSS.
- **secret_access_key** (string) - The secret access key for S3/OSS.
- **bucket** (string) - The bucket name for S3/OSS.
- **region** (string) - The region for S3/OSS.
- **public_base_url** (string) - The public base URL for accessing stored files.

#### Response Example
```json
{
  "enabled": false,
  "endpoint_url": "",
  "access_key_id": "",
  "secret_access_key": "••••••••",
  "bucket": "",
  "region": "us-east-1",
  "public_base_url": ""
}
```
```

--------------------------------

### Get Workspace Info

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/api-endpoints.md

Retrieves configuration and metadata for the Nanobot workspace. Requires administrator authentication.

```APIDOC
## GET /api/workspace/info

### Description
Get workspace configuration and metadata.

### Method
GET

### Endpoint
/api/workspace/info

### Response
#### Success Response (200 OK)
- **path** (string) - The absolute path to the workspace directory
- **exists** (boolean) - Indicates if the workspace directory exists
- **writable** (boolean) - Indicates if the workspace directory is writable

### Response Example
```json
{
  "path": "/home/user/.nanobot/workspace",
  "exists": true,
  "writable": true
}
```
```

--------------------------------

### GET /api/cron/{job_id}

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/api-endpoints.md

Retrieves a specific cron job by its ID. Requires administrator authentication.

```APIDOC
## GET /api/cron/{job_id}

### Description
Retrieves a specific cron job by its ID. Requires administrator authentication.

### Method
GET

### Endpoint
/api/cron/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The ID of the cron job to retrieve.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200 OK)
- **cron job** (object) - The details of the requested cron job.

### Request Example
None

### Response Example
```json
{
  "id": "uuid-string",
  "name": "Daily summary",
  "enabled": true,
  "schedule": {
    "kind": "cron",
    "expr": "0 9 * * *",
    "tz": "UTC",
    "at_ms": null,
    "every_ms": null
  },
  "payload": {
    "message": "Send daily summary",
    "deliver": true,
    "channel": "telegram",
    "to": "admin_user"
  },
  "state": {
    "next_run_at_ms": 1704067200000,
    "last_run_at_ms": 1704067200000,
    "last_status": "success",
    "last_error": null
  },
  "delete_after_run": false,
  "created_at_ms": 1704067200000,
  "updated_at_ms": 1704067200000
}
```
```

--------------------------------

### create_app(container)

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Creates and configures the FastAPI application, registering various routes for authentication, configuration, channels, providers, and more. It returns a configured FastAPI app ready for use with uvicorn.

```APIDOC
## create_app(container: ServiceContainer | None = None) -> FastAPI

Create and configure the FastAPI application.

```python
from webui.api.server import create_app
from webui.api.gateway import ServiceContainer

app = create_app(container)
# Returns configured FastAPI app ready for uvicorn
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| container | ServiceContainer|None | Service container (optional) |

**Returns:** FastAPI application

**Routes registered:**
- `/api/auth/*` — Authentication
- `/api/config/*` — Configuration
- `/api/channels/*` — IM channels
- `/api/providers/*` — LLM providers
- `/api/mcp/*` — MCP servers
- `/api/skills/*` — Skills management
- `/api/cron/*` — Cron jobs
- `/api/sessions/*` — Chat sessions
- `/api/users/*` — User management (admin)
- `/api/system/*` — System info
- `/api/workspace/*` — Workspace files
- `/api/v1/*` — OpenAI-compatible proxy
- `/ws/chat` — WebSocket chat endpoint
- `/*` — Static file serving (React frontend) + SPA fallback
```

--------------------------------

### webui.utils.webui_config.get_exec_env_passthrough

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Get a list of environment variables to pass through to the exec tool from the web UI configuration.

```APIDOC
## get_exec_env_passthrough()

### Description
Get list of environment variables to pass through to exec tool.

### Method
Call

### Parameters
None

### Request Example
```python
from webui.utils.webui_config import get_exec_env_passthrough

passthrough = get_exec_env_passthrough()
# Returns: ['PATH', 'HOME', ...]
```

### Response
#### Success Response (200)
- **passthrough** (list[str]) - List of environment variable names to pass through.
```

--------------------------------

### GET /api/channels

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/api-endpoints.md

Lists all available IM channels and their current operational status. Requires administrator authentication.

```APIDOC
## GET /api/channels

### Description
List all IM channels and their status.

### Method
GET

### Endpoint
/api/channels

### Parameters

### Request Example

### Response
#### Success Response (200 OK)
- **name** (string) - The name of the channel.
- **enabled** (boolean) - Indicates if the channel is enabled.
- **running** (boolean) - Indicates if the channel is currently running.
- **config** (object) - Channel-specific configuration details.

#### Response Example
```json
[
  {
    "name": "weixin",
    "enabled": true,
    "running": true,
    "config": {
      "token": "••••••••",
      "api_key": "••••••••",
      "allow_from": "*"
    }
  },
  {
    "name": "telegram",
    "enabled": false,
    "running": false,
    "config": {
      "api_token": "••••••••"
    }
  }
]
```
```

--------------------------------

### Create a new user

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/python-modules.md

Add a new user to the `UserStore` using the `create_user` method. Specify username, password, and optionally a role. Raises `ValueError` if the username already exists.

```python
user = store.create_user("john", "secret123", role="user")
# Returns: {'id': 'uuid', 'username': 'john', 'role': 'user', 'created_at': '...'}
```

--------------------------------

### GET /api/providers

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/api-endpoints.md

Lists all available providers, including both built-in and custom ones. Requires admin authentication.

```APIDOC
## GET /api/providers

### Description
List all available providers (built-in and custom).

### Method
GET

### Endpoint
/api/providers

### Response
#### Success Response (200 OK)
- **name** (string) - 
- **api_key_masked** (string) - 
- **api_base** (string) - 
- **extra_headers** (object) - 
- **has_key** (boolean) - 
- **models** (array) - 
- **is_custom** (boolean) - 

### Response Example
```json
[
  {
    "name": "openai",
    "api_key_masked": "••••6d4a",
    "api_base": null,
    "extra_headers": null,
    "has_key": true,
    "models": ["gpt-4", "gpt-3.5-turbo"],
    "is_custom": false
  },
  {
    "name": "custom_provider",
    "api_key_masked": "••••abcd",
    "api_base": "https://api.custom.com",
    "extra_headers": {"Authorization": "Bearer ..."},
    "has_key": true,
    "models": ["model-a", "model-b"],
    "is_custom": true
  }
]
```
```

--------------------------------

### Import Workspace Configuration

Source: https://github.com/good0007/nanobot-webui/blob/main/_autodocs/api-endpoints.md

Imports workspace configuration from a provided ZIP file. Requires administrator authentication.

```APIDOC
## POST /api/workspace/config/import

### Description
Import workspace configuration from a ZIP file.

### Method
POST

### Endpoint
/api/workspace/config/import

### Request Body
- Content-Type: multipart/form-data

### Request Example
```
file=<zip-file>
```

### Response
#### Success Response (200 OK)
```