---
title: "Web UI"
---
The embedded Web UI manages authorized resources through the same API as `karactl`; open the installation's HTTPS origin, without a separate frontend deployment or browser infrastructure credential.

## Sign in

Use your local account or the configured SSO button. Bootstrap and reset-password accounts must complete **Change password**, then sign in again. Later, use **Change password** at the foot of the sidebar. The browser uses HttpOnly session cookies; refresh and CSRF handling are automatic. See [access control](/docs/access-control/) for accounts, SSO and permissions, and [security](/docs/security/) for session protections.

Missing or disabled controls can reflect RBAC restrictions. Without create permission, an empty cluster list says **No accessible clusters** rather than offering creation. Delete actions require deletion permission; backup-policy controls require cluster-update permission. Typing a resource URL does not bypass server authorization.

## Namespace selection

The app-shell switcher offers **All namespaces** and readable namespaces with token/relay health indicators. Selection persists in `?namespace=` and a non-secret local preference. Clusters, backups, events, operations and storages follow that selection. Cluster-detail links retain namespace to distinguish same-named clusters; switching namespace from a detail page returns to the scoped list. Choose an explicit namespace for creation.

**Not in your namespace list** means the selection is absent from your readable list, not necessarily deleted. An API-confirmed missing namespace offers **Back to all namespaces**. See [namespaces and relays](/docs/namespaces/).

## Clusters and creation

**Clusters** lists authorized clusters and their phases. On narrow screens, the cluster filter wraps within its card and wide tables scroll independently. The sidebar uses an icon rail; **Change password** remains available through its key icon, with a tooltip and accessible name.

**Create cluster** opens the catalog-driven wizard:

| Step | What to choose or inspect |
| --- | --- |
| Basics | Namespace, unique name, engine, exact catalog version, topology and optional preset |
| Topology | Engine driver-supported members, components and configuration |
| Resources | Per-component CPU mode and CPU/RAM/disk bounds |
| Backups | Namespace-local storage, supported schedules and optional recovery source |
| Access & TLS | Supported TLS/certificate options, private/public exposure, allowlist and monitoring |
| Review | Complete request, aggregate runtime/resource footprint, volumes and placement limitations |

Use **Continue** or **Back**; validation keeps you on the affected step. Names are 2–12 lowercase letters/digits, begin with a letter and must be unique in the namespace. Schedule retain counts must be positive integers.

Engine-specific fields, presets, minimum resources and connection procedures belong in the [MongoDB](/docs/mongodb/), [RabbitMQ](/docs/rabbitmq/) and [Elasticsearch](/docs/elasticsearch/) guides. Review aggregate capacity across every component against project capacity before submission. Footprint bounds are not initial allocations, a price quote or a host-separation guarantee; backup object storage is additional. Read [platform limitations](/docs/limitations/).

[PostgreSQL](/docs/postgres/) and [Supabase](/docs/supabase/) add single/HA database topology, proxy resources, synchronous policy and engine-specific options. Supabase component versions are release-locked; the [current artifact inventory](/docs/supabase/components/) can reject a catalog preset or component even when its configuration is otherwise valid.

