Web Dashboard

MindRoom includes a web dashboard for configuring agents, teams, rooms, and integrations without editing YAML files. Editors keep local draft state and write config.yaml when you use their save action.

Accessing the Dashboard

Standalone Mode:

mindroom run

The dashboard will be available at http://localhost:8765. When running from a source checkout, MindRoom will build the dashboard assets on first start if Bun is available.

SaaS Platform: Access your dashboard at https://<instance-id>.mindroom.chat

Dashboard Tabs

Dashboard (Overview)

The main dashboard shows system stats and monitoring:

• Stats cards - Agents (with status breakdown), rooms, teams, models, and voice status
• Network graph - Visual representation of agent-room-team relationships (desktop only)
• Search and filter - Filter by agents, rooms, or teams
• Export Config - Download configuration as JSON

Agents

Configure AI agents:

• Display name and Role description
• Model - Select from configured models
• Memory backend - Inherit global memory backend or override per agent (mem0, file, or none)
• Tools - Organized into configured tools (green badge) and default tools (no config needed)
• Instructions - Custom behavior instructions
• Rooms - Where the agent operates
• Learning - Enable or disable Agno Learning per agent (enabled by default)
• Learning mode - Choose always (automatic extraction) or agentic (tool-driven)

Teams

Configure multi-agent collaboration:

• Display name and Team purpose
• Collaboration mode - Coordinate (sequential) or Collaborate (parallel)
• Team model - Optional model override
• Team members and Team rooms

Rooms

Manage Matrix room configuration:

• Display name and Description
• Room model - Optional model override
• Agents in room - Select which agents have access

External Rooms

View and manage rooms that agents have joined but are not in the configuration:

• Per-agent view with room names and IDs
• Bulk selection and Leave rooms functionality
• Open in Matrix - Link to view in your Matrix client

Models & API Keys

Configure AI model providers:

• Add/edit models with provider, model ID, host URL, and advanced settings
• Provider API keys section for configuring credentials

Runtime-supported providers: Anthropic, Bedrock Claude, Azure OpenAI, OpenAI, Codex CLI ChatGPT authentication, Kimi Code, Google Gemini, Vertex AI Claude, Ollama, llama.cpp, Groq, OpenRouter, Cerebras, DeepSeek, Z.ai, and the internal synthetic provider. The dashboard preserves provider IDs already present in the configuration; not every runtime provider has a dedicated icon or preset in the add-model dropdown.

Memory

Configure global memory defaults:

• Backend - Global default backend (mem0, file, or none)
• Provider - Ollama (local), OpenAI, or Sentence Transformers
• Model - Provider-specific embedding models
• Credential service - Strictly bind an OpenAI-compatible embedder to a dedicated stored key
• Host URL - For Ollama provider
• File backend settings - Path and file memory tuning options
• Auto-flush settings - Background extraction and flush controls for file-backed memory

Per-agent overrides are configured from the Agents tab using the Memory backend selector.

Knowledge

Manage file-backed semantic or files-only knowledge bases:

• Create/edit/delete knowledge bases with description, mode, path, and refresh-on-access watch settings
• Choose semantic search or files-only access depending on whether a base should build embeddings
• Configure Git repository, branch, filtering, credentials service, and sync options
• Upload and remove files for non-Git-backed knowledge bases
• Reindex or sync a knowledge base on demand
• Track index status (file_count and indexed_count)
• Assign agents to a specific knowledge base from the Agents tab

Git-backed knowledge bases are managed from the dashboard, but file mutations still belong in the repository.

• The dashboard hides upload, dropzone, and per-file delete controls for Git-backed bases.
• /api/knowledge/bases/{base_id}/files reflects the manager's filtered file set (for example include_patterns/exclude_patterns).
• Private HTTPS repo auth can be managed in the Credentials tab, then referenced by knowledge_bases.<id>.git.credentials_service.
• POST /api/knowledge/bases/{base_id}/reindex syncs Git first for Git-backed bases, then rebuilds semantic indexes or publishes files-mode source metadata.
• POST /api/knowledge/bases/{base_id}/upload and DELETE /api/knowledge/bases/{base_id}/files/{path} reject Git-backed bases with 409; update the repository and sync or reindex instead.
• Chat/runtime requests use last successfully published indexes and do not wait for indexing or Git sync.

Credentials

