Skip to content

WebUI

The JANUS WebUI is the operator's administrative browser application. It is a thin client of the Management API: every screen reads a read model from the API, and every change it makes is submitted back through the API.

The one sentence to remember

The WebUI is an API client. Git is the source of truth. Administration produces Git commits — the WebUI never writes WireGuard, nftables, routes or gateway state itself.

What the WebUI is, and what it is not

  • It is a browser front end over the Management API. It holds no privileged channel into the controller: it does not read the desired-state repository, does not open a database connection, does not compile anything, and does not contact a gateway directly.
  • It is a viewer of both desired state and observed runtime state. It is never a second source of truth.
  • It is not the source of truth. Desired state lives in Git; the WebUI authors changes into it and then reads back what reconciliation did.
  • Filtering, sorting and paging are performed by the API, never in the browser.

The WebUI is served as a separate process from the controller and listens on loopback (127.0.0.1:8080) by default; a wider address is an explicit operator decision. In a packaged installation a reverse proxy terminates TLS in front of it and the session cookie takes the hardened __Host- form.

Scope: platform and deployment

Every screen carries a scope signal, and the two scopes are kept visibly apart:

  • Platform scope is platform-wide administration — tenants, deployments, gateway nodes and placement.
  • Deployment scope is administration of one customer's deployment. A deployment scope can never reach another deployment's objects.

The navigation rail renders a Platform block above the deployment-scoped groups so the two cannot be confused.

Platform block

Base path: /app/platform.

Entry Route State
Tenants / Organizations /app/platform/inventory/tenants Available
Deployments /app/platform/inventory/deployments Available
Gateway nodes /app/platform/inventory/gatewaynodes Available
Gateway enrollment /app/platform/enrollment Available
Placement /app/platform/placement Available
Principals & bindings, Roles & bindings, MFA policy, API credentials /app/platform/{principals,roles,mfa-policy,credentials} Available

An entry is only shown as available when its surface actually works through the API. Entries that exist only as declared product structure are rendered non-interactive with an explicit "Planned" marker and never look like a working feature.

Deployment groups

Base path: /app/deployments/<deployment>.

Group Entry Route State
Operate Overview /overview Available
Operate Operations & reconciliation /operations Available
Operate Audit /audit Available
Runtime observability Runtime /runtime Available
Runtime observability Client activity /clients Available
Runtime observability Fabric /fabric Available
Runtime observability Reachability /reachability Available
Runtime observability Explain access /explain Available
Operational visualization Operational dashboard /dashboard Available
Operational visualization Topology & client path /topology Available
Operational visualization Health & trends /health Available
Operational visualization Failure & recovery timeline /timeline Available
Desired state Gateways /inventory/gateways Available
Desired state Sites /inventory/sites Available
Desired state Site Edges /siteedges Available
Desired state Devices /inventory/devices Available
Desired state Resources /inventory/resources Available
Desired state Prefixes / networks /inventory/prefixes Available
Access Access policies /inventory/accesspolicies Available
Access Groups /inventory/groups Available
Access Users /inventory/users Available
Access Device enrollment /enrollment Available
Access Route policies /inventory/routepolicies Prototype listing only
Access NAT policies /inventory/natpolicies Available
Deployment platform Identity providers /identity-providers Available

Two different meanings of \"platform\"

The Platform block is platform-wide administration. The Deployment platform group is deployment-scoped product structure. They are deliberately given different labels so they cannot be confused.

Signing in

First-run setup

On a fresh installation, GET /setup presents the initial setup form. It is reachable without a session because there is no identity yet, and the server re-reads the authoritative setup state on every request — once setup is complete the route creates no further accounts.

Field Required Notes
username yes the primary administrator's locator
displayName yes human-readable name
password yes new password
confirmPassword yes must match password

On success the page reports that initial setup is complete and that setup is now permanently closed, and offers a link into the application. There is no wizard: the setup form creates the primary administrator only. It does not configure topology, gateways or providers.

Sign in

GET /login presents the sign-in surface. The offered methods are read from the API (local credentials, OIDC, or the host-enabled break-glass recovery credential). POST /login accepts username, password and an optional next target. A failed sign-in returns a single uniform error and never discloses whether an account exists.

The JANUS WebUI sign-in page

The WebUI sign-in page (JANUS 0.18.0).

Working with desired state

Browsing an inventory

Open any Desired state or Access entry to see one dense table for that object kind. Search, sort and paging requests are sent to the API; the table body is re-rendered in place (HTMX) without a full page load. A Reset filters action clears the current query. An empty answer is shown differently from a filtered-empty answer, and a permission-limited view states the permission the API requires.

