Run the dashboard

The dashboard is the embedded React web UI that ships inside the revka binary. It is served by the gateway at the same address as the REST API and talks to the runtime exclusively over that API, using a bearer token obtained through device pairing. This guide gets the gateway running, pairs your browser, and orients you in the 18-route navigation. Use it the first time you open the dashboard, or whenever you need to pair a new device.

If you just want the fast path from install to a paired browser, the Quickstart covers it in a few commands. For a page-by-page tour of what each route does, see the Dashboard overview.

Gateway and daemon runtime

The dashboard needs a host process. You have two options:

• revka gateway — starts just the dashboard, REST API, Server-Sent Events stream, and WebSocket endpoints.
• revka daemon — runs the full runtime: the gateway plus all configured channels, the heartbeat, and the cron scheduler, under one supervised process.

For local dashboard work, revka gateway is enough. Use revka daemon (or an OS service) when you want channels and scheduled jobs running alongside the UI.

Gateway only

revka gateway                        # foreground, dashboard + API only
revka gateway start --host 127.0.0.1 --port 42617
revka gateway restart                # graceful restart

Full daemon

revka daemon                         # gateway + channels + heartbeat + cron
revka daemon --host 127.0.0.1 --port 42617

OS service

revka service install
revka service start                  # launchd / systemd / OpenRC

By default the gateway binds to 127.0.0.1. The listen port comes from your config ([gateway].port): a fresh quick setup writes 8080, while the built-in schema default is 42617. The process prints its URL on startup. The runtime modes and service registration are covered in revka gateway, daemon & service and Run as a background service.

Caution

Binding to a non-loopback address such as 0.0.0.0 is refused unless you set allow_public_bind = true under [gateway]. To reach the dashboard from outside your machine, keep it on localhost and front it with a tunnel — see Expose your gateway with a tunnel.

Confirm the gateway is alive before opening a browser. The public health endpoint needs no auth and never leaks secrets:

curl http://127.0.0.1:42617/health
# {"status":"ok","paired":true,"require_pairing":true,"runtime":{...}}

If no dashboard build is bundled, the gateway returns a dashboard-unavailable response for UI routes while the API, WebSocket, pairing, health, and webhook routes keep working. To serve a filesystem build instead of the embedded one, set REVKA_WEB_ROOT or [gateway].web_root — see Dashboard development below.

Getting started with the dashboard

1. Start the host process and note the printed URL.

   revka gateway

2. Open the dashboard at the gateway address. The root path serves the React app.

   http://127.0.0.1:42617/

3. Pair your browser. Revka ships with require_pairing = true, so the first connection shows a login gate that exchanges a one-time code for a bearer token. See Dashboard pairing and authentication for both the localhost and remote flows.

4. Land on the Dashboard page. After pairing, you arrive at /dashboard — the operator overview with a live run DAG, the risk/agent/command rails, and recent runs. From the left sidebar you can reach every other surface.

Dashboard pairing and authentication

