LiteBot

Dashboard

This chapter is a tour of the LiteBot web dashboard: how you sign in, what each page shows, what you can do there, and which role or permission each page needs. Read it after your first start-up, when you open the dashboard for the first time, or when a user asks why a page is missing for them.

Opening the dashboard

LiteBot serves the dashboard itself, on the same port as the API. Open it in a browser:

http://127.0.0.1:3345/

There is no separate web server to run. In production, put LiteBot behind a TLS reverse proxy and open the dashboard over https:// (see Security).

Signing in

The whole dashboard needs a login. Until you sign in you see only the Sign in form (username and password).

  • The form calls POST /api/auth/login and stores the returned access token, refresh token and user in the browser's local storage under the key litebot-auth.
  • The access token lasts JWT_EXPIRES_IN (default 24h). The dashboard renews it with the refresh token, which lasts 7 days.
  • The sign-out button (top right) clears the stored tokens.
  • On a fresh install with no users in MongoDB, sign in with the bootstrap admin from .env (ADMIN_USERNAME, ADMIN_PASSWORD_HASH). Create real users afterwards. See Users, roles and tenants.

The dashboard hides pages from users who cannot use them, but the server is what enforces access. Hiding a page is a convenience, not a control.

The top bar

Item What it does
Chat Test console for talking to your bots. See Chat.
Analytics Platform analytics view. See Analytics view.
Admin The admin console with a sidebar of pages. See Admin console.
Theme toggle Light or dark theme.
User badge Your username and role. A global admin shows global admin; everyone else shows tenant: <id>.
Tenant switcher Global admin only. See Viewing as a tenant.