A device inventory table

An inventory table (Devices) with search, sorting, paging and a permission-aware empty state (JANUS 0.18.0).

Creating or editing an object

  • Create: open …/objects/<kind>/new.
  • Edit: open an object from an inventory row, which loads …/objects/<kind>/<name>.

The editor column is the editable desired state. Its fields are:

Field Notes
name required; lowercase letters, digits and hyphens; at most 128 characters
kind-specific fields rendered by declared kind: a switch for booleans, a select, a number input, a text area, or a date-time text field
lookup fields a server-searched combobox, so the browser never enumerates the object set
hidden csrf, action (create/update), etag sent with every submit; the etag is the concurrency guard

The immutable identity of an object is its UUID; the name is the human key.

The editor offers three actions:

  • Validate and review — preflights the change without writing anything.
  • Submit to Git — authors the change through the Management API.
  • Delete — a declarative delete (see below).

enabled is an access state, not an activity state

Wherever the UI shows an enabled flag — on a Device, a User, a Gateway, an Access policy or a Site Edge — it means authorized/activated in desired state. It never means "currently passing traffic". Activity is a separate, observed fact shown only on the runtime and observability surfaces.

Preflight review

Validate and review calls the API's preflight, which performs whole-state validation, the configuration diff and the semantic plan. Nothing is written. The review column renders each checkpoint on its own, and never collapses them into a single "Saved!":

DRAFT → VALIDATED → COMMITTED → RECONCILING → DELIVERED → APPLIED

The lifecycle rail never renders a stage the provider did not report as reached; everything beyond the reached stage is visibly dimmed. The review distinguishes, in its own words:

  • validation and compilation;
  • the configuration diff (what the object changes, line by line);
  • the semantic plan (what the compiler predicts, on which gateways);
  • Git acceptance (the revision the repository accepted);
  • controller reconciliation (whether the revision is last-known-good);
  • gateway delivery and application (per gateway).

An exceptional outcome is labelled explicitly — candidate rejected, refused, stale, failed, rolled back, and Outcome unknown, which is never presented as success.

Submit to Git

Submit to Git submits the candidate through the Management API. An invalid or no-op candidate is refused and not submitted. The result panel reports Git acceptance and the management operation, and states plainly that reconciliation, delivery and application are not claimed unless the API reported them.

Delete

Delete is a declarative delete: the candidate desired state without the object is validated and compiled, authored to Git, and then reconciled normally. The confirmation text states that a delete never tears down WireGuard, nftables or routes in the browser — the WebUI removes the declaration, and reconciliation withdraws the effect. The result view shows the last accepted state as evidence.

Policy authoring

Access policies are authored exactly like any other object: open Access policies, create or edit one, fill in the subject and destination fields, Validate and review, then Submit to Git. The plan panel shows access granted and reachability under separate headings, because routing is not authorization — an AccessPolicy grants access, while Site, RoutePolicy and Prefix affect reachability and grant nobody anything. A disabled policy is valid and grants nothing, and the plan says so explicitly. NAT is never implicit.

Operations and audit

  • Operations & reconciliation (/operations) shows the controller state (last-known-good revision, reconciliation id, OK or retained last-known-good), the gateway state, and the management operation list, using the product's own status vocabulary — including an explicit Outcome unknown.
  • Audit (/audit) lists recent audit events. The screen states that browser diagnostics are never audit, and that the Git author is not the authenticated actor — the actor is recorded separately in audit metadata.

Operations and reconciliation

Operations & reconciliation: the controller's last-known-good revision, per gateway delivery/application state, and the management operation log (JANUS 0.18.0).

Runtime and observability

These surfaces are reads of deployment-scoped API read models; none reaches the repository, the database or a gateway directly.

  • Runtime (/runtime) lists runtime participants — each participant's identity is the pair (GatewayNode, Deployment) — with columns for State, Desired, Applied (observed), Clients, Client port, Fabric, Routes and Last status, plus a bounded log of recent runtime transitions.
  • Client activity (/clients) lists devices; client detail (/clients/{device}) shows desired identity next to observed attachment, kept separate.
  • Fabric (/fabric), Reachability (/reachability) and Explain access (/explain) present the inter-gateway fabric, resource/site reachability, and a path-and-policy explanation.

Desired, delivered, applied and observed are kept independent