Manage service credentials directly from the dashboard:

• List configured credential services from CredentialsManager
• Create/select service names (for example github_private or model:sonnet)
• Edit raw JSON credential payloads and save via /api/credentials/{service}
• Test credentials existence using /api/credentials/{service}/test
• Delete credential sets using /api/credentials/{service}
• Reuse credentials for Git knowledge sync by setting knowledge_bases.<id>.git.credentials_service to the same service name
• GITHUB_TOKEN auto-seeds github_private (username: x-access-token, token: <GITHUB_TOKEN>, _source: env) unless the service is UI-managed

Schedules

View and manage scheduled tasks across rooms:

• List all schedules with room, status, schedule type, delivery mode, and next run time
• Edit schedule timing, description, and visible or silent delivery
• Cancel schedules by task ID

Skills

Manage OpenClaw-compatible skills:

• List installed skills with origin and edit status
• View skill content (SKILL.md)
• Create new skills with name and description
• Edit user-created skills
• Delete user-created skills

Voice

Configure voice message handling:

• Enable/disable voice message support
• Speech-to-Text - OpenAI transcription or a self-hosted OpenAI-compatible service
• Transcript intelligence - Model selection for mention normalization and light ASR cleanup

Integrations

Connect external services to enable agent capabilities:

• Categories - Email & Calendar, Communication, Shopping, Entertainment, Social, Development, Research, Smart Home, Information
• Search and filter by status (Available, Unconfigured, Configured)
• OAuth flows for Google (6 endpoints), Spotify (4 endpoints), Home Assistant (7 endpoints), and more

Features

Save Status

The sync status indicator in the header shows:

• Synced - All changes saved
• Syncing... - Save in progress
• Sync Error - Sync failed
• Disconnected - Lost connection to backend

If another dashboard tab or a server-side edit changes the configuration, saving an older draft can return HTTP 409. The dashboard keeps your draft and shows persistent recovery guidance, including in the raw configuration recovery editor. Copy any changes you want to keep, refresh the page to load the current configuration, then reapply and save your changes. Further save attempts are rejected locally while the conflict remains; editing the draft or refreshing agent policies does not resolve it. The dashboard does not automatically reload and retry a full replacement, because that could overwrite another writer's changes.

Theme and Responsive Design

Toggle between dark and light themes. The dashboard adapts to desktop and mobile devices.

API Endpoints

The dashboard communicates with the backend API at /api/:

Configuration

When /api/config/load returns validation errors, the dashboard fetches /api/config/raw, opens the recovery editor, and saves a full replacement through PUT /api/config/raw before retrying the structured reload.

When the loaded configuration is composed from multiple files via !include, structured save endpoints reject writes with HTTP 409 and the machine-readable error code config_composed_from_includes, distinguishing this permanent rejection from a retryable stale-write conflict. POST /api/config/load reports the includes state in the x-mindroom-config-uses-includes response header, GET /api/config/raw includes a uses_includes field in its response body, and the dashboard shows a banner explaining that changes must be made by editing the include source files directly. The raw recovery editor keeps working on the top-level file's literal text; see the configuration guide's section on splitting the configuration into multiple files for the full semantics.

Credentials

Credentials support scoping via query parameters:

• agent_name — scope credentials to a specific agent
• execution_scope — scope credentials to a specific worker scope (e.g., shared, unscoped)

Agent-scoped credential routes for shared agents require the authenticated dashboard requester to be a platform administrator or a concrete user in agents.<name>.credential_managers. Requester-private agents allow authenticated requesters to manage OAuth connections in their own isolated scope. Deployment-global OAuth client configuration requires platform-administrator authority, with or without agent_name. Responder access and room membership never grant credential-management access. Unauthorized agent-scoped requests return HTTP 403. Trusted upstream deployments should provide a Matrix requester identity through the configured Matrix user ID header or email-to-Matrix template. Standalone deployments should set MINDROOM_OWNER_USER_ID so API-key dashboard requests manage credentials as the owner Matrix user.

Knowledge

Skills

Schedules

Workers

Token Usage

GET /api/usage returns retained token usage using the same collector as the usage_stats tool. It uses dashboard authentication; ordinary Connections users cannot access it. Standalone deployments should protect the dashboard with MINDROOM_API_KEY as described above.

