Skip to content
SHC Docs

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).

  1. Name: console stays. 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”, never com.console.app).

  2. 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.

  3. 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.gate with the product’s usual coded refusal (X403029LICENT keyed-but-unentitled, X403036LICOPT never-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.

  4. Ops-only surface. The console’s / is the stacks list, not a homescreen; the launcher shell is the only user homescreen.

  5. 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.

  6. 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).

  7. 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.

  8. 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.js already declares Expo/React Native for both native platforms under com.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; see 2026-08-16-native-release-readiness.md for the ledger, the App Review 4.2 position, the demo-cluster prerequisite, and the no-IAP guard that now runs in make 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 at modules/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.
  • 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.
  1. 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.

  2. Identifier rebrand (expo/bundle/Tauri/VS Code ids) before first publish.

  3. Daemon-side SPA embed + serving route; release-coupled rollout.

  4. Ops-only reshape: / → stacks; remove springboard containers from the console app (springboard-ui stays shared for the launcher shell).

  5. Apps screen: daemon catalog + install; marketplace new-tab link (registration-aware). Retire the iframe dock and marketplace-bridge (marketplace doc §1).

  6. Per-estate console Keycloak client + RBAC screen gating; master-realm entry for the portal-federated owner.

  7. Launcher menu + app-SSO entitlement gating per the free-tier line.

  8. ★ Console-side refusal UI (owed 2026-08-16): the console’s session bootstrap calls shc.console.gate and, 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.

  9. ★ 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:

  1. 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 (only marketplace and portal exist), no app-catalog entry installs it, and apps/console is 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.

  2. App review. See owed item 8.