The WebUI never merges these into one column. desired is the Git revision, delivered means the gateway agent received and persisted the candidate, applied means the data plane reflects it, and observed is what the participant reported. delivered does not mean applied.

Operational visualization

The Operational dashboard shows state at a glance (participant, client, fabric and resource counts, the desired revision and the generation time), an attention list, and a recent-changes transition log. Topology & client path, Health & trends and the Failure & recovery timeline arrange the same observed state so an operator can see shape, path and change.

A gauge and a derived rate are visually distinct. A topology edge is a placement, attachment or reachability statement — never an authorization. Health and trends on a participant whose state is unknown or stale are never rendered as healthy.

Platform administration

  • Placement (/app/platform/placement) shows deployments by owner and placement, and gateway nodes by sharing and placement, keeping capability, entitlement and placement apart.
  • Gateway node runtime (/app/platform/gatewaynodes/<node>/runtime) is the only WebUI surface that lists several runtime domains of one physical GatewayNode together; it requires platform authority.

Identity and access administration

Four platform-scope surfaces administer administrative identity. They are API clients of the identity-administration endpoints and require the principal:admin permission at platform scope, which the built-in platform_admin role carries. See Identity and access for the workflows themselves.

  • Principals & bindings (/app/platform/principals) lists human accounts and service principals with their kind, state and effective bindings; creates a human account (with an initial password) or a service principal (with no interactive credential); and opens a principal's detail page, where its roles are granted and removed, its account is enabled or disabled, and its API credentials are created and revoked.
  • API credentials (/app/platform/credentials) lists every API credential in the installation by the identity that holds it, with its label, identifier, creation and expiry, last use and state, and revokes one. A credential secret is displayed exactly once, on the identity's own page, immediately after it is created.
  • Roles & bindings (/app/platform/roles) shows the built-in roles with their permissions and every principal→role binding in the installation.
  • MFA policy (/app/platform/mfa-policy) reads, sets and removes the per-scope second-factor requirement, including which factors satisfy it.

Scopes are chosen by name: a deployment or tenant is presented as the name an administrator gave it, never as a raw identifier.

Enrollment

Device enrollment and gateway enrollment each have a shipped WebUI surface. Both are API clients of the canonical enrollment endpoints and make no trust decision of their own.

Gateway enrollment — /app/platform/enrollment

Gateway trust records are controller-global, so this is a platform-scope surface. It lists every gateway identity the controller has seen with its state (pending, approved, rejected or revoked), its public fingerprint, its claimed hostname, its source address, its request and decision times and its last-seen time. From here an administrator decides:

  • Approve a pending record, so the gateway may authenticate with the key it proved possession of;
  • Reject a pending record (terminal);
  • Revoke an approved record, withdrawing trust.

The screen states the boundary plainly: enrollment is trust, not health. Approving a record does not claim the node is reachable; reachability is a runtime fact shown on the runtime and observability surfaces. A record that is not approved fails closed at the API.

The decision routes require gateway:admin at platform scope and a session-bound CSRF token. The API decides the permission; the WebUI only renders the outcome.

Gateway enrollment trust records

Gateway enrollment: trust records with state, fingerprint, source and decision (JANUS 0.18.0).

Device enrollment — /app/deployments/<deployment>/enrollment

Device enrollment is deployment-scoped. The administrator authorizes a person to use Janus: the screen creates a bounded enrolment invitation for a chosen user and device, and presents the invitation code once. The code is never stored, never retrievable again, and is never placed in a URL — so it cannot leak through browser history, bookmarks or a proxy log. The list shows each invitation's state and a non-secret prefix. An unredeemed invitation can be revoked from here.

The ordinary path needs only two things: which user the invitation is for and, optionally, a device name. Everything else is policy: the gateway placement and the client address come from the deployment's declared self-service policy, the lifetime is bounded by default, and the invitation is single-use. The expert overrides — a specific gateway, explicit IPv4/IPv6, a different lifetime or use count, a justification — are available under Advanced; none of them is a prerequisite for the normal path, and none of them changes what the user is authorized to reach.

Creating, listing and revoking invitations require config:read/config:write on the deployment.

Device enrollment invitations

Device enrollment: invitations with state and a non-secret token prefix; the plaintext code is shown once at creation and is never retrievable (JANUS 0.18.0).

End-to-end user onboarding

