WebUI Dashboard

Getting Started

1. Enable WebUI in config.yaml

webui:
  enabled: true
  port: 7777                # default HTTP port
  host: "127.0.0.1"         # localhost only for security
  auth_token: null           # auto-generated if omitted

If you leave auth_token as null, the agent generates a random token on every startup.

2. Start the agent

On startup the agent prints a one-click authentication URL to the console:

WebUI server running
URL: http://127.0.0.1:7777/auth/exchange?token=<TOKEN>
Token: abcd...wxyz (use Bearer header for API access)

3. Open the URL in your browser

Clicking the URL calls /auth/exchange, which sets an HttpOnly session cookie and redirects you to the dashboard homepage. You are now authenticated and can browse all pages.

Authentication

All /api/* routes require a valid token. The middleware checks three methods in order:

Auth endpoints (no token required)

Cookie settings

• httpOnly: true -- prevents JavaScript access (XSS protection)
• sameSite: Strict -- prevents CSRF
• secure: false -- localhost does not require HTTPS
• maxAge: 7 days -- cookie lifetime

Example: cURL with Bearer token

curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:7777/api/status

Dashboard Pages

Each page in the WebUI corresponds to one or more API endpoints. Below is a page-by-page reference of what each screen shows and what you can do.

Dashboard

The main landing page after login. Provides real-time visibility into the running agent via Server-Sent Events.

What it shows:

• Agent uptime, status (running/stopped), and a Run/Stop button
• Metrics: sessions, tools count, knowledge chunks, messages, chats, total tokens, estimated cost
• Current LLM provider and model
• AgentSettingsPanel: switch provider, model, max_tokens, temperature
• TelegramSettingsPanel: DM policy, group policy, admin IDs, bot token
• ExecSettingsPanel: enable/disable exec tools, set scope and allowlist (Linux only)
• Live Logs: real-time log stream via SSE, inline on the Dashboard

Tools Page

Browse, filter, and configure every tool the agent has access to. Tools are grouped by module: telegram, ton, stonfi, dedust, dns, deals, journal, workspace, web, mcp_*, and plugins.

What it shows:

• Each tool's name, description, module, scope, category, and enabled status
• Tool RAG status: whether RAG-based tool selection is enabled, how many tools are indexed, the topK value, total tool count, and always-include patterns

What you can do:

• Enable or disable individual tools
• Override a tool's scope (always, dm-only, group-only, admin-only)
• Toggle Tool RAG on/off and adjust the topK setting

Memory Page

Search the agent's knowledge base and inspect active chat sessions.

What it shows:

• Knowledge base statistics: total knowledge chunks, sessions, messages, chats
• Active chat sessions with chatId, sessionId, messageCount, and contextTokens
• Full-text + vector search results over stored knowledge

What you can do:

• Search the knowledge base with a free-text query (combined full-text and vector search)
• Browse active sessions to see which chats are in progress and how many tokens they consume

Config Page

Read and update the agent's config.yaml from the browser. Changes are written back to the YAML file on disk.

What it shows:

• A structured key-value editor organized by section (agent, telegram, webui, etc.) with typed fields and hot-reload indicators

What you can do:

• View the full configuration or a specific section
• Update any section — changes persist to config.yaml

Soul Page

View and edit the agent's personality and behavioral instructions (the "soul" files).

What it shows:

• Current soul/personality settings that define how the agent behaves and responds

What you can do:

• Read the current soul configuration
• Update the soul settings to change the agent's personality, tone, or behavioral guidelines

Plugins Page

See which plugins are currently loaded into the agent.

What it shows:

• Each loaded plugin's name and version

MCP Servers Page

Manage Model Context Protocol (MCP) server connections. Add, inspect, or remove external tool servers.

What it shows:

• Each server's name, type (stdio or sse), target (package or URL), scope, enabled status, connected status, toolCount, individual tool names, and env key names

What you can do:

• Add a new MCP server (provide name, package, args, url, scope, env as needed)
• Remove an existing MCP server by name

Tasks Page

View and manage scheduled tasks (cron-like jobs the agent executes automatically).

What it shows:

• All scheduled tasks with their current status

What you can do:

• Create a new scheduled task
• Update a task's status

Workspace Page

Browse, read, create, edit, and delete files in the agent's workspace directory.

What it shows:

• File listing for the workspace directory
• File contents when a file is selected

What you can do:

• List workspace files
• Read file contents
• Create or upload new files
• Update existing files
• Delete files

Marketplace (API only)

The plugin marketplace is accessible via API endpoints only. There is no dedicated frontend marketplace page in the WebUI. Plugin installation and update checking are performed via the REST API below.

Setup Wizard

The WebUI includes a first-run setup wizard accessible at /setup. It guides you through all required configuration in a step-by-step flow. Launch it with teleton setup --ui or teleton start --webui on a fresh install.

Configuration Reference

Complete list of all WebUI configuration keys and their defaults:

webui:
  enabled: false              # Enable WebUI server
  port: 7777                  # HTTP port
  host: "127.0.0.1"           # Bind address (localhost only by default)
  auth_token: null             # Auto-generated if omitted
  cors_origins:                # Allowed CORS origins
    - "http://localhost:5173"
    - "http://localhost:7777"
  log_requests: false          # Log all HTTP requests

Security

The WebUI is designed with a defense-in-depth approach:

• Localhost only -- default bind address 127.0.0.1 rejects all non-local connections
• Token secrecy -- the auth token is never fully exposed in logs (only the last 4 characters are shown)
• HttpOnly cookies -- session cookies cannot be read by JavaScript, preventing XSS token theft
• CORS restricted -- only configured origins may make cross-origin requests
• Body limit -- 2 MB maximum request body to prevent abuse
• Security headers -- every response includes X-Content-Type-Options: nosniff, X-Frame-Options: DENY, and Referrer-Policy: strict-origin-when-cross-origin

Remote access

For remote access, use an nginx reverse proxy with SSL termination, or an SSH tunnel:

# Forward local port 7777 to the server's localhost:7777
ssh -L 7777:localhost:7777 user@your-server

# Then open in browser (sets session cookie automatically)
open http://localhost:7777/auth/exchange?token=YOUR_TOKEN

If you use an nginx reverse proxy, ensure the upstream points to 127.0.0.1:7777 and enable HTTPS with a valid certificate. Keep the WebUI host as 127.0.0.1 so the server never listens on a public interface directly.

API Error Format

All API errors follow a consistent JSON envelope:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Successful responses use the same envelope with "success": true and a "data" field containing the result.