The dashboard talks to the gateway over the REST API, and every /api/* request carries Authorization: Bearer <token>. That token comes from a one-time, 6-digit pairing code. Pairing is what stops an unknown browser on your network from driving your agent.

How you obtain the code depends on where the browser is:

• Localhost — the login screen auto-fetches the current code from GET /pair/code and displays it in a large monospace badge. Copy it into the input.
• Remote — the code is not shown in the remote browser. Read the 6-digit code from your terminal (or the CLI) and type it in.

Show or rotate the code from the CLI at any time:

revka gateway get-paircode          # show the current code
revka gateway get-paircode --new    # rotate to a fresh code

When you submit the code, the dashboard calls the pairing endpoint and stores the returned token in localStorage:

POST /pair
X-Pairing-Code: 123456

{
  "paired": true,
  "persisted": true,
  "token": "<bearer-token>",
  "message": "Save this token — use it as Authorization: Bearer <token>"
}

Caution

The token is shown exactly once and the gateway stores only a hash. Save it immediately if you also need it for direct API calls. A 401 at any later point dispatches a revka-unauthorized event and forces re-pairing.

The dashboard UI uses the richer JSON pairing path, which also records device metadata in the device registry so the device shows up on the Pairing page:

POST /api/pair
Content-Type: application/json

{ "code": "123456", "device_name": "My laptop", "device_type": "desktop", "hardware": "macOS" }

Pair another device

Once one device is paired, generate codes for new devices from the Pairing page (/pairing) without restarting the daemon. It calls POST /api/pairing/initiate and renders a QR code plus a copyable code. A new device scans the QR or types the code, and you can revoke any device later.

Action	Method + path	Auth
List paired devices	GET /api/devices	Bearer
Generate a new code	POST /api/pairing/initiate	Bearer
Revoke a device	DELETE /api/devices/{id}	Bearer
Rotate a device token	POST /api/devices/{id}/token/rotate	Bearer
Read the current code (startup)	GET /pair/code	None

The QR payload is a JSON string a mobile client can parse directly:

{ "v": 1, "type": "revka-pair", "host": "<origin><basePath>", "code": "123456" }

Pairing is rate-limited and protected by brute-force lockout. For the full auth model see Pairing & authentication and Secrets, pairing & device auth.

Collapsible sidebar navigation

The dashboard is organized by a persistent left rail with three labelled sections. Click any item to navigate; click the collapse chevron to switch to icon-only mode. The collapsed/expanded state persists in localStorage under the key revka-sidebar-collapsed.

The three sections and their routes are:

• Orchestration — Dashboard /dashboard, Workflows /workflows, Agents /agents, Canvas /canvas, Teams /teams
• Operations — Assets /assets, Skills /skills, Tools /tools, Integrations /integrations, Cron /cron, Pairing /pairing, Config /config, Cost /cost, Skins /skins
• Inspection — Memory /memory, Logs /logs, Audit /audit, Doctor /doctor

The header also carries a theme/skin toggle, a language switcher, and a button that opens the operator chat assistant — a floating panel with chat, terminal, and code tabs available on every page.

Dashboard route map

There are 18 navigable routes. Each links to its detailed reference page.

Route	Page	What it does
/dashboard	Dashboard overview	Live run DAG, risk/agent/command rails, recent runs, audit-chain badge
/workflows	Workflows & editor	Browse, create, edit, run, deprecate, delete workflow definitions; AI-assisted Architect editor
/agents	Agents	CRUD for agent definitions (identity, soul, expertise, agent type, avatar)
/canvas	Canvas	Live visual workspace where agents push HTML/text frames over WebSocket
/teams	Teams	Group agents into delegation topologies with relationship edges
/assets	Assets	Kumiho asset manager: projects, spaces, items, revisions, artifacts, bundles, edges
/skills	Skills	Skill registry plus the ClawHub marketplace and GitHub installer
/tools	Tools	Read-only reference of agent (MCP) tools and discovered CLI binaries
/integrations	Integrations	Read-only catalogue of channels/connectors with status badges
/cron	Cron	Manage scheduled agent and shell jobs; per-job run history
/pairing	Pairing	Generate codes, show QR, rotate, and revoke paired devices
/config	Config	View/edit config.toml via a structured form or raw source editor; MCP server CRUD
/cost	Cost	Session, daily, and monthly spend with per-model breakdown
/skins	Skins	Browse, activate, upload, and delete UI skin packages
/memory	Memory	Force-directed graph of Kumiho memory; filter by kind/space, inspect nodes
/logs	Logs	Live SSE event stream from the daemon with pause and type filtering
/audit	Audit	Tamper-evident audit log viewer with one-click chain verification
/doctor	Doctor	On-demand diagnostics grouped by subsystem with OK/WARN/ERROR results

Note

The legacy /memory-auditor URL redirects to /memory. The map above matches the sidebar’s three sections — Orchestration, Operations, and Inspection.

Explore the surfaces in depth from the Dashboard overview, and jump straight to the workflow, agent, asset, and inspection pages from Workflows, editor & runs, Agents, teams & canvas, Assets & memory explorer, and Logs, audit, doctor, pairing & skins.

Dashboard development

The dashboard is a React + TypeScript + Tailwind + Vite app in the repo’s web/ directory. The gateway and the frontend are developed independently: a plain cargo build is Rust-only and does not run npm. You only need this section if you are editing the UI itself.

1. Run the gateway in one terminal.

   cargo run -- gateway start

2. Run the Vite dev server in a second terminal.

   cd web
   npm ci
   npm run dev

3. Open the Vite dev UI at http://127.0.0.1:5173. Vite proxies the /api, /ws, /pair, /health, and /admin surfaces to http://127.0.0.1:42617 by default. Set REVKA_GATEWAY_URL=http://host:port before npm run dev if your gateway runs elsewhere.

To have the Rust gateway serve a local build without embedding it in the binary, point it at a filesystem web root:

cd web
npm ci
npm run build

cd ..
$env:REVKA_WEB_ROOT = "$PWD/web/dist"
cargo run -- gateway start

The equivalent config key:

[gateway]
web_root = "/absolute/path/to/revka/web/dist"

Dashboard assets resolve in this order: REVKA_WEB_ROOT (when set and non-empty) → [gateway].web_root → the embedded web/dist build → the dashboard-unavailable response. Filesystem serving canonicalizes the configured root and rejects path traversal; hashed assets under assets/ get immutable cache headers, while index.html is served no-cache.

For an official release build, build the frontend before compiling the release binary so it can be embedded:

cd web
npm ci
npm run build

cd ..
cargo build --release --locked

build.rs no longer builds the frontend by default. To restore the old cargo-triggered flow, set REVKA_BUILD_WEB=1 before cargo build.

Troubleshooting

• The dashboard shows a “dashboard unavailable” page. No web build is bundled or resolvable. Verify REVKA_WEB_ROOT/[gateway].web_root or build web/dist. API, pairing, and health routes still work meanwhile.
• The pairing input rejects your code. Rotate it with revka gateway get-paircode --new and try again; codes are single-use and consumed once paired.
• Everything 401s after working. Your token was invalidated (revoked device or rotated token). Re-pair the browser.
• You can’t reach the gateway from another machine. The default bind is loopback-only. Set allow_public_bind = true or front it with a tunnel.

Run the in-dashboard Doctor page or revka doctor from the CLI for structured diagnostics.

Next steps

Dashboard overview A page-by-page tour of every route in the embedded web UI.

Pairing & authentication The full gateway pairing flow, device registry, and bearer tokens.

Chat with your agent Use the operator chat assistant and CLI to talk to your agent.

Run as a background service Keep the gateway and daemon running with launchd, systemd, or OpenRC.