The current view is kept in the URL hash (#analytics, #admin/conversations), so you can bookmark a page or use the browser's back button.

Viewing as a tenant

A global admin (role admin) sees a View as tenant drop-down next to the user badge. It lists All tenants (global) and every tenant.

  • Pick a tenant and the page reloads. A viewing as: <id> badge appears.
  • From then on the dashboard adds the header X-Tenant-Id: <id> to every same-origin /api/ request. The server narrows the admin's scope to that tenant, so lists, analytics, tools and knowledge base show what that tenant's admin would see.
  • Pick All tenants (global) to go back to the unrestricted view.
  • The choice is remembered in the browser.

The server ignores X-Tenant-Id from anyone who is not a global admin. Tenant users cannot change their scope.

Chat

The Chat view is a test console. The left sidebar lists the bots you can see (your tenant's bots, or all bots for a global admin). Pick a bot and type.

  • Text chat goes over the WebSocket /chat, with replies streamed into the message bubble.
  • If the bot has voice.enabled: true, a Voice selector appears with Off, Text and Audio. Text and Audio open a Gemini Live session on the /voice WebSocket, authenticated with your login token. Audio uses your microphone, so the browser needs HTTPS (or localhost).
  • If the server has VEXYL_GATEWAY_WS_URL set, a Gateway option also appears. It sends your voice through the Vexyl voice gateway, which calls back into this LiteBot. See Voice.

Chat sessions you start here are real sessions: they are stored in conversations and counted in analytics.

Admin console

The Admin view has a collapsible sidebar with a search box. Each entry is a page:

Page What it shows and lets you do Who sees it
Overview Headline numbers for the last 24 hours, 7 days or 30 days: sessions by hour of day, slow replies, which bots took the calls, what the server reports and what the bots waited on Everyone
Bot Management List, create, edit, test, import and export bots Everyone (writes need bots:*)
Tool Registry List, view, test, validate, create and edit tools Everyone (writes need tools:create)
Knowledge Base Documents, upload, search and collections Everyone (calls need documents:* / collections:*)
Analytics Per-tenant analytics and reports Everyone
Conversations Conversation history, transcripts and traces Everyone (calls need conversations:read)
API Keys Create, list and revoke lbk_ keys Everyone (calls need api-keys:*)
My Tenant Your tenant's LLM keys, usage and shared tools Non-admin users with api-keys:read
Roles & Permissions Built-in and custom roles Global admin only
User Management Dashboard users Users with users:read
Tenants Create tenants; per-tenant keys, usage and shared tools Global admin only
System Settings Health, hot reload, providers, config files, environment Global admin only
Auto Dialer Outbound call campaigns Everyone, when the module is enabled (calls need campaigns:*)

"Everyone" means any signed-in user. Pages marked with a permission are shown to all users, but the server answers 403 to a user whose role lacks it, and the page shows an error. To keep the menu clean for limited users, give them a role that matches what they need (see Built-in roles).

Bot Management

The page header has Import Bot (from an exported .zip) and Create Bot. The tabs are:

Tab Purpose
Overview Every bot in scope with its status. Tick bots and use Export Selected for a bulk export
Testing Send a test message to a bot and try intent detection
Create New bot form (or the visual builder, see below)
View / Edit Opens when you pick a bot
Analytics Per-bot analytics

The bot form covers the system prompt, provider and model, tools, template variables, escalation rules, Session-end tools (onSessionEnd hooks), and the Voice (Gemini Live) block. A global admin also sees a Tenant selector to assign the bot to a tenant. Saving applies the change live, without a restart. The fields are described in Bot configuration reference.

Visual builder

When the dashboard is built with VITE_ENABLE_VISUAL_EDITOR=true, the Create tab offers a drag-and-drop flow builder, and bots that carry a _visualFlow open in it. The server needs ENABLE_VISUAL_EDITOR=true too, or its /api/visual-builder routes are not registered. See Visual flows.

Tool Registry

Tabs: Overview, Testing, Validation, and Create (only if you can write tools). View and Edit open when you pick a tool. A global admin also gets a Reload button.

When a global admin creates a tool, a scope selector offers Global (*) (a database tool for every tenant that is allowed it), a specific tenant (a database tool only that tenant sees), or Disk file (legacy) (writes a .js file under config/tools/). A tenant user always creates database tools in their own tenant. See Tools.

Knowledge Base

Tabs: Overview, Documents, Upload, Search and Collections. Uploads are limited to 10 MB per file. Tenant users see the global collections plus their own; they can write only to their own. See Knowledge base.

Conversations

A filterable list of sessions. Open one to see the Messages or the Traces (per-turn tool calls and timings). You can export a session as JSON or CSV, delete one, or select several and use Delete Selected. See Conversations and analytics.

Analytics (admin page)

Tabs: Sessions, Performance, Usage, Insights, Advanced and Reports. Reports shows daily cost, daily tokens and a per-bot breakdown, and downloads an evidence bundle (transcripts, traces, analytics and the bot configuration) as a zip.

API Keys

Create a key with a name and a role; a global admin also picks the tenant. The full key is shown once, in the creation dialog. Copy it then. The list shows name, role, tenant, created and last-used dates, with a revoke action. A tenant user cannot pick the admin role. See API keys.

Roles, Users, Tenants and My Tenant

  • Roles & Permissions: view the three built-in roles and create, edit or delete custom roles. Built-in roles are read-only.
  • User Management: create users, change role, tenant (global admin only) and status, reset passwords, delete users. A tenant admin sees only users of their own tenant and never sees admin users.
  • Tenants: create a tenant with an id and a display name, then expand it to set the tenant's own LLM provider keys, see its usage, and choose which global tools it may use.
  • My Tenant: the same panel for your own tenant, for tenant users. Keys you set here are used by your tenant's bots; providers you leave unset use the platform keys.

All four are covered in Users, roles and tenants.

System Settings

Global admin only. The tabs are:

Tab What it shows and lets you do
Health Overall status, services (MongoDB, Redis, vector database, auto-dialer) and memory use
Hot Reload Hot-reload status for bot, prompt and tool files
Providers Each LLM provider's status. Test a provider, or Hot Swap API Key to replace a provider key in the running process
Config The bot, prompt and tool files on disk, with a validate action
Environment Read-only view of the main settings and feature flags. API keys are masked (first and last 4 characters)
Outbound Dialer Only when the dashboard is built with the auto-dialer flag. See below

A key changed with Hot Swap lives in memory only. Put the same key in .env or it is lost on the next restart.

Outbound Dialer

The tab has two panels.

Outbound Dialer sets the Default Outbound Endpoint URL: the gateway endpoint campaigns use to place calls. A campaign uses, in order, its own endpoint, then this setting, then AUTO_DIALER_OUTBOUND_ENDPOINT from the server environment. The panel shows which one is in effect. Changes apply to running campaigns from their next call.

Voices and models lets you add your own text-to-speech voices and models per provider, such as cloned or designed voices. Pick a provider, then add model ids and voice ids, each with an optional label. Your entries are listed first in the campaign form, next to the built-in ones. The panel tells you when a provider takes no per-call model, or when the voice id is also the model.

Both panels are editable by a global admin only. See Auto-dialer.

Auto Dialer

When enabled, the Auto Dialer page has three views: the campaign list, the campaign form (bot, endpoint, voice and model, CSV upload with automatic column mapping, retry policy) and the campaign monitor (progress, per-contact call results, start, pause, resume and stop). See Auto-dialer.

Analytics view

The Analytics item in the top bar opens a separate analytics view with tabs Sessions, Performance, Usage, System, Bottlenecks and Insights. It reads the same tenant-scoped analytics as the admin page, with more focus on latency: slowest operations, tool performance and optimisation hints.

Feature flags

Two optional modules are switched on at two levels. The dashboard half is fixed when the binary is built: the VITE_* flags are compiled into the dashboard, so your litebot binary shows the Auto Dialer and visual builder pages only if it was built with them on. Setting a VITE_* variable on the server does nothing. The server half is an ordinary .env setting.

Variable Where Default Meaning
VITE_ENABLE_AUTO_DIALER build time off true shows the Auto Dialer page and the Settings > Outbound Dialer tab
VITE_ENABLE_VISUAL_EDITOR build time off true shows the visual flow builder in Bot Management
ENABLE_AUTO_DIALER server .env false true registers the /api/campaigns routes and starts the dialer
ENABLE_VISUAL_EDITOR server .env false true registers the /api/visual-builder routes

Set the matching pair. A page the dashboard shows while the server flag is off fails with 404 errors; a server module whose page was not built in still works through the API. If you need a page your binary lacks, ask for a build with that flag on.

Where to go next

Quickstart: Binary Users, Roles & Tenants