The invitation is the whole of what the person needs:

  1. the administrator picks the user and creates the invitation;
  2. the administrator gives the invitation code to that person over a channel they trust (it is a bearer secret: treat it like a password);
  3. the person opens the Self-Service Portal at https://<controller>/portal/invitation, enters the code and — for a first-time account — chooses their own password. The administrator never sees or chooses that password;
  4. Janus generates the device's WireGuard key pair in the person's browser, creates the device, and shows a ready-to-import configuration file and QR code;
  5. the person downloads the file and imports it into the official WireGuard client, then activates the tunnel.

No step requires a command line, an API call, Git, a deployment identifier or any knowledge of WireGuard keys. The person never supplies a key, never chooses a gateway, never sees the tunnel addresses and never edits the configuration file; what they can reach is exactly what the deployment's access policy grants, and nothing the portal lets them choose can widen it. The private key is generated on their own device and is never sent to Janus.

Activating an access invitation in the portal

The Self-Service Portal's activation page: the invited user enters the invitation code and — for a first activation — chooses their own password (JANUS 0.18.0).

The Self-Service Portal sign-in page

A returning end user signs in to the Self-Service Portal to see and manage their own devices (JANUS 0.18.0).

Site Edges — /app/deployments/<deployment>/siteedges

A Site Edge is a customer-side participant that routes; a GatewayNode authorizes and carries provider Internet egress — the two are never merged. The Site Edges surface lists each authored SiteEdge object with its enrollment trust and observed state — fingerprint, enrollment state, when it enrolled and when it last made contact. A SiteEdge object is authored through the ordinary object editor.

A SiteEdge can be authored in either of two ways:

  • with spec.identity.publicKey — the key is pre-registered and the edge is enrolled as soon as it proves possession;
  • without it — the SiteEdge is the expected appliance. The operator brings the appliance up from its own local setup page, the Controller shows the request here as Pending approval (with the fingerprint to compare), and an administrator clicks Approve to bind the proven identity and enrol it.

An edge that has been authored but has not completed bootstrap is shown as Pre-registered — which grants nothing, because a public key alone authenticates nothing. An enrolled edge can be revoked from here; revocation fails closed and is never silently undone. Reading the participant requires siteedge:read; approving, rejecting and revoking require siteedge:admin on the deployment.

Site Edge enrollment state

Site Edges: enrollment state, fingerprint and last contact per authored edge (JANUS 0.18.0).

Appliance onboarding is shipped and accepted. SiteEdge objects, the pending/approval flow and the appliance's own local setup page (janus-site-edge-webui) are implemented, covered by unit/integration tests, and have been accepted end to end on a packaged Real-Lab appliance: local setup page → proof of possession → PENDING at the Controller → approve in the Admin WebUI → enrolled → the edge applies its compiled participant profile and carries an authorized customer flow.

What remains out of the WebUI

  • The JANUS-aware client manifest is still not delivered by a WebUI or portal screen. The Self-Service Portal delivers the ordinary WireGuard configuration and a QR code; provisioning a JANUS-aware client (the janus-clientd reference daemon) remains an out-of-band file-placement step. See Client.
  • Route policies is a prototype listing only; the backing API for that listing is not implemented.

Current limitations

These are real limits of the shipped product, not documentation gaps. They are listed so an administrator is not surprised by them:

  • Site Edge onboarding runs through the controller's pending/approval flow and the appliance's own local setup page (janus-site-edge-webui). That page is loopback-only on the appliance: to reach it from another machine, use the reference reverse proxy the package ships (janus-site-edge-proxy.service + /etc/janus/caddy/site-edge.Caddyfile), which needs the optional caddy package, or a reverse proxy you already run. The appliance works without any proxy; only remote access to the local page needs one.
  • Route policies is a prototype listing only; the backing data-plane compilation is not implemented.
  • Portal account lifecycle. A portal account is created when the invited user redeems an invitation and chooses a password. There is no separate "invite an account without a device" flow, no password reset by an administrator and no account deletion. What the identity milestone added is on the account-security side: the signed-in user — administrator or end user — manages their own password, second factors, recovery codes and sessions from /app/account (or /portal/security), and an administrator manages principals, roles, bindings, service principals, API credentials and the MFA policy from the platform identity-administration surfaces described above.

Security notes

The WebUI sets a strict content-security policy with no inline script or style and no third-party origin, plus clickjacking and referrer hardening. Every state-changing route requires both a session and a session-bound CSRF token. The operator's API credential is replayed server-to-server and never reaches the browser.

  • API — the surface the WebUI is a client of
  • Configuration — the desired-state objects the WebUI authors
  • Operations — observing applied state
  • Client — how a user enrols a device and gets a configuration