Web UI

The operator web UI is built into Keeper and served at the /ui route out of the box. No separate process, port, reverse proxy, or static-asset deployment is needed: the single keeper binary carries both the Operator API and the UI for it.

The UI is a layer over the same Operator API as soulctl, MCP, and direct /v1/* calls. Everything available in the UI is available through the API; the UI offers no operations that the API doesn’t.

Access

The UI comes up on the same HTTP listener as the Operator API (port 8080 by default), at the path /ui:

1. Open http://keeper.example.com:8080/ui in a browser.
2. Paste an Archon’s JWT into the token field. Once loaded, the UI calls /v1/* with that token in the Authorization: Bearer header.

The JWT is the same credential used for the Operator API:

• a bootstrap token issued when the first Archon is created (keeper init, see Quick Start);
• a token issued for an existing Archon via POST /v1/operators/{aid}/issue-token.

Permissions in the UI are determined by the Archon’s roles in that JWT: RBAC and Purview are applied on the API side, the same for every client. The UI neither widens nor bypasses the checks — it simply sends requests under your token.

Static assets are public, data is behind JWT

The UI files (/ui/*) are served without authorization — just like the /docs spec viewer. They’re JS/CSS/HTML, not secrets. What’s protected is the API: every request to /v1/* goes through JWT, RBAC, and default-deny checks. Without a valid token the UI loads but shows no data.

What it can do

The UI is a browser interface to the Operator API: what you do through /v1/* is available with the mouse. In particular — working with service incarnations, launching and viewing runs, reviewing the connected souls (Souls), and managing operators (Archons).

The complete, always-current surface of operations is the OpenAPI spec itself: open http://keeper.example.com:8080/docs for an interactive reference to every endpoint.

Turning it on and off

The UI is controlled by a single Keeper config key — web_ui_enabled (top-level):

keeper.yml

# web_ui_enabled: true    # default (omitted / null → ON); false — opt-out

Value	Behavior
omitted / null	default-ON — the UI is mounted at /ui out of the box
true	the UI is mounted at /ui
false	the UI is not mounted; /v1/* and /docs are unaffected

For headless installations (working only through CLI / MCP / API), set web_ui_enabled: false — the /ui route won’t appear, and the rest of Keeper’s surface is unchanged.

The toggle requires a restart

web_ui_enabled is restart-required, not hot-reload. The effective value is read once at startup and fixed in the router; SIGHUP and an API reload don’t toggle it. To enable or disable the UI, change the key in the config and restart keeper. Enabling the UI opens no new ports — the static assets sit on the same :8080.

Embed and dev server

For the operator, the UI is always the built-in /ui: nothing to build or run separately. The Keeper binary carries an already-built static UI bundle, so the interface works even in air-gapped environments — no external CDN required.

A separate dev server (Vite) is only for developers of the UI itself when working on its source — that’s a frontend-development scenario, not Keeper operations. For an operator, the built-in /ui is all it takes.