Console architecture: RULED 2026-08-14
Status: open design. Ruled in the owner Q&A of 2026-08-14. The console ships inside shcd, and this note still carries an owed-work list. Companions:
2026-08-14-portal-architecture.md,2026-08-14-marketplace-architecture.md. The three-surface story: Portal (central,my.selfhostedcloud.org) · Marketplace (central,marketplace.selfhostedcloud.org) · Console (per-cluster).
Rulings
Section titled “Rulings”-
Name:
consolestays. The Portal/console pairing is the industry convention. The template identifiers are residue and must be replaced before any first publish (com.selfhostedcloud.console, “SHC Console”, nevercom.console.app). -
Serving: daemon-served, same-origin. shcd serves the built SPA on the estate’s existing publicUrl host, no extra containers, no CORS, ships atomically with releases (launcher-shell-style embed). Today nothing publishes console bytes; this is the vehicle.
-
Auth: per-estate confidential Keycloak client, role-gated screens. On an entitled estate every realm user may sign in; operator screens gate on the RBAC role matrix. No forward-auth wall in front. The registered-cluster owner additionally arrives via the portal-federated master realm (see portal doc §2).
★ AMENDED 2026-08-16. This clause used to read “Every realm user may sign in”, full stop, and that is no longer true on a free estate. The console now requires Hobby or above (ruling below), so the estate’s entitlement is asked before any user’s identity is. What a free-tier estate sees instead: not a login screen and not a broken page, a refusal that names the tier, in the same voice every other paid verb uses, carrying the licensing runtime’s standard renewal pointer. The daemon answers
GET /api/method/shc.console.gatewith the product’s usual coded refusal (X403029LICENTkeyed-but-unentitled,X403036LICOPTnever-licensed → the trial opt-in), and the console renders that, not an error state. Nothing about the estate’s own auth is disconnected by the refusal; a free estate’s Keycloak, its apps and its running deployments are untouched. -
Ops-only surface. The console’s
/is the stacks list, not a homescreen; the launcher shell is the only user homescreen. -
The launcher stays separate from the console, non-React, as lightweight as possible (ruled 2026-08-14): fastest load time wins; no React, no shared component code with the console. But the design and look must match 100%; parity is achieved through shared design tokens and assets (wallpapers, icons, spacing/color variables) and guarded by visual parity checks, never by importing console code into the launcher.
-
Apps area = the daemon’s own catalog, always. The console’s Apps screen is the daemon catalog with direct installs (an ops surface), self-sufficient on unregistered and airgapped estates. The marketplace link sits alongside and opens in a new tab (registration-gated).
-
Strictly single-cluster, in both web and native. “You can login to different consoles from the portal but from console you can’t switch to another console.” Cross-cluster navigation is exclusively the Portal’s job (link-out). No connection switcher anywhere in the console.
-
Build lanes: web is the only released target.SUPERSEDED 2026-08-16: every lane is pushed toward release. The original text read: “web is the only released target. iOS/Android/GNOME/Tauri/VS Code lanes stay in-tree and CI-typechecked as insurance and the multiplatform.one showcase; revisit promotion after the Portal ships.” The owner ruled otherwise on 2026-08-16: first “web only”, corrected within the same breath to “not none, push all of them” and “also do the pwa”. So: iOS, Android, desktop (Tauri / GNOME / VS Code) and a PWA are all release targets. The “revisit after the Portal ships” condition is discharged, not deferred. This is a promotion of existing lanes, not a greenfield:apps/console/app.config.jsalready declares Expo/React Native for both native platforms undercom.selfhostedcloud.console, so ruling 1’s identifier work is done for the console. What is not done is everything between a typechecking lane and a submittable binary; see2026-08-16-native-release-readiness.mdfor the ledger, the App Review 4.2 position, the demo-cluster prerequisite, and the no-IAP guard that now runs inmake lint.
Entitlement lines touching the console (ruled 2026-08-14)
Section titled “Entitlement lines touching the console (ruled 2026-08-14)”- ★ The console itself is Hobby-and-up (ruled 2026-08-16, owner,
verbatim: “No console requires at least hobby”). This is a carve-out
from the free tier, not a born-paid addition; the console ships free
today, the owner was told otherwise, was corrected, and re-affirmed the
ruling with the correction in hand. The full record is in
TIERS.md(“The console line”) and atmodules/license.FeatureConsole.- The free tier stays CLI-complete. install / deploy / update /
restore / recover, the whole catalog, automatic TLS and DNS, backups
and vault are untouched. The shape sold is CLI-complete on free, GUI
paid; a test holds that half (
modules/console:TestConsoleGateTouchesNoCliRoute). - Where the gate lives: the daemon API, not the bytes. Nothing in Go
serves console bytes today (owed item 2 below), and a gate on the
serving path would be bypassed by calling the API the served page
calls. So the enforceable boundary is a console-specific daemon route,
shc.console.gate(modules/console/gate.go), answered by the resolver that actually holds the estate’s posture. The routes the console calls (shc.stack.*,shc.logs.get,shc.events.stream,shc.config.*) are the CLI’s routes and are deliberately not gated; gating them would break free’s CLI. Driving the API by hand past the gate therefore lands you in the CLI’s surface, which is free by the same ruling: that is the sold shape, not a leak. - Owed items 2 and 5 must consult the same decide path
(
gateDecide) rather than re-deriving the question; byte-serving and the per-estate Keycloak client are the console’s second and third doors, and MCP already paid for the lesson that two doors drift.
- The free tier stays CLI-complete. install / deploy / update /
restore / recover, the whole catalog, automatic TLS and DNS, backups
and vault are untouched. The shape sold is CLI-complete on free, GUI
paid; a test holds that half (
- Free tier (permanent): no launcher menu and no SSO into apps. The traefik launcher/menu overlay and app-SSO are paid (Hobby+) features.
- A registered free cluster still gets portal SSO into the master realm (admin access), registration plumbing, not the paid SSO feature.
- Likely offering (directional, owner: “prob”): Hobby free for the first 3 months so users experience SSO into apps before the line bites.
Owed work
Section titled “Owed work”-
Launcher → console entry (owner-requested 2026-08-14): the launcher homescreen gets a way into the console once the console is served (a tile or affordance in the overlay; role-gated visibility to match the console’s RBAC screens). Blocked on item 2; today nothing serves console bytes on any estate, so there is nothing to link to yet.
-
Identifier rebrand (expo/bundle/Tauri/VS Code ids) before first publish.
-
Daemon-side SPA embed + serving route; release-coupled rollout.
-
Ops-only reshape:
/→ stacks; remove springboard containers from the console app (springboard-ui stays shared for the launcher shell). -
Apps screen: daemon catalog + install; marketplace new-tab link (registration-aware). Retire the iframe dock and marketplace-bridge (marketplace doc §1).
-
Per-estate console Keycloak client + RBAC screen gating; master-realm entry for the portal-federated owner.
-
Launcher menu + app-SSO entitlement gating per the free-tier line.
-
★ Console-side refusal UI (owed 2026-08-16): the console’s session bootstrap calls
shc.console.gateand, on a coded refusal, renders a screen that names the tier and points at renewal instead of an ops surface. The daemon half exists (modules/console); the client half lands with the serving work in item 2, since a console nobody serves has no bootstrap to hook. -
★ Demo cluster (owed 2026-08-16, a HARD PREREQUISITE for any app -store submission): a real, seeded, publicly reachable estate with credentials handed to the reviewer. With the console gated, a free-tier reviewer who downloads the app can do nothing with it, the classic minimum-functionality rejection. This was previously a nice-to-have; the 2026-08-16 ruling makes it blocking.
Consequences the ruling raises and does NOT settle
Section titled “Consequences the ruling raises and does NOT settle”Both are the owner’s, and neither is decided here:
-
Grandfathering. Every estate currently on free that uses the console loses it. Grandfather existing installs, cut over, or give a notice period; that is the actual rug moment, and it is an operational decision, not an engineering one.
Measured 2026-08-16, and the measurement makes it cheap: the affected population is zero estates, vendor or customer. Nothing serves the console anywhere; ruling §2’s daemon-served SPA is still owed item 2, there is no
deploy/stack for it (onlymarketplaceandportalexist), no app-catalog entry installs it, andapps/consoleis a build workspace CI typechecks rather than a deployed surface. The launcher has nothing to link to for the same reason (owed item 0’s own note). So this decision is cheap today and gets expensive the moment item 2 ships to a free estate, which is the argument for taking it before, not after. -
App review. See owed item 8.