Admin UI

​

Why a web UI

• Monitoring — watching chat messages, server logs, and plugin logs in real time is awkward in a terminal. A browser tab with live-updating panels is more practical.
• Overview — a dashboard showing workspace count, device count, online status, and channel health gives an at-a-glance picture that requires multiple CLI commands to assemble.
• CRUD operations — adding a workspace, pairing a device, or toggling a channel involves fewer steps in a form than in a terminal.

​

Why NiceGUI

​

Fit with the existing stack

• The ToolRegistry — call any tool without HTTP round-trips
• The ChannelManager — read live channel status
• The CommunicationManager — tap into inbound/outbound message queues for chat viewing
• The workspace path — read conversation JSONL files, config, state, and log files directly

​

Architecture

​

Startup

# Start server with admin UI
hirocli start --admin

# Start server without admin UI (default, unchanged)
hirocli start

​

Port allocation

​

Localhost only

uvicorn.Config(
    app=nicegui_app,
    host="127.0.0.1",
    port=config.admin_port,
)

​

Page structure

​

Sidebar groups and pages

Server
├── Dashboard
├── Workspaces
├── Channels
└── Agents

Nodes / Devices
├── Devices
└── Chats

Configuration
└── Logs

​

Table action button rules

​

Sizing and spacing

1. Never add dense to action icon buttons. dense reduces the touch target to ~24px — adjacent buttons become too close to tap reliably, especially on touch screens or high-density displays.
2. Add class="q-ma-xs" to every action button. This applies a 4 px margin on all sides, creating visible gaps between adjacent buttons and a larger effective click area.
3. Use size="sm" for icon-only buttons in compact table rows. sm is large enough for a comfortable tap target without inflating the row height.

# Correct — adequate target, spaced apart
'<q-btn flat size="sm" icon="play_arrow" class="q-ma-xs" @click="..." />'

# Incorrect — dense kills the hit target; no margin packs buttons together
'<q-btn flat dense size="sm" icon="play_arrow" @click="..." />'

​

Workspace management safety rules

​

Restart dialog

• For non-current workspaces: unchecked by default, user can toggle freely.
• For the current Admin UI workspace: checked and disabled (forced on). Restarting without re-enabling the Admin UI would disconnect the browser session with no way to reconnect from the same UI.

​

Color theme

​

Rules

1. Never hardcode Tailwind palette colors on text or icons. Classes like text-gray-500, text-green-600, or text-blue-500 are fixed values — they do not respond to Quasar’s body--dark class and cause invisible or unclear text when the theme changes.
2. Use Quasar semantic color roles. These are theme-aware by design:

3. Use opacity-* for muted or subdued text and icons. Opacity modulates the current theme color — it looks correct in both light and dark mode without knowing the background.
   Copy

   Ask AI

   ui.icon("wifi_off").classes("text-3xl opacity-50")   # muted icon
   ui.label("subtitle").classes("text-sm opacity-60")    # muted label
   
4. Let body text inherit. The default Quasar body color is white in dark mode and near-black in light mode. Headings and value labels that carry no semantic meaning should carry no color class — they inherit automatically.
5. Use color="white" on buttons inside QHeader. The header background uses the primary color. Flat buttons must declare color="white" (a Quasar named role, not a hex value) so their icons are visible on the primary-colored background.
   Copy

   Ask AI

   ui.button(icon="menu", on_click=drawer.toggle).props('flat dense round color="white"')
   
6. Use Quasar structural components — not Tailwind utility divs — for layout. QHeader, QDrawer, QItem, and QCard auto-adapt their background and text to the active theme. Wrapping layout in plain div with Tailwind background colors breaks dark mode.

​

Sidebar behavior

​

Pages

​

Dashboard

​

Workspaces

​

Channels

• Enable / Disable toggle — icon button that calls ChannelEnableTool or ChannelDisableTool and refreshes the table. The mandatory devices channel displays a lock icon instead and cannot be toggled.

​

Agents

​

Devices

​

Chats

​

Logs

​

Dependency

dependencies = [
    ...,
    "nicegui>=2.0",
]

​

File layout

hirocli/src/hirocli/
├── ui/
│   ├── __init__.py
│   ├── app.py              # NiceGUI app setup, layout shell, sidebar
│   ├── run.py              # run_admin_ui() coroutine for server_process.py
│   └── pages/
│       ├── __init__.py
│       ├── dashboard.py
│       ├── workspaces.py
│       ├── channels.py
│       ├── agents.py
│       ├── devices.py
│       │                   # chats and logs are stub routes registered in app.py
├── runtime/
│   ├── server_process.py   # modified: conditionally adds admin UI coroutine
│   └── http_server.py      # unchanged
├── tools/                  # unchanged — admin UI calls tools directly
└── commands/
    └── root.py             # modified: --admin flag on start command

​

What the admin UI is not

• Not a replacement for the CLI. The CLI remains the primary interface and works without a running server. The admin UI requires a running server process.
• Not a remote management tool. It binds to localhost only. Remote access would require a reverse proxy or tunnel, which is out of scope.
• Not a new API surface. The admin UI calls tools in-process. It does not introduce new HTTP endpoints or WebSocket protocols.
• Not always running. It starts only when explicitly requested via --admin. The server’s core functionality is unaffected when the admin UI is not running.