[OpenBao](https://openbao.org/) adds engine options in the Basics step: unseal share count and threshold (5/3 by default), the seal (Shamir, transit or [AWS KMS](https://aws.amazon.com/kms/) auto-unseal, with the transit token and [AWS](https://aws.amazon.com/) keys entered as write-only secrets that are stored encrypted and never shown again), Raft or PostgreSQL storage and the log level. Unseal shares, seal and storage are fixed once the cluster is initialized; **Topology** shows them read-only and only the log level remains editable. When seeding a new OpenBao cluster from a Raft snapshot whose source cluster was deleted, the Backups step accepts the source's unseal shares pasted from your offline copy; they travel once in the create request and are never cached.

PostgreSQL storage is selectable only when the OpenBao engine driver advertises `postgresql-storage`, which requires the control plane's shared PostgreSQL binding service (present in the standard server); merely having PostgreSQL clusters in the namespace is not sufficient. Without that service the wizard disables the option and explains that integrated Raft must be used. Pasted restore shares are discarded when disabled and after submission, including a failed request; retrying requires pasting them again.
[MySQL and PXC](/docs/mysql/) are separate engine driver choices. MySQL offers single or Group Replication (3/5); PXC offers only [Galera](https://galeracluster.com/) `cluster` (3/5), requires [ProxySQL](https://proxysql.com/) and hides Group Replication-only settings. Both expose MySQL-native application access, TLS connection help, physical backup/PITR caveats and engine driver-specific maintenance review.

[Weaviate](/docs/weaviate/) adds single/3–9-member topology with three fixed voters, typed modules/inference and full [S3](https://aws.amazon.com/s3/) backups. Review private-network requirements and topology-preserving [restore limits](/docs/weaviate/backups/).

Creation acceptance starts asynchronous work. Follow cluster health and desired-generation convergence, not just the success notification; see [operations and status](/docs/clusters/#operations-and-status).

## Cluster detail tabs

Tabs and actions are gated by engine capabilities and your permissions.

| Tab | What it shows | Engines where it appears |
| --- | --- | --- |
| Overview | Phase, conditions, password-free connection summary and explicit credential reveal | All |
| Topology | Members, health, resource/membership changes, placement, replacement and logs | All |
| Upgrades | Catalog-based version changes and rolling restart | All; additional controls vary by engine |
| Backups | Supported backup inventory, on-demand backup, storage and schedules | All; recovery capabilities vary |
| Restores | In-place restore or recovery into a new cluster, progress and errors | All |
| Users | Engine identities and roles | MongoDB |
| Access | Engine-native access management | RabbitMQ |
| Elastic Access | Engine-native access management | Elasticsearch |
| Postgres access | PostgreSQL roles, databases and grants | PostgreSQL and Supabase |
| MySQL access | MySQL users, databases, grants and password rotation | MySQL and PXC |
| Recovery | Explicit fenced minority quorum recovery with typed danger confirmation | PXC; requires supported operation and cluster update permission |
| Weaviate access | Native database users, API-key rotation and RBAC roles; capability `weaviateAccess` | Weaviate |
| Components | Supabase service topology/resources | Supabase |
| Functions & SMTP | Source deployment/deletion and write-only SMTP password | Supabase |
| OpenBao | Seal/initialization state per member and Raft voter observations, explicit unseal-key reveal, database credential connections | OpenBao |
| Monitoring | Per-member time series and status context | All |
| Events | Cluster activity and diagnostic messages with actor attribution | All |
| Operations | Durable asynchronous work, progress, failure and initiating actor | All |
| Delete | Deletion or retained-volume/backup choices | All, with deletion permission |

In **Topology → Review & apply**, inspect **What will change** and expand **Merge patch to be sent** for the exact request. CPU-only changes do not move data, but platform resource changes may still restart a member. **Leaving** members remain visible during removal; active-member health ratios exclude them and show their count separately. **Upgrades** distinguishes observed running/member versions from the desired version; **not yet observed** is not deployment confirmation.

PostgreSQL major upgrades (16→17 and 17→18) require **offline maintenance**, not a rolling restart: all data members stop for `pg_upgrade --link`, and database access remains unavailable through replica rebuild. Both the topology change review and upgrade confirmation describe this outage and require a recent successful backup. The in-progress warning retains the offline guidance while data members report mixed source/target majors during replica rebuild. Minor upgrades retain replica-first rolling maintenance (or downtime for a single member).

MySQL/PXC upgrades use their separate catalog paths and block downgrades/engine driver conversion. The 8.0→8.4 path requires a recent successful current-version backup. PXC's Recovery tab is not a generic force-bootstrap switch: the provider refuses an existing Primary component, compares same-history committed positions and completes fencing before recovering one survivor. Full-outage recovery and backup restore use different evidence rules; see [MySQL/PXC operations](/docs/mysql/operations/).

**Reveal credentials** requires `cluster-credentials:read` and is audited. Revealed credentials are the engine's administrative identity, **not an application identity**. Use scoped application access: [MongoDB](/docs/mongodb/access-and-tls/), [RabbitMQ](/docs/rabbitmq/access-and-tls/), [Elasticsearch](/docs/elasticsearch/access-and-security/). The response is not retained in the query cache. Keep copied passwords/URIs out of logs. Reveal also provides the public CA with copy/download controls; if clipboard access fails, use manual copy or download without losing PEM line breaks.

Supabase adds a separately authorized API/dashboard credential reveal; do not expose service-role/secret keys to application browsers. [PostgreSQL access](/docs/postgres/access-and-tls/) describes database identities and ProxySQL limits; [Supabase operations](/docs/supabase/operations/) covers source visibility and key rotation. Functions source controls do not supply an absent runtime artifact.

The **OpenBao** tab reveals the unseal (or recovery) shares and the initial root token only after typing the cluster name; it requires `openbao-unseal-keys:reveal` (administrators by default), is audited, and keeps the response in the open panel only — hide it or leave the page and it is gone. Store the shares offline immediately. Database connections list each target, mount, phase and the credential paths of its roles; creating one needs `clusters:update` on the OpenBao cluster and `database-users:create` on the target, deleting one `database-users:delete` on the target. Only PostgreSQL, MongoDB replica-set and RabbitMQ clusters in the same namespace are offered as targets. In-place restores of an OpenBao cluster from another cluster's snapshot accept pasted unseal shares the same way as the creation wizard.

Changing either the cluster name or namespace discards the revealed material and confirmation state immediately. Pending reveal requests are aborted when their panel is removed, and late responses cannot populate a different cluster's panel.

[Weaviate access](/docs/weaviate/access-and-tls/) lists native users/roles and supports user creation, complete role-list replacement, activation, deletion, key rotation and custom role replacement/deletion, subject to management permissions. Protected identities and built-in roles are read-only. This is separate from the MongoDB Users tab and from administrative reveal. Generated database-user keys appear once in a dedicated dialog, bypassing query/mutation caching; closing it or leaving the tab clears the key, and GET cannot retrieve it. Rotation immediately replaces the old key and also requires `clusters/update` if current roles exceed `viewer`/`read-only`; user deletion needs only `database-users/delete`.

JWT rotation is not a **Functions & SMTP** UI action. Use `karactl -n NS supabase rotate-jwt-secret CLUSTER --yes` or POST `/api/v1/clusters/{cluster}/supabase/rotate-jwt-secret`; follow the [CLI/API rotation procedure](/docs/supabase/operations/#credentials-and-rotation) and coordinate application key replacement.

**Cluster → Backups → Backup now** requires a registered storage. Follow the operation and inventory to completion; acceptance does not mean a successful backup. Restore/clone dialogs can select a source namespace; see [backups and recovery](/docs/backups/) for permissions and storage selection. For destructive retention choices, see [delete or suspend](/docs/clusters/#delete-or-suspend).

## Data MCP

Supported clusters show a **Data [MCP](https://modelcontextprotocol.io/)** card on **Overview**, separate from database connection credentials. Inspect the phase, provider/upstream version, cluster-level access and diagnostic message. Copy the per-cluster endpoint or the `karactl mcp config --cluster <namespace>/<cluster>` command; the CLI, not the browser, mints the restricted token. A write command requests token scope but does not bypass owner RBAC or the installation write switch.

Users with cluster update permission can enable/disable data MCP, select read-only/read-write access, set engine-specific scope, deny tools, require write confirmations and opt into recording query text in audit. Save applies `spec.dataMcp` as a cluster merge patch; disabling asks for confirmation. Other users see settings read-only. Enabling data access and requesting writes are security decisions: review the [data MCP guide](/docs/data-mcp/), particularly [all four write switches](/docs/data-mcp/#four-switches-for-writes), before sharing a client configuration.
### Fleet operations and restore verification

Member agent identity is distinct from the database version. **Upgrade agents** rolls the current control-plane executable through the existing engine safety gates without changing database versions. Unknown agent identities are not proof of a current build; inspect the reported build and operation result. Automatic rollout is opt-in under installation settings.

Configure maintenance time zone, cron starts and durations in the **Topology** maintenance policy editor; the current window badge shows whether disruption can begin. Configured windows gate the start of a new disruption. A pending operation can wait without consuming an execution attempt; an explicit maintenance override bypasses that policy for the requested action, not the engine's quorum or readiness checks. Windows never stop a member halfway through an already-started disruptive step.

Placement evidence is provider-dependent. **Move member** replaces and synchronizes the selected member; it is not a direct disk move. Providers with authoritative placement exclude the predecessor's group, while best-effort providers cannot promise a different host. Review the placement source and warning before confirming.

**Backups → Drills** lists retained reports with pagination and links to individual report details; **Run drill** restores an eligible successful backup into a server-managed throwaway target in the same namespace. The policy editor controls scheduled runs. Reports retain verification checks, data age, restore duration and cleanup outcome. Managed targets are labeled and protected while active. RabbitMQ verification restores definitions only, not messages. See [backup drills](/docs/backup-drills/).

## Installation settings

| Settings page | Purpose |
| --- | --- |
| Backup storages | Register S3 credentials, inspect transport options and latest verification result; see [backups](/docs/backups/) |
| Namespaces | Add/validate projects, inspect relay health, rotate tokens and remove unused namespaces; see [namespaces](/docs/namespaces/) |
| Accounts, RBAC, API tokens, SSO | Account lifecycle, policy/effective-permission checks, one-time token creation and OIDC configuration; see [access control](/docs/access-control/) |
| Monitoring | Collection status and Prometheus guidance; scrape URL is installation-root `/metrics` |
| Orphaned volumes | Read-only inventory of volumes awaiting platform cleanup; see [operations](/docs/operations/#orphaned-platform-volumes) |
| Agent rollout | Inspect the current executable build and opt into bounded automatic member rollout; see [upgrade](/docs/getting-started/upgrade/) |
| Control-plane backup | Configure S3 snapshot policy, run a snapshot and inspect retained reports; rebuild remains an offline administrative action |
| Notifications | Configure write-only webhook, Slack or TLS email destinations, filters and test delivery; inspect delivery failures |

The sidebar **API specification** opens `/api/v1/openapi.yaml`. Settings never expose stored provider infrastructure credentials or the operator master key.

The API-token creation dialog blocks double submission and reuses its retry key for an unchanged body. After creation, the one-time-secret panel provides `KARAKORAM_SERVER` / `KARAKORAM_TOKEN` CLI commands and the running [OpenAPI](https://www.openapis.org/) link. Store the secret before closing; prefer secret-manager injection over pasting secret-bearing commands into history or shared logs.

## Events history and live rows

Global **Events** and cluster **Events** initially load the newest **200** authorized persisted events, not every history page. Matching SSE events merge by ID, newest-first; the live buffer holds up to **500** rows. For older history, use [API pagination](/docs/api/#pagination-and-events) or `karactl events list` with the returned cursor.

Apply **Type**, global **Cluster**, and authorized **Actor / Resource** filters with **Apply filters**. Applied filters persist in the URL; draft edits do not apply automatically. Values are exact and case-sensitive. Type is `Normal`, `Warning` or `Audit`; `OperationFailed` is a reason, not a type. Audit visibility requires the relevant `audit:read` permission. See [audit attribution and durability](/docs/security/#audit-attribution-and-durability).

Expand **Event details** for complete JSON. Cluster names and operation IDs link to their detail pages; authorization still applies to shared links.

## Operation details and cancellation

Acceptance toasts offer **View operation** when the response identifies one. Events and global/cluster **Operations** link to the same detail page. It shows phase, namespace/cluster, target, step, initiating actor, reported progress, message/error, cancellation state and exact UTC timestamps. Active operations poll every three seconds; duration starts at `startedAt`, or `createdAt` if absent.

**Cancel operation…** is available for Pending/Running work with cluster-update permission unless already requested. Confirmation requests cancellation, not rollback; unsafe checkpoints can return **409**, and Running work may remain Running during cleanup. Follow the terminal result. See [API cancellation mechanics](/docs/api/) and the [status model](/docs/clusters/#operations-and-status).

## Monitoring ranges

| Range | Query step |
| --- | --- |
| 15m | 15s |
| 1h (default) | 30s |
| 6h | 2m |
| 24h | 10m |

Selection persists as `range` in the URL; there is no seven-day UI query. Charts retain the full window with sparse samples. Recognized state series have labels/legends; fractional state values represent averaging across sampled states, not extra engine states. Use [external monitoring](/docs/monitoring/) for longer retention.

## Errors and live updates

Read the request error, cluster conditions and existing operation before retrying. Forms preserve server error context; unchanged supported submissions reuse retry keys as described in [safe API retries](/docs/api/#safe-retries-with-idempotency-key).

**Live**, **reconnecting — data may be stale** and **connection lost — data may be stale** describe delivery state. Failed background reads can mark data stale even with SSE connected. Retained values during outages are last-known data, not fresh health confirmation. Refresh and inspect durable CLI/API status before resubmitting; see [SSE reconnect and proxy buffering](/docs/api/#pagination-and-events).

**The page could not be displayed → Reload page** reloads without resubmitting an action. If the origin reports **UI not built**, deploy a binary with built frontend assets; see [contributor build instructions](/docs/contributing/) and [operations](/docs/operations/).