Control UI

Control UI

The Control UI is a browser-based dashboard served by the Gateway for managing chat, configuration, sessions, and monitoring.

Quick Start

After starting the Gateway, open: http://127.0.0.1:18789/

The Control UI is a Vite + Lit single-page app that communicates directly with the Gateway WebSocket on the same port.

Authentication

Auth is supplied during the WebSocket handshake:

• connect.params.auth.token — Gateway token
• connect.params.auth.password — Alternative password auth

The onboarding wizard generates a gateway token by default. Paste it into the dashboard settings on first connect.

Device Pairing

When connecting from a new browser/device:

1. You'll see "disconnected (1008): pairing required"
2. Approve the device:

opensoul devices list
opensoul devices approve <requestId>

• Local connections (127.0.0.1) are auto-approved
• Remote connections require explicit approval
• Each browser profile generates a unique device ID

Features

Chat

• Send messages and receive streaming responses
• View tool calls and live tool output
• Abort running responses with Stop button or /stop
• Inject assistant notes into transcripts
• Session transcript loading (v0.2.4)

Agent Management

• Create Soulmate modal for new agent creation (v0.2.4)
• Agent workspace management
• Per-agent configuration

Channels

• View channel status (WhatsApp/Telegram/Discord/Slack and plugin channels)
• QR code login for WhatsApp
• Per-channel configuration

Sessions

• List all active sessions
• Per-session thinking/verbose overrides
• Session transcript viewing

Configuration

• View/edit ~/.opensoul/opensoul.json
• Schema-driven form rendering
• Raw JSON editor
• Apply + restart with validation
• Base-hash guard against concurrent edit conflicts

Skills

• Status, enable/disable
• Install new skills
• API key management

Monitoring

• Gateway health and status snapshots
• Live log tailing with filter/export
• Event log and manual RPC calls
• Model list

Cron Jobs

• Create, run, enable/disable cron jobs
• Run history
• Delivery configuration

Other

• Node management (list + capabilities)
• Exec approval management
• Gateway update + restart

Remote Access

Tailscale (Recommended)

Use Tailscale Serve for secure remote access without SSH tunnels:

tailscale serve --bg https+insecure://127.0.0.1:18789

SSH Tunnel

ssh -L 18789:127.0.0.1:18789 user@server

Then open http://127.0.0.1:18789/ locally.

UI Development

After modifying ui/:

1. Run pnpm ui:build
2. Restart the gateway to serve updated assets

Related Pages

• Getting Started — Quick setup
• Configuration — Gateway config reference
• Architecture — How the UI connects to the Gateway