Run the console
The console is the web application your people use to read verdicts, compare models, query the ledger, manage virtual keys and gather evidence. This page says how to run it and what it needs. It runs as its own process, next to the platform, and is not part of the platform Helm chart.
What it needs
- The enforcement hook, for virtual keys and the health check.
- The audit service, for the ledger and for budgets.
- Your sign-in proxy (oauth2-proxy), which is the only part that talks to your identity provider.
- The catalogue directory and your policy configuration, which it reads from disk.
- Two tokens the console's server holds and the browser never sees: the hook's admin token and the audit query token.
Run it
Build once and start the server. It needs Node 22.12 or later.
npm run build
npm startA container image can be built from the Dockerfile in the console's directory, with --build-arg UI_BUILD_ID=<a commit id or tag>. The image runs as a non-root user and listens on port 8080. This image has not been built or run in a real estate. The server speaks plain HTTP unless you give it a certificate and key; put it behind a reverse proxy that terminates TLS, or set both UI_TLS_CERT and UI_TLS_KEY.
| Variable | Default | What it sets |
|---|---|---|
UI_HOST, UI_PORT | 127.0.0.1, 5173 | Where it listens. The image sets 0.0.0.0 and 8080 |
UI_GATEWAY_URL | http://127.0.0.1:8095 | The hook's address |
UI_AUDIT_URL | http://127.0.0.1:9090 | The audit service's address |
UI_OAUTH2_PROXY_URL | http://127.0.0.1:4180 | The sign-in proxy |
UI_GATEWAY_ADMIN_TOKEN | not set | The hook's admin token. Without it the Keys view does not work |
UI_AUDIT_QUERY_TOKEN | not set | The audit service's query token. Without it the Ledger and Budgets do not work |
UI_POLICY_CONFIG | The policy configuration the hook itself loads | |
UI_CATALOGUE_DIR | The admission records and provenance artefacts | |
UI_CLIENT_CATALOGUE_DIR | not set | Your own models' records. Unset means none |
UI_BUILD_ID | not set | A build id the console reports at /version |
UI_RATE_LIMIT | 600 | API requests per client per minute. 0 turns it off |
UI_TRUST_PROXY | not set | 1 reads the client address from X-Forwarded-For; use it only behind a proxy you control |
Keep the two tokens in a secret store and out of any repository.
Who can do what
Every API call needs a signed-in session. The role comes from your identity provider through the sign-in proxy.
- Everyone signed in can read Admission, Compare reports and Compliance.
- The admin role also sees Ledger and Entitlement, and can start a Compare run. Anyone without it is told that those sections are for administrators, and the console makes no request for them.
- A request that changes something, such as issuing or revoking a key, is refused if it comes from another site. The person who acts is recorded from the session, not from anything the browser sends.
Checking that it is running
| Address | Meaning |
|---|---|
/healthz | The process is up |
/readyz | The hook, the audit service and the sign-in proxy each answer. A 503 lists which one does not, as true or false |
/version | The package version and the build id |
None of these needs a session and none returns a secret. The console also shows a banner across the top when it cannot reach the hook or the audit service. The footer's Copy diagnostics button copies the build, the page, the time and recent failed calls, with no cookies or account details, for a support request.
Limits
- The console has not run in a real estate. It has been tested against stand-in services.
- Cookie settings come from your sign-in proxy, not from the console.
- Ledger downloads are limited to the 1,000 rows the audit service returns in one call.
- Starting a Compare run needs the comparison tool on the console's host, or a prebuilt one named by
UI_COMPARE_BIN.