The JSON includes overall totals, an entity breakdown, a model_breakdown, and user_breakdown. Each user has a canonical user_id, token totals, run_count, and their own model_breakdown. Counters include input, output, total, cache read/write, reasoning, and audio tokens. Models include their provider. Stored per-model details split runs that use several models; older runs fall back to their recorded model. Malformed or inconsistent model details retain the run's tokens under unknown and mark model coverage as incomplete. Requester aliases are combined; user_id: null holds unattributed usage.

Use GET /api/usage?include_daily=true to also return daily_breakdown and daily_coverage. Each daily row includes a UTC date, combined token totals, run_count, and a model_breakdown with input, output, total, cache-read, cache-write, reasoning, and audio counters. With include_daily=true, each entry in user_breakdown also includes its own daily_breakdown with that same row structure. User aliases are combined before daily grouping, and the user_id: null entry includes daily unattributed usage. Daily rows are sorted oldest first and use retained run creation timestamps. Missing or invalid timestamps exclude the run from daily rows and mark daily coverage as incomplete. Users with only undated retained runs have an empty daily_breakdown; their all-time totals still include those runs. The report-level daily_coverage applies to both the overall and per-user daily breakdowns. Omitting include_daily or setting it to false leaves out the daily fields. The API and agent tools share storage reading, aggregation, and serialization.

User and model breakdowns cover retained top-level runs. They can differ from session totals, which may include compacted history and nested team-member usage. Deleted sessions are unavailable. The coverage, model_coverage, and user_coverage fields describe missing sources and these limits. This is a retained-usage report, not a billing ledger. Responses contain no conversation content and use Cache-Control: no-store.

The administrator response also contains private_agent_breakdown, with one row per canonical user_id and agent_name. Rows separate stored session totals and session_count from retained_run_totals, run_count, and model_breakdown. They include daily_breakdown when include_daily=true, with the same input, output, cache-read, cache-write, reasoning, and audio counters. Session totals use a validated private-instance owner or the recorded session requester; retained runs preserve their recorded requester, falling back to the validated owner when missing. Unknown ownership remains user_id: null, and private_agent_coverage reports unavailable attribution or metrics. Compacted history can contribute to session totals without recoverable model or daily detail.

Personal Private-Agent Usage

GET /api/usage/me/private-agents?include_daily=true returns the authenticated requester's usage across their configured private agents. It shares the collector used by get_my_private_usage() and returns the same private rows, without user_id or an administrator user_breakdown. Known requester aliases share one history; other users' databases and shared-agent databases are excluded. The optional include_daily parameter defaults to false.

This endpoint requires trusted upstream authentication with signed JWTs and a verified Matrix identity, using the same identity checks as the personal Connections API. An instance API key alone cannot select a personal user. The requester comes only from authenticated identity; user, agent, and storage-path query overrides are rejected. Ordinary authenticated users can access this personal endpoint; /api/usage retains its existing dashboard administrator access rules.

Health & Readiness

MindRoom tracks runtime phases internally:

When the semantic-search embedder is failing, the health payload additionally carries "embedder": {"status": "failing", "detail": ...} with the classified cause; this block is diagnostic only and never flips liveness. Use /api/health for liveness probes and /api/ready for readiness probes in container orchestrators. Ordinary Matrix transport silence still reaches the watchdog after 120 seconds and makes /api/health return 503 after 180 seconds without a successful sync. While Nio commits durable ingestion progress, the watchdog and /api/health consume the same monotonic progress snapshot and defer for up to MINDROOM_MATRIX_INGESTION_GRACE_SECONDS (default 600). Both stop deferring when that grace expires or progress stops advancing for their respective silence timeout. Successful sync completion refreshes both liveness clocks and clears the ingestion grace window. After 90 seconds without sync or durable ingestion progress, matrix_sync_stall_diagnostics logs bounded await chains for that agent's sync, ingestion runner, ingestion pump, and delivery recovery tasks, including during first-sync and restarted-sync startup grace. Reports repeat at most every 90 seconds and include sync age, time without progress, and ingestion generation without changing watchdog or readiness behavior. Snapshots contain at most four tasks and 32 code locations per task, with strings capped at 240 characters; they exclude locals, message content, and source text, and stop at opaque Future or Task await boundaries. Configure liveness probe failureThreshold to allow sufficient time for watchdog self-healing.

Tools & Matrix