Skip to content
SHC Docs

Mobile apps: proposal, owner design conversation 2026-08-16

Status: open design. Some items are ruled, and the console Hobby-gate premise is still awaiting a new ruling. Items marked (ruled) or (decided) were decided by the owner in the 2026-08-16 design conversation. Items marked (recommendation) are this document’s argument and are not decided. Items marked ★ NEEDS OWNER RULING either contradict a standing ruling or correct a premise the owner stated, and must be answered before build.

Amended 2026-08-16 (later the same day): the platform matrix is recorded as decided (§8.3) and the app review strategy with it (§9.6, including the demo-cluster gate as owed build work). ★ And §10.0 flags a ruling made on a WRONG PREMISE: the console was gated to Hobby on the belief that it was “born paid” and therefore additive, which the tree contradicts. That one is NOT resolved here: it needs the owner to re-decide (§12 Q5).

Companions landing today: ../decisions/2026-08-16-marketplace-identity-and-install.md · ../decisions/2026-08-16-portal-cluster-identity.md · ../decisions/2026-08-16-marketplace-entitlement-and-licensing.md.

Standing surface architecture: 2026-08-14-console-architecture.md · 2026-08-14-portal-architecture.md · 2026-08-14-marketplace-architecture.md.


0. ★ The greenfield premise is wrong: corrected before anything else

Section titled “0. ★ The greenfield premise is wrong: corrected before anything else”

The owner asked this to be re-verified and said to speak up if scaffolding was missed. It was. The correction is large enough that it reshapes the proposal, so it goes first.

Run against a fresh clone of main (a66f798a7), whole tree, .git excluded:

Looked forFound
AndroidManifest.xmlnone
*.xcodeproj / *.xcworkspace / Podfile / *.entitlementsnone
pubspec.yaml (Flutter)none
capacitor.config.* / Cordova / NativeScript / Ionicnone
*.webmanifest / manifest.webmanifest / site.webmanifestnone
service worker (sw.js, service-worker*, workbox*, vite-plugin-pwa)none
beforeinstallprompt, display: standalonenone
React Native✅ react-native 0.83.2, pinned in the root pnpm.overrides and in two workspace apps
Expo config✅ apps/console/app.config.js and apps/marketplace/app.config.js
iOS/Android build lanes✅ prebuild:ios, prebuild:android, one run:ios, one run:android, plus root pnpm ios / pnpm android

So the accurate statement is:

Greenfield on PWA. Not greenfield on native.

There is no PWA of any kind anywhere in the repo: no manifest, no service worker, no install affordance. That half of the premise is confirmed.

But apps/console is already a declared iOS and Android application. Its app.config.js reads, verbatim:

platforms: ["ios", "android"],
ios: { bundleIdentifier: "com.selfhostedcloud.console", supportsTablet: true },
android: { package: "com.selfhostedcloud.console" },
plugins: ["vxrn/expo-plugin"],

There is no AndroidManifest.xml in the tree because there is not supposed to be one: one prebuild generates the native projects from app.config.js on demand, and the generated android/ and ios/ trees are build output, not source. Searching for AndroidManifest.xml in an Expo-style prebuild project is searching for a compiler artifact. The scan was correct and the conclusion drawn from it was not.

apps/marketplace is the same shape and still carries template residue: com.marketplace.app for both bundle id and package, the exact identifier console-architecture §1 ruled must never ship.

Beyond mobile, apps/console also carries Tauri (src-tauri/, tauri:build) and GNOME (vite.config.gnome.ts, gjs).

There is already a ruling on all of it: console-architecture §8:

Build lanes: 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.

So the question in front of the owner is not “should we build mobile apps”. It is:

Should the console’s already-existing, already-typechecked native lanes be promoted from insurance to product, and if so, on which platform, and does a PWA get there first and cheaper?

That is a materially cheaper question than the one asked, and it has a different answer, because the marginal cost of the Android lane is not “build an Android app”; it is “add the one Android-only feature and take on a release channel”. §7 follows the argument from there.

One further correction while the premise is being fixed: the owner said “the portal app”. The portal is Frappe: portal-architecture §9, “All portal-side logic on Frappe. The owner explicitly declined a separate Go broker service.” There is no apps/portal workspace package and no portal native lane. The two apps are therefore not two symmetrical builds: the console has native lanes today and the portal has nothing. See §1.3.


RULED: a CONSOLE app and a PORTAL app, never one app.

1.1 The sharp reason: they authenticate against different IdPs

Section titled “1.1 The sharp reason: they authenticate against different IdPs”

Not “they do different things”. The boundary is an identity boundary:

Portal appConsole app
IdPour Keycloakthe customer’s Keycloak
Realmour central realmthat cluster’s tenant realm
Serverone, always the same, oursa different server per user, theirs
Discoverya fixed, compiled-in issuerdiscovered at setup, per connection
Trust rootour TLS chainthe customer’s, possibly a private cluster CA
Token lifetimesours, uniformtheirs, per realm, unknown to us
Who can revokeusthe customer, unilaterally

An app holding both credential sets straddles exactly the boundary the L2 compliance seal protects. From ../decisions/2026-08-16-portal-cluster-identity.md §4.1:

A compliance control the restricted party can flip is theatre.

The seal is real because we hold no admin credential on the customer’s Keycloak, and sealing is “the customer deleting one IdP entry” (§4.1). A single binary that holds a live session against our IdP and a live session against the customer’s cluster is a process in which those two credentials are one memory-safety bug, one logging mistake and one shared keychain group apart. It does not break the seal on paper. It makes the seal a claim about our code quality rather than a claim about what we structurally cannot do, and that substitution is precisely what §4.1 refuses.

A sealed cluster’s console app keeps working because it never talked to the portal.

This falls straight out of the split and is the cheapest available proof that the boundary is drawn in the right place. It matches, and extends to mobile, the properties portal-cluster-identity §4.3 already records as surviving L2: the machine install channel survives because “the install channel carries no human” (§1.5), and purchase approval survives because the approver acts in the portal, not on the cluster (§4.3). Add a third:

The console app survives L2, because it authenticates to the cluster and only to the cluster.

If a future change made the console app depend on a portal session for any non-optional function, that change would have silently broken an L2 seal. This sentence is the regression test for it, and should be carried into the mobile acceptance criteria as a named property, not left as prose.

1.3 ★ The asymmetry the ruling does not yet cover: NEEDS OWNER RULING

Section titled “1.3 ★ The asymmetry the ruling does not yet cover: NEEDS OWNER RULING”

“Two apps” reads as two equal builds. The repo says otherwise:

  • Console app: exists. React Native 0.83, correct identifiers, iOS+Android prebuild lanes, CI-typechecked, screens already written (features/console/src StacksScreen, StackDetailScreen, AppsScreen, EventsScreen, SettingsScreen, MarketplaceScreen, plus daemon/installApp, launcher/menu).
  • Portal app: does not exist in any form. The portal is a Frappe bench (portal-architecture §9) and shares no code with the multiplatform.one workspace.

And there is a third central product with a native lane nobody has ruled on: apps/marketplace, which has its own app.config.js declaring iOS and Android. The three-surface story is Portal · Marketplace · Console (console-architecture header). So “two apps” leaves the marketplace’s native lane unaddressed.

Question for the owner: is the marketplace’s native lane (a) folded into the portal app as a tab, (b) killed and its app.config.js deleted so it stops implying a product, or (c) a third app? (b) is the recommendation; the marketplace is a storefront on our domain reached by top-level navigation (marketplace-identity §5), which is the one thing a browser does best.


2. ★ Multi-cluster: this contradicts a standing ruling. NEEDS OWNER RULING

Section titled “2. ★ Multi-cluster: this contradicts a standing ruling. NEEDS OWNER RULING”

The owner ruled today that the console app needs multiple connections, an SSH-client host list, each with its own realm and tokens.

Console-architecture §7 rules the opposite, and rules it in both surfaces:

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.

The phrase “in both web and native” is not incidental; it was written to pre-empt exactly this request. This proposal will not quietly overwrite it.

2.1 Why the two rulings can be reconciled, and on what terms (recommendation)

Section titled “2.1 Why the two rulings can be reconciled, and on what terms (recommendation)”

The reason §7 exists is a session reason: a console web page that can switch clusters is a page that holds, or can be made to hold, more than one cluster’s credentials in one origin, and the portal already owns cross-cluster navigation, so the switcher buys nothing and costs a boundary.

On a phone that reasoning does not fully transfer, for one concrete reason: there is no portal tab to hop from. The web console’s §7 is livable because the portal is one browser tab away and can log you into any console. An installed app with no connection list is an app the user must delete and reconfigure to look at their second cluster.

So the recommended reconciliation is a narrowing, not a reversal:

  1. §7 stands unchanged for the web console. No switcher, ever.
  2. The native/installed console gets a connection list: an address book, the SSH-client analogy the owner used, which is exactly right: ~/.ssh/config lists hosts; it does not log into all of them at once.
  3. Hard property: exactly one connection is active at a time. Switching connections is a teardown and a re-establish, not a merge.
  4. No aggregate views. Ever. No combined stack list, no combined health, no fleet screen, no cross-cluster search. The moment two clusters’ data appear in one view, the app has become a fleet manager and has taken the Portal’s job, which §7 exists to prevent and which portal-architecture §8 prices as a paid, multi-cluster capability.
  5. Credential isolation is per connection, in separate keychain/keystore entries, with no shared refresh path.

Under those five terms the connection list is a client-side convenience and not a cross-cluster session, and §7’s actual concern is untouched. That is the argument; the owner has to accept or reject it, because it edits a ruled item.

2.2 Three clusters running nextcloud: and a gap in the label ruling

Section titled “2.2 Three clusters running nextcloud: and a gap in the label ruling”

The owner is right that the disambiguator already exists. It is ../architecture/flows/launcher.md §13 Q5, overruled 2026-08-13:

Q5 OVERRULED 2026-08-13: every tile always shows its stack name, iPad-style. […] the server (captionEveryTile) middle-ellipsizes a long name to 14 runes, middle, not end, because estate stack names differ at both ends (gitlab-s3, huly-nextcloud, <name>-api).

Launcher labels are stack names, not app names. That is what tells three Frappe benches apart today, and it is what tells nextcloud from nextcloud-staging apart on one cluster.

★ But it does not solve the cross-cluster case, and this is a real gap. Launcher.md §16 fixes the grouping key as (tenant, environment, stack): “one tile per stack name: group key (tenant, stack)”. There is no cluster component in that key. Three clusters each running a stack named nextcloud produce three labels reading exactly nextcloud, and the middle-ellipsis rule cannot help because the strings are identical.

Recommendation (recommendation): the alias/shortcut label is <stack> · <connection>, where <connection> is the user’s own name for that cluster from §2.1’s address book, user-chosen, therefore short and memorable, therefore ellipsis-friendly. The cluster qualifier is a client-side concern and must not be pushed into the launcher payload, which is under a hard 10,250-byte ceiling (launcher.md §13 Q7, ruled “No” on raising it a third time) and which has no concept of a cluster anyway, being served by one.


3. Android launcher integration (ruled): and the verified mechanics

Section titled “3. Android launcher integration (ruled): and the verified mechanics”

RULED: Android launcher integration on the console app, user-disableable globally and per-app.

The owner asked for the mechanics to be checked against current Android documentation rather than taken on faith. They check out, with one addition and one useful consequence he did not raise.

3.1 <activity-alias>: build-time declaration, runtime toggle, no prompt

Section titled “3.1 <activity-alias>: build-time declaration, runtime toggle, no prompt”

Verified against the Android manifest reference. An <activity-alias> is “an alias for an activity, named by the targetActivity attribute”; the target “must be in the same application as the alias and declared before the alias in the manifest”; the alias “presents the target activity as an independent entity, and can have its own set of intent filters”, its own android:icon and its own android:label. android:enabled “default value is "true"”, so every alias must ship explicitly android:enabled="false" or a fresh install carpets the drawer before the user has connected anything.

The runtime toggle is PackageManager.setComponentEnabledSetting(). Verified: the CHANGE_COMPONENT_ENABLED_STATE permission “is not required if target components are running under the same uid with the caller”; an app changing its own components needs no permission, and the call shows the user nothing. A signature permission is only required to touch another application’s components.

This is the mechanism, and it is the whole reason the feature is possible: icons appear in the app drawer, on their own, with no prompt, when the user connects a cluster.

3.2 requestPinShortcut(): dynamic, home screen, and unavoidably prompted

Section titled “3.2 requestPinShortcut(): dynamic, home screen, and unavoidably prompted”

Verified against the Android shortcuts guide, quoting it directly:

Note: When you attempt to pin a shortcut onto a supported launcher, the user receives a confirmation dialog asking their permission to pin the shortcut. If the user doesn’t let the shortcut be pinned, the launcher cancels the request.

and

Note: If the user doesn’t let the shortcut be pinned to the launcher, your app doesn’t receive a callback.

The dialog is a system dialog, it is per shortcut, and it cannot be suppressed; the creation cannot happen in the background precisely because it requires that confirmation. The old silent path, the com.android.launcher.action.INSTALL_SHORTCUT broadcast, survives only inside ShortcutManagerCompat as a fallback for API 25 and lower; on Android 8.0 (API 26) and above it is gone.

★ Say this plainly so nobody promises it in a demo or a roadmap:

Silent home-screen population is unavailable to anyone, on any Android version we would ship for. It is not an SHC limitation, a permissions gap, or something a launcher partnership unlocks. It is platform design.

What is silent is the app drawer, via aliases. What is prompted is the home screen, via pinned shortcuts. Those are different surfaces and users will conflate them; the UI copy must not.

  • Flagship apps → <activity-alias>. Automatic, drawer, zero prompts, icons baked into the APK. The flagship set is bounded and stable (apps/flagship/), which is exactly the property build-time declaration requires.
  • The long tail → ShortcutManager.requestPinShortcut(). Any app in the catalog, icon fetched from the catalog at runtime, arbitrary label and intent, lands on the home screen, one explicit tap each. Surfaced as a “Add to home screen” affordance next to each app in the console’s app list, so the prompt reads as a consequence of the user’s own tap rather than as an interruption.
  1. Icons bake in at build time. An alias’s android:icon is a drawable resource compiled into the APK. A catalog icon change requires an app release. ★ But this cost is much smaller here than it looks, because of a ruling already made. Launcher.md §13 Q4 ruled: “Category glyphs + monogram fallback. NO VENDOR LOGOS”, “a trademark question with an owner’s name on it, not a lane’s”, noting that 76 of 91 icons were third-party URLs across 57 origins. So the alias icon set is a bounded set of category glyphs plus generated monograms, not 91 churning vendor logos. Category glyphs change approximately never. The build-time bake is a real constraint and an almost-zero-frequency one. The pinned-shortcut path, which takes a runtime icon, absorbs whatever churn remains.
  2. Manifest bloat. Each alias is a manifest entry and a compiled component. Past a few dozen the manifest, the APK and package-manager scan time all grow. Cap the alias set at the flagship list and hold the line; the pinned-shortcut path exists so the cap never becomes a product limit.
  3. OEM launcher jank. setComponentEnabledSetting is well known to be unreliable on some OEM launchers: icons not appearing, disappearing, or not refreshing until the launcher is relaunched or the device rebooted. This is not fixable from inside the app. It needs (a) a device matrix in QA, and (b) UI copy that does not promise instant appearance, and (c) a visible “apps didn’t show up?” path in settings rather than a support ticket.
  4. A disabled alias is still a shipped component. Users with a component inspector will see every flagship alias in the APK regardless of connection. That is an inventory disclosure of what SHC ships, not of what this customer runs, acceptable, but state it so it is not discovered later.

The owner is right that this is the part that decides whether the feature is good or a liability.

Add-only is a defect, not a v1 simplification. When an app is uninstalled on the cluster, its alias must be turned off, or the user accumulates dead icons that launch into 404s, and a dead icon is worse than a missing one, because it teaches the user that the icons lie.

Design it as a reconcile loop against the deployment list, not as an event handler on install:

desired = { alias(stack) : stack ∈ deployments(active connection), entitled, user-enabled }
actual = { alias : getComponentEnabledSetting(alias) == ENABLED }
for alias in desired - actual: setComponentEnabledSetting(alias, ENABLED, DONT_KILL_APP)
for alias in actual - desired: setComponentEnabledSetting(alias, DISABLED, DONT_KILL_APP)

Properties this shape buys that an event handler does not:

  • Idempotent: running it twice changes nothing, so it is safe to run on every foreground, on connection switch, and on push.
  • Convergent after missed events. The app will be backgrounded, killed, and offline. It will miss install and uninstall events. A reconcile loop does not care; a handler chain does.
  • Correct on connection switch, which under §2.1 is the common case: the previous cluster’s entire alias set lands in actual - desired and switches off in one pass, with no special-casing.
  • Correct on entitlement change, which matters because the launcher menu is a Hobby+ feature (see §10); the alias set is that entitlement rendered into the drawer, so a lapse must retract icons, and only a reconcile does that without a bespoke revocation path.

The one thing that needs no reconcile, exactly as the owner said: aliases are package components, so uninstalling the SHC app removes every one of them with the package. There is no orphan sweep, no cleanup broadcast, no BOOT_COMPLETED receiver keeping a registry tidy. This is the strongest argument for aliases over pinned shortcuts: pinned shortcuts are owned by the launcher and outlive the app’s control, which is why the long tail should stay a deliberate, per-app, user-initiated act rather than something the app does in bulk on the user’s behalf.

Reconcile input (recommendation): the same inventory the launcher already computes, read through the daemon rather than re-derived. Do not invent a second source of truth for “what is deployed here”; launcher.md §16’s group key and environment-precedence rules are subtle, already ruled, and already tested, and a second implementation in Kotlin will drift.

User control, per the ruling: global off, and per-app off. Per-app off must be sticky and must win over reconcile; it belongs in desired, not as a post-filter, or the next reconcile pass silently re-enables what the user turned off.


4. ★ The architectural ruling that matters most: the app is not its own browser

Section titled “4. ★ The architectural ruling that matters most: the app is not its own browser”

RULED: Custom Tabs on Android, SFSafariViewController on iOS. Never an embedded WebView for app content.

The owner asked for the SSO claim to be verified against the forward-auth implementation before asserting it. It verifies, and the real mechanism is different from, and stronger than, the summary.

Section titled “4.1 The correction: the shared thing is not an SHC cookie”

The summary was “a shared Keycloak SSO session enforced at Traefik forward-auth”. The gate part is exactly right: ../architecture/access-control.md “Forward-auth flow” §2–3: Traefik calls GET /api/auth/forward-auth with the client’s Authorization header “or shc_access_token cookie”, and SHC validates the bearer against the issuing realm’s userinfo endpoint.

But shc_access_token is not the thing that makes SSO work across apps. From traefik/plugin/launcher.go, in the header comment that exists precisely because this was got wrong once:

The identity gate that closed the disclosure proved callers from the shc_access_token cookie, which auth.go sets, host-only, and ONLY on the forward-auth leg. Every app carrying its own native SSO (gitlab, huly, affine, nextcloud) is deliberately UNGATED, so that cookie is never minted there and never travels between hosts.

and later:

shc_access_token is SameSite=Lax and host-scoped.

A parent-domain cookie was considered and refused for two recorded reasons: it would create a new ambient credential on every host of the parent domain, and it “STRUCTURALLY CANNOT COVER THE ESTATE” because bitspur routes hq.flyingfoxlabs.in, outside .corp.bitspur.com.

So what actually provides single sign-on is the Keycloak SSO session cookie at the auth host, KEYCLOAK_IDENTITY and AUTH_SESSION_ID, named in the same file, which every app’s OIDC redirect rides silently, gated or ungated.

The owner’s conclusion survives this correction and gets stronger. A WebView has its own cookie jar. What that jar fails to contain is not an SHC cookie but the Keycloak session itself. Consequences:

  • Every gated app launched in the WebView performs a full interactive Keycloak login, not a silent redirect.
  • And so does every ungated app: gitlab, huly, affine, nextcloud all carry their own native SSO against the same Keycloak. An embedded WebView breaks the apps that are not behind the gate too. The summary understated the blast radius.
  • An app-per-tab WebView architecture would make it worse than one login per app; it would be one login per app per app launch, since the jar is the shell’s and its lifetime is the shell’s.

That is the single-sign-on property the gate exists to provide, destroyed.

4.2 Custom Tabs: verified, and the platform-sanctioned OAuth surface

Section titled “4.2 Custom Tabs: verified, and the platform-sanctioned OAuth surface”

Chrome’s Custom Tabs documentation, verbatim:

Shared cookie jar and permissions model so users don’t have to sign-in to sites they are already connected to, or re-grant permissions they have already granted.

and, on the alternative:

WebViews […] don’t share state with the browser and add maintenance overhead.

One Keycloak login covers every app opened. That is the property, stated by the platform vendor, and it is the same property SFSafariViewController provides on iOS.

They are also the only sanctioned OAuth surface. RFC 8252 (OAuth 2.0 for Native Apps) states native apps MUST NOT use embedded user-agents for authorization requests, and that authorization endpoints MAY detect and block them. Google does block them, returning disallowed_useragent. Since traefik/plugin/launcher.go already implements PKCE (RFC 7636) with S256, on both legs, unconditionally, an embedded WebView would break the login the estate already ships; the launcher’s own PKCE tests (launcher_pkce_test.go) exist because Keycloak refused every non-PKCE attempt with invalid_request: Missing parameter: code_challenge_method.

★ The same family of reasoning has already been ruled twice, and the precedent should be cited rather than re-argued. ../decisions/2026-08-16-marketplace-identity-and-install.md §4 refuses an iframe of the store inside the console because “the iframe cannot hold a session, not ‘degrades’, cannot”, and rejects the CHIPS / Storage Access API workarounds because they put “a tracking-style consent prompt” in front of the user. A WebView is that same defect with a native wrapper: an isolated jar, an unusable session, and a workaround worse than the disease. This ruling is the mobile edge of a boundary already drawn twice.

4.3 The consequence: what the native app is for

Section titled “4.3 The consequence: what the native app is for”

Rendering is delegated. The native app does exactly five things and no sixth:

  1. Connection management (§2.1, the address book, one active at a time).
  2. The launcher grid: the console’s own UI, native, not a web page.
  3. Notifications.
  4. The alias reconcile loop (§3.5).
  5. NetBird handoff, not a VPN client (§6).

Everything else opens a Custom Tab.

This composes with the aliases exactly as the owner said, and the composition is the nicest property in the design: tapping a drawer icon fires an intent into the SHC app, which resolves the stack against the active connection and opens a Custom Tab straight to that host, already authenticated, because the tab shares the browser’s Keycloak session. The user experiences “a Nextcloud icon on my phone that just opens Nextcloud, logged in”, and the app never rendered a byte of Nextcloud.

4.4 ★ Two owed items this ruling creates, neither of them optional

Section titled “4.4 ★ Two owed items this ruling creates, neither of them optional”

(a) The native app needs its own Keycloak client, and it must be public. The launcher’s PKCE flow deliberately runs a confidential client server-side inside the middleware, and deliberately refuses to hand a token to JavaScript: “An estate access token in a variable readable by any script on somebody else’s application is a worse credential than the one this feature was trying to avoid needing”. A native app cannot reuse that flow: it holds no secret, so it must be a public client with PKCE (the standard AppAuth pattern, and what RFC 8252 prescribes). That is a new per-cluster Keycloak client, and access-control.md’s redirect-URI discussion notes that publicClient: true puts the client back under the strict redirect-URI rule that shc-forward-auth’s confidential wildcard is exempted from. The native client’s redirect URIs must be exact: the app’s custom scheme (shc-console://, cf. scheme: "shc-console" already in app.config.js) or an App Link / Universal Link, never a wildcard.

(b) Keycloak SSO cookies are non-persistent by default, and mobile will expose that. launcher.go records the measurement:

Keycloak’s SSO cookies (KEYCLOAK_IDENTITY, AUTH_SESSION_ID) are NON-PERSISTENT by default: the browser drops them when it exits.

On desktop that produces the already-documented “sign in while signed in” confusion after a browser restart. On mobile it is much worse, because Android and iOS kill the browser process routinely and without user action. The promise “one Keycloak login covers every app” is true within a browser session and false across restarts, and on a phone restarts are frequent and invisible.

This must be measured and decided before the launcher-icon feature ships, or the flagship experience is: tap a drawer icon, get a login screen, several times a day. The levers are the realm’s SSO Session Idle / Max settings and Keycloak’s “Remember Me” (which makes the identity cookie persistent). This is an estate-side fix, not an app-side one, which is worth noticing, because it means a PWA-first console hits the identical wall and gets the identical benefit. It is not a native-vs-PWA discriminator; it is a prerequisite for both.


5. iOS: no alias equivalent, ship anyway (ruled)

Section titled “5. iOS: no alias equivalent, ship anyway (ruled)”

iOS has no <activity-alias> equivalent. There is no supported API by which an app places additional, independently-labelled, independently-iconned launchers for third-party destinations on the Home Screen. setAlternateIconName swaps the app’s own icon and is one icon, not many.

The only per-app-icon story on iOS is: the user visits the app’s URL in Safari and does Share → Add to Home Screen, once per app, by hand.

★ And it is weaker still than “manual”, in a way worth stating. An Add-to-Home-Screen result is only a real web app, installed, standalone, push-capable, if the origin serves a web app manifest. Those origins are Nextcloud, GitLab, Immich, Huly. SHC does not control them. Whether a given app gets a proper icon and a standalone window or a generic screenshot bookmark is decided by third-party upstreams, per app, and will be inconsistent across a catalog of 91. SHC can improve this for apps it serves itself and cannot for the rest.

RECOMMEND SHIPPING iOS ANYWAY (recommendation). The management surface, notifications, connection management and the NetBird handoff are entirely platform-neutral, and they are, per §7, the substance of the product. Do not withhold a platform because one enhancement does not port. The reverse error is the common one: holding both platforms hostage to feature parity, and shipping neither.

The honest framing for users, which should appear in the product and not only here: the drawer-icon feature is an Android feature. Not “coming soon to iOS”.


6. Reachability: the owner’s correction, carried

Section titled “6. Reachability: the owner’s correction, carried”

../architecture/access-control.md, verbatim:

Exposure axis | Per-deployment and orthogonal to access: exposure: lan (the default, reachable on the LAN only) or exposure: internet.

and:

Access and exposure are two independent axes.

Legacy public: migration seeds exposure to lan as well. So the default SHC deployment is unreachable from a phone on cellular, and a mobile console that can only work on the home Wi-Fi is not a mobile console.

6.2 The owner’s correction, verified: NetBird already solves it

Section titled “6.2 The owner’s correction, verified: NetBird already solves it”

The owner corrected an earlier framing in which a bundled VPN profile was the reason to go native. He is right, and every part of it checks out:

  • NetBird is a flagship app. apps/flagship/netbird/app.yaml: name: netbird, version: "0.76", description: NetBird - VPN mesh networking with WireGuard, category: networking, tags including vpn, mesh, wireguard, zero-trust. The package is complete: compose.yaml, backup.yaml, oidc.plug.yaml, postgres.plug.yaml, an init job, an exporter, a socket, and tests.
  • It is wired into the identity plane. apps/standalone/identity-broker/netbird.plug.yaml exists, alongside the plugs for gitlab, immich, mailcow, matrix, midpoint, nextcloud and peertube.
  • NetBird ships first-party iOS and Android clients, from the App Store and Play Store.

Therefore: reachability is solved by an app the user installs from the store, and SHC should not build or embed a VPN client. Not “should defer”, should not. Shipping a WireGuard client would mean a NEPacketTunnelProvider network extension on iOS and a VpnService on Android, a second key custody problem, a second set of store review questions, and a permanent maintenance obligation to duplicate a flagship app that is already packaged, already brokered into Keycloak, and already has better clients than we would write.

One honesty note on the wiring, since the app doc says so itself: netbird/app.yaml records that “NetBird has no CLI/API for bootstrapping a PAT. The first admin must log into the dashboard UI (via Keycloak) and create a PAT manually”. So first-run NetBird is not push-button today. That is a NetBird packaging gap worth closing on its own merits; it is not a mobile gap and it does not change this recommendation.

What the console app should do about VPN (recommendation): detect that the active connection is unreachable, and deep-link to NetBird (install it, or open it) with a plain explanation. A handoff, not a tunnel.

6.3 The operational wrinkle: one line, as asked

Section titled “6.3 The operational wrinkle: one line, as asked”

iOS permits only one active VPN configuration at a time. Verified: only one NEPacketTunnelProvider (enterprise VPN) may run on the system at once, and where an enterprise VPN and a Personal VPN are both configured the enterprise one takes route precedence. A user already on a corporate VPN will conflict with NetBird. That is a NetBird and user-education matter. It is not a reason to build anything, and specifically it is not an argument for embedding our own client; an embedded client would hit the identical limit.

With reachability carried by NetBird, and with web push working on iOS since 16.4 for Home-Screen-installed web apps (verified: Web Push on iOS is available only to Home Screen web apps, an open Safari tab has no PushManager, and requires a manifest plus a user-gesture permission request; iOS 16 or newer is now the overwhelming majority of the installed base), notifications are not a native-only need either.

The only remaining native-only capability is the Android <activity-alias> launcher integration. One platform. An enhancement, not a foundation.

The owner asked that the proposal follow the argument rather than protect the earlier framing. It follows.


7. PWA-first: evaluated as the likely answer, and adopted (recommendation)

Section titled “7. PWA-first: evaluated as the likely answer, and adopted (recommendation)”

The reasons compound, and several are specific to this repo rather than general PWA advocacy:

  1. It is already served from the estate, on a domain the user trusts. Console-architecture §2 ruled “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”. A manifest and a service worker are additive bytes on a vehicle that is already ruled and already owed. The PWA is close to free.
  2. ★ The Keycloak session already lives there. This is the decisive one. §4’s entire problem, an isolated cookie jar, does not exist for a PWA, because there is no native shell to have a jar. An installed PWA on Android runs in the browser’s own storage; the Custom-Tab-vs-WebView question stops being a question because there is nothing to embed.
  3. Installable on both platforms, from Chrome and from Safari’s Add to Home Screen, with no store account, no review, no signing identity, no release channel.
  4. One codebase, and apps/console is already a web build with routes and screens written.
  5. It ships with the estate. Version skew between app and daemon, normally the hardest problem in a management client, disappears, because the console bytes and the daemon are one release. A store-distributed native app must support every daemon version its users are running, forever. This is a large, permanent, easily-underestimated cost that PWA-first simply does not incur.

What a PWA gives up:

  • The alias icons. Fully. There is no web API that places drawer icons. This is the entire native-only surface, and it is real.
  • Anything needing a background service the OS will not run. No periodic background reconcile, no long-lived socket. Partially mitigated: a service worker runs on push delivery, so a push-triggered reconcile is possible on Android, but nothing runs on a schedule, and iOS is stricter still.
  • A wrinkle needing measurement before it is promised: on iOS, a Home Screen web app has its own storage container rather than sharing Safari’s, and links opened out of it land in Safari with a different session. So the iOS PWA console likely costs one Keycloak login at install and then persists, acceptable, and still one login rather than one per app, but the interaction between the installed console’s session and Safari’s session must be measured on a device, not assumed. Combined with §4.4(b)‘s non-persistent SSO cookie default, this is the top of the measurement list.

7.2 What still justifies a thin native Android app?

Section titled “7.2 What still justifies a thin native Android app?”

The honest answer is: one thing, and it is not yet enough on its own.

  • The <activity-alias> drawer integration. That is the list.

And there is a verified argument against shipping a thin native shell to a store. App Store Review Guideline 4.2 (Minimum Functionality), verbatim:

Your app should include features, content, and UI that elevate it beyond a repackaged website. If your app is not particularly useful, unique, or “app-like,” it doesn’t belong on the App Store.

A native console whose substance is “open a Custom Tab at the estate’s console URL” is a repackaged website by construction. 4.2 is a far more likely rejection ground than 4.7 (§9), and it is one the architecture invites by design, since §4 rules that rendering is delegated. A native app only clears 4.2 once the alias reconcile, notifications, and connection management are real and visible, which is to say, the native app must earn its way past review by being the things a browser cannot do, and until it is, it should not be submitted.

★ And then the sharpest fact in the whole analysis:

The one native-only capability exists on the one platform that does not require a store.

Android permits sideloading, F-Droid, and self-hosted APKs. The estate can serve its own APK. So the alias feature can ship with zero store review, zero store presence, zero 4.2 exposure and zero IAP exposure to precisely the audience most likely to want it, who are by construction people who self-host their own infrastructure and are unbothered by “Install unknown apps”.

  1. PWA-first for the console, both platforms. Manifest, service worker, install affordance, web push. Ships with the daemon per console-architecture §2. This is the product.
  2. An optional Android APK, distributed off-store from the estate (and optionally F-Droid), for users who want drawer icons. It is the same apps/console codebase through the native lane that already exists. It is an enhancement layer over the PWA, and it must not become a fork.
  3. No iOS native app. Nothing yet justifies it, and this document declines to manufacture a justification. Revisit only if iOS ships an API that makes per-app icons possible, or if a capability appears that web push and NetBird do not cover.
  4. No Play Store or App Store presence for the console at v1. Revisit when there is a reason that is not “apps live in stores”.

Per §7. Gains: one codebase, no review, no store presence to maintain, ships with the estate, same-origin with the Keycloak session. Gives up: alias icons and OS-scheduled background work.

8.2 Portal: no. The owner guessed correctly, and here is the reason

Section titled “8.2 Portal: no. The owner guessed correctly, and here is the reason”

Not a preference: the reasons the console’s case is strong are each absent for the portal:

Console’s reasonPortal
solves a reachability problem (exposure: lan)none: my.selfhostedcloud.org is on the public internet, run by us, always reachable
ships with the estate, so no version skewnothing to ship with: it is a Frappe bench we operate and deploy continuously
installability is genuinely usefulinstall prompts on an admin console are noise. People reach an admin console from a desktop browser with tabs and bookmarks
same-origin with a session that already existsour own IdP on our own domain; a browser already handles this perfectly

Its one native-shaped need is push for approval requests. That comes straight out of the request-and-approve ruling, ../decisions/2026-08-16-portal-cluster-identity.md §2:

RULED: request-and-approve is the default.

with §2.1 routing the request across two populations: a cluster tenant user requests, a portal account approves. An approval that waits is a purchase that does not happen, so notifying the approver promptly is a genuine product requirement rather than a nice-to-have.

Web push already covers it, on desktop unconditionally and on iOS since 16.4 for Home-Screen-installed web apps. And email covers the rest.

Conclusion, with the one nuance that keeps it honest (recommendation):

The portal is not a PWA product and should not be a mobile app. But it should ship a web app manifest and a service worker, purely so that an approver who wants push on an iPhone can install it and get push, since on iOS that is the only path to PushManager.

Ship the capability; do not promote the install. No beforeinstallprompt banner, no “get the app” interstitial, no store listing, no portal app. An approver who wants a push-capable icon can add one; nobody is asked to.

8.3 ★ THE PLATFORM MATRIX (decided, 2026-08-16)

Section titled “8.3 ★ THE PLATFORM MATRIX (decided, 2026-08-16)”

This is a capability matrix, and it is decided. It says what each target can reach, not what ships; shipping is §7.3 (a recommendation) and, for desktop, a release decision nobody has taken yet. Read a cell as “is this objective reachable on this platform at all”, because the whole reason to write it down is that two of the answers are platform floors that no amount of engineering moves.

objectiveAndroid nativeiOS nativePWADesktop
management surface (stacks, health, events, install/deploy/restore)yesyesyesyes
notificationsyesyesyes (web push; iOS needs Home-Screen install)yes
per-app iconsyes: drawer, silentNO, hard platform limitnoyes, and better, see below
home-screen / desktop placementone confirmation tap eachmanual, per app, by the usermanualyes, fully dynamic, no dialog
auth without a platform-isolation spikeCustom Tabs (§4.2)ASWebAuthenticationSessionn/a; the browser is the session (§7.1)yes, no spike needed
store presence availableyesyesnon/a
background re-warmlimitedvery limitednoyes

Android native reaches every objective, with one asterisk that is a platform floor, not a gap:

  • Aliases populate the DRAWER silently. setComponentEnabledSetting() on the app’s own components needs no permission and shows the user nothing (§3.1). This is the mechanism the whole feature rests on.
  • The HOME SCREEN still needs one confirmation tap each. requestPinShortcut() raises a system dialog, per shortcut, that cannot be suppressed, and the silent INSTALL_SHORTCUT broadcast is gone on API 26 / Android 8 and above (§3.2). This is a platform floor since Android 8. It is not an SHC limitation, a permissions gap, or something a launcher partnership unlocks. Nobody may promise silent home-screen population in a demo or a roadmap.

iOS native reaches everything EXCEPT per-app icons, and that exception is a hard platform limit with no API (§5). There is no <activity-alias> equivalent; setAlternateIconName swaps the app’s own icon and is one icon, not many. The only per-app story is the user doing Share → Add to Home Screen by hand, whose quality is decided by third-party upstreams’ manifests, Nextcloud’s, GitLab’s, Immich’s, which SHC does not control. Everything else on the list ports: management surface, notifications, connection management, the NetBird handoff.

PWA gets launcher + marketplace on both platforms, and the honest limits are three:

  • Auth is plausible on Android and doubtful on iOS, pending the spike. On Android the installed PWA runs in the browser’s own storage, so §4’s cookie-jar problem does not exist. On iOS a Home Screen web app has its own storage container rather than sharing Safari’s, and links opened out of it land in Safari with a different session. This must be measured on a device, not assumed (§7.1, owed work item 6).
  • No store presence. By construction, which §7.3 counts as a feature.
  • No background re-warm. Nothing runs on a schedule; a service worker runs on push delivery, and iOS is stricter still.

★ DESKTOP reaches everything, and does two things BETTER than Android. This is the part of the matrix that was not obvious and is the reason it is worth writing down:

  1. .desktop files and Start Menu shortcuts are fully dynamic. There is no build-time set, no manifest to declare aliases in, no APK to rebuild when the catalog changes, and no confirmation dialog. Writing a .desktop file into ~/.local/share/applications/ or a shortcut into the Start Menu is a file write. So the constraint that shapes the entire Android design, §3.4’s “icons bake in at build time; a catalog icon change requires an app release”, and the cap on the alias set, simply does not exist on desktop, and neither does §3.2’s per-icon prompt. Desktop gets the silent drawer and the dynamic long tail, which is strictly more than Android manages.
  2. The embedded-webview auth story needs no platform-isolation spike at all. §4.4(a)/(b) and owed work items 5 and 6 exist because mobile makes session sharing between a native shell and the system browser hard. A desktop shell embeds a webview it controls, on a machine whose browser profile the user already owns; there is no App-Bound-Domains equivalent and no Custom-Tabs-vs-WebView question to lose.

★ And desktop is a RELEASE decision, not a build decision: the lanes already exist. §0.1 found them in-tree today: Tauri (src-tauri/, tauri:build) and GNOME (vite.config.gnome.ts, gjs), both under apps/console, both CI-typechecked, all sitting under console-architecture §8’s “web is the only released target”. So the question for desktop is the same one §0.2 poses for mobile, promotion from insurance to product, and the marginal cost is lower than mobile’s, because desktop needs neither of the two spikes mobile needs.

macOS is the awkward case. The .desktop-file property above is Linux; Windows Start Menu shortcuts are the close equivalent. macOS has no clean dynamic equivalent for per-app icons: the Dock and Launchpad are populated from .app bundles, so a per-app icon means generating bundles, which brings code-signing, notarization and Gatekeeper into a feature that is a file write everywhere else. Treat macOS as reaching everything except the per-app icon story, alongside iOS, and do not let it hold the Linux and Windows lanes hostage; that is the §5 error repeated one platform over.

The two rows to quote when someone asks why the feature is uneven: silent home-screen population is impossible on every platform we would ship for except desktop; per-app icons are impossible on iOS and macOS and cheap everywhere else. Both are platform design.


9. App Store posture: argued, not asserted

Section titled “9. App Store posture: argued, not asserted”

Recorded because the owner raised it. Every guideline below was read from the current App Review Guidelines rather than recalled, and one of the owner’s premises needs correcting.

9.1 Guideline 4.7: ★ the premise needs correcting, the conclusion survives

Section titled “9.1 Guideline 4.7: ★ the premise needs correcting, the conclusion survives”

The owner referred to 4.7 as the “your own app store” rule. Today’s 4.7 is titled “Mini apps, Mini Games, Streaming Games, Chatbots, Plug-ins, and Game Emulators”, and it is a permissive section, not a prohibition:

Apps may offer certain software that is not embedded in the binary, specifically HTML5 and JavaScript mini apps and mini games, streaming games, chatbots, and plug-ins. […] You are responsible for all such software offered in your app, including ensuring that such software complies with these Guidelines and all applicable laws.

The argument that it does not apply, which is stronger than the owner’s version because the section is about a different thing entirely:

  1. 4.7 governs software offered in your app: code that executes on the iOS device, inside the app’s process or its embedded runtime. That is why 4.7.2 forbids extending native platform APIs and 4.7.3 governs sharing privacy permissions: the mini app is running on the phone.
  2. An SHC install puts a container on the customer’s own server. Nothing is downloaded to the device, nothing executes on the device, no runtime is embedded, no native API is exposed to third-party code. The device’s role is to send an authenticated instruction to a remote machine the customer owns.
  3. The category is remote-infrastructure management, and it ships on the App Store today at scale: AWS Console, DigitalOcean, Linode, Portainer, Cloudflare. Each lists, provisions and configures third-party software on remote servers. None is treated as an app store.
  4. The console app’s install action is strictly less than those: under ../decisions/2026-08-16-marketplace-identity-and-install.md §5 the store itself is reached by top-level navigation to marketplace.selfhostedcloud.org, not embedded, so the catalog browsing and purchasing surface is a website in a browser, not a surface in the app.

Assessment: 4.7 most likely does not apply. Not certain, no guideline read is, but the argument is on the merits and the precedent class is large.

★ RECORDED AS DECIDED: the “your own app store” framing is STALE and must not be repeated. Not in a plan, not in review notes, not in a conversation with a reviewer. Today’s 4.7 is titled “Mini apps, Mini Games, Streaming Games, Chatbots, Plug-ins, and Game Emulators” and it governs code executing ON THE DEVICE, which is why 4.7.2 forbids extending native platform APIs and 4.7.3 governs sharing privacy permissions. An SHC install puts a container on the customer’s own server; nothing is downloaded to the device, nothing executes on it, no runtime is embedded. Repeating the stale framing does active harm in two directions: it invites a reviewer to evaluate the app against a section that does not fit, and it makes us design defensively against a rule that is not the one we have to clear. The rule we have to clear is 4.2; see §9.6.

9.2 Guideline 4.8: Sign in with Apple. Not triggered, and the exception is explicit

Section titled “9.2 Guideline 4.8: Sign in with Apple. Not triggered, and the exception is explicit”

4.8 attaches to apps that “use a third-party or social login service (such as Facebook Login, Google Sign-In, Log in with X, Sign In with LinkedIn, Login with Amazon, or WeChat Login) to set up or authenticate the user’s primary account”. Its listed exceptions include, verbatim:

  • App exclusively uses company’s own account systems
  • App is education/enterprise requiring institutional account

Both apply. The portal app authenticates against our own IdP, the first exception, precisely. The console app authenticates against the customer’s own Keycloak, in their tenant realm, the second exception, precisely: an institutional account issued by the customer’s own identity system.

It would become mandatory if “Sign in with Google” (or any social IdP) is ever offered as a primary login on either app. Note this is not about a customer configuring Google as a federated IdP inside their own Keycloak; that is their realm configuration, invisible to us and to Apple; it is about our app offering a social login button.

9.3 ★ Guideline 3.1.1: the real commercial risk, and the structural dodge

Section titled “9.3 ★ Guideline 3.1.1: the real commercial risk, and the structural dodge”

Not 4.7. IAP. Verbatim:

If you want to unlock features or functionality within your app […] you must use in-app purchase. Apps may not use their own mechanisms to unlock content or functionality, such as license keys, augmented reality markers, QR codes, cryptocurrencies and cryptocurrency wallets, etc.

The “license keys” clause is the one to notice, because SHC’s entitlement spine is Keygen licences (../decisions/2026-08-16-marketplace-entitlement-and-licensing.md: “ERPNext invoice → broker POST /record → Keygen record”). If the app ever took a licence key and unlocked in-app functionality with it, 3.1.1 would bite directly and by name.

The already-ruled purchase design dodges it structurally. Under portal-cluster-identity §2, purchasing authority is request-and-approve: a request is raised, an approver acts in the portal, and per §4.3 the approver acts in the portal “on a portal object”, which is why purchase approval survives an L2 seal at all. Combined with marketplace-identity §5’s new-tab signed handoff to the store, the result is:

  • Purchases happen on the web, in the portal, through SHC’s own processor (ERPNext Sales Invoice as source of truth; Keygen as entitlement store; processors pluggable underneath; portal-architecture §7 names Hyperswitch as “the likely orchestrator”, which is directional, not ruled, and should not be written down as settled).
  • The app requests and installs what is already entitled. It shows entitlements; it does not sell them.
  • Money never touches the app.

★ Record this as what it is: a consequence, not a workaround. The request-and-approve ruling was made for governance reasons, “turns approval into a real decision instead of a rubber stamp”, months of App Store compliance later than it should be relevant. The IAP-safe posture is what that ruling produces on its own. A design that is compliant by accident of good architecture is far more durable than one engineered around a rule, because there is no in-app purchase flow to re-litigate when the rule moves.

9.4 Why “the apps sell nothing” is defensible, not merely convenient

Section titled “9.4 Why “the apps sell nothing” is defensible, not merely convenient”

RECOMMENDED POSTURE: the apps sell nothing. No prices, no purchase UI, no upgrade button, no “unlock” affordance, no plan comparison.

The argument, in the terms that actually decide it:

Apple requires IAP for digital content and functionality consumed in the app. It does not require IAP for goods and services consumed outside it. An SHC subscription is consumed on infrastructure the customer owns and operates: a Nextcloud running on their hardware, a Keycloak realm holding their users, a Traefik gate enforcing their access policy. The phone is a management client for a service that exists whether or not the phone does. The app is not the product; the estate is.

The precedent is unambiguous and large. AWS, DigitalOcean, Linode, Cloudflare, Salesforce and Shopify all ship management apps for services with substantial recurring fees. None sells its service through IAP. This is not a grey area being probed; it is the settled shape of an entire app category.

An additional structural fact that strengthens it here: the SHC console app often manages an estate the app cannot reach without NetBird (§6) and which continues to operate, bill, serve users and run backups when the phone is switched off. The service’s independence from the app is not an argument; it is an operational property.

9.5 ★ Anti-steering is moving: do not write down numbers

Section titled “9.5 ★ Anti-steering is moving: do not write down numbers”

Rules on linking out to external purchase have changed materially and repeatedly (the Epic injunction, the 2025 US ruling, the EU DMA regime) and now differ by jurisdiction within the same guideline. This is directly visible in the current text, which carves the US storefront out by name:

These entitlements are not required for developers to include buttons, external links, or other calls to action in their United States storefront apps.

In all other storefronts, except for the United States storefront, where this prohibition does not apply, apps and their metadata may not include buttons, external links, or other calls to action that direct customers to purchasing mechanisms other than in-app purchase.

Therefore:

  • Do not state commission percentages or link-out permissions as settled fact anywhere: not in this doc, not in a plan, not in marketing.
  • The shape is: US storefront currently permissive on link-outs; other storefronts restrictive with entitlement carve-outs; EU governed separately under the DMA.
  • Re-check at build time, from the primary source, per storefront. Treat today’s reading as perishable.
  • ★ And notice why the posture was chosen: “the apps sell nothing” does not depend on how this area settles. An app with no purchase UI and no external purchase links is unaffected by every one of these movements in either direction. That robustness is a feature of the choice, and it is worth more than the marginal conversion a link-out would buy.

9.6 ★ THE APP REVIEW STRATEGY (decided, 2026-08-16): what we submit, and the gate that sinks submissions

Section titled “9.6 ★ THE APP REVIEW STRATEGY (decided, 2026-08-16): what we submit, and the gate that sinks submissions”

This governs if and when a native app is submitted. It does not overturn §7.3, which recommends PWA-first with no store presence at v1; it says that should a submission happen, this is the posture, and it changes what the build has to contain, so it is not deferrable to submission day.

9.6.1 Submit an ESTATE MONITORING AND OPERATIONS CLIENT that also launches apps, not a launcher

Section titled “9.6.1 Submit an ESTATE MONITORING AND OPERATIONS CLIENT that also launches apps, not a launcher”

The framing is the strategy. A “launcher” is, in App Review’s vocabulary, a thing that opens other things, which is a bookmark folder with an icon, and 4.2 Minimum Functionality exists to reject exactly that:

Your app should include features, content, and UI that elevate it beyond a repackaged website. If your app is not particularly useful, unique, or “app-like,” it doesn’t belong on the App Store.

★ 4.2 is the real risk, not 4.7 (§9.1), not 4.8 (§9.2), and not 3.1.1, which the purchase design already dodges structurally (§9.3). §7.2 already named it: a native shell whose substance is “open a Custom Tab at the estate’s console URL” is a repackaged website by construction.

★ And here is the counterintuitive consequence that must not be got backwards: THINNESS is what trips 4.2, so STRIPPING FEATURES TO REDUCE REVIEW SURFACE MAKES REJECTION MORE LIKELY, NOT LESS. The instinct to submit a minimal build “to get through review” is precisely inverted. There is no minimum-surface strategy for 4.2; there is only a substance strategy. The app must earn its way past review by being the things a browser cannot do.

9.6.2 The native capabilities that carry it, most legible to a reviewer first

Section titled “9.6.2 The native capabilities that carry it, most legible to a reviewer first”

Ordered by how immediately a reviewer sees native capability, not by build cost. A reviewer spends minutes, and the first three do the work:

  1. Live Activities on long installs and backups. A Dynamic Island / Lock Screen surface updating during a multi-minute operation is unmistakably native, is impossible on the web, and maps onto a real thing the product does; installs and backups genuinely take minutes.
  2. Home Screen widgets for estate health. Visible without opening the app; no web equivalent exists on iOS.
  3. Local Network discovery. Finding an estate on the LAN is real utility given exposure: lan is the default (§6.1), and its permission prompt is itself proof of native capability: a web page cannot ask for it, so the reviewer sees the system dialog and the question of “is this a website” is answered by the OS.
  4. Actionable push: approve/deny a purchase request, acknowledge an alert, from the notification.
  5. Face ID / Touch ID and Keychain for connection credentials.
  6. App Intents: Siri and Shortcuts integration for common operations.
  7. A Files provider extension, surfacing estate storage in the Files app.

Each is a genuine capability, not a compliance ornament, which is what makes the list defensible: a design that is compliant by accident of good architecture is far more durable than one engineered around a rule (§9.3).

9.6.3 ★ THE PRACTICAL GATE THAT SINKS SUBMISSIONS: a WORKING DEMO ACCOUNT

Section titled “9.6.3 ★ THE PRACTICAL GATE THAT SINKS SUBMISSIONS: a WORKING DEMO ACCOUNT”

Record this as OWED BUILD WORK, not as a policy note. It is the most common cause of rejection for apps in this category, it has nothing to do with guideline interpretation, and it cannot be produced in the hour before submission.

App Review needs credentials that work. A reviewer in a different country, on an unknown network, with no estate of their own, must be able to sign in and see the app do something. An SHC console app with no cluster to connect to is a login screen, which is a 4.2 rejection and a “we could not review your app” rejection at once.

What is owed, concretely:

  • A real, seeded, publicly reachable demo cluster. Not a mock, not a screenshot mode, not a fixture bundle: a live estate with stacks installed, health history, events, an app list and a backup or two, so the reviewer sees a populated product rather than an empty one.
  • Publicly reachable, which for this product is the hard part: the default is exposure: lan (§6.1), and the NetBird handoff (§6.2) is not something a reviewer will do. The demo cluster must be reachable without a VPN, which makes it a deliberately-exposed estate and therefore its own small security design: a scoped tenant, throttled, nothing real behind it, rotated credentials.
  • Credentials in the review notes, in the App Store Connect demo-account fields, and kept working across every resubmission. A demo account that has expired between builds is a rejection.
  • A reviewer path that does not require Local Network permission, since a reviewer on cellular cannot use it; the capability is a strength (§9.6.2), but it must not be the only way in.

This is build work with an owner and a schedule, and it belongs in §11.


10. ★ The tier tension: the owner’s premise does not match the repo. NEEDS OWNER RULING

Section titled “10. ★ The tier tension: the owner’s premise does not match the repo. NEEDS OWNER RULING”

10.0 ★★ A RULING WAS MADE ON A WRONG PREMISE, AND IT NEEDS RE-DECIDING: OWNER INPUT NEEDED

Section titled “10.0 ★★ A RULING WAS MADE ON A WRONG PREMISE, AND IT NEEDS RE-DECIDING: OWNER INPUT NEEDED”

Read this before anything else in §10, and do not implement past it.

Later on 2026-08-16 the owner ruled that the console is gated to Hobby. That ruling is not recorded here as settled, and this document deliberately does not resolve it, because the premise he was given was wrong.

What he was told: that the console and the marketplace were “born paid”, features added alongside the free tier rather than carved out of it, so gating the console to Hobby was a clean addition that took nothing away.

That was wrong for the console. It may hold for the marketplace; it does not hold for the console, and §10.2 below is the evidence, read out of the tree:

  • TIERS.md’s free tier includes “the full single-node experience”, alongside “full app catalog + install / deploy / update / restore / recover” and “the full CLI is visible”. The console is not named as an exclusion anywhere in TIERS.md; it is not mentioned in TIERS.md at all.
  • 2026-08-14-console-architecture.md §3 says the opposite of born-paid, explicitly: “Every realm user may sign in; operator screens gate on the RBAC role matrix.”
  • TIERS.md’s Hobby section names what paid adds, and it is three things: named environments, the support bundle, the MCP server, under the sentence “Those three are the whole of what every paid tier adds over free.” The console is not among them.

Therefore moving the console to Hobby TAKES SOMETHING AWAY FROM FREE. It is a carve-out, not an addition. The owner decided it believing it was additive. That is a different decision from the one he made.

★ What has changed since, and what has not. TIERS.md dropped the no-rug placement promise earlier the same day (dd35fac98, “drop the no-rug promise, keep the placement heuristic”); the section now reads “This section describes how we currently place features. It is not a commitment about future placement, and it is deliberately not written as one.” So nothing forbids the carve-out any more; the objection that this document originally raised (§10.2’s closing paragraph, now amended) is gone. The objection that remains is narrower and harder: the decision was made on a false description of what it cost. Removing a prohibition does not convert a carve-out into an addition.

(Note for whoever touches TIERS.md next, not this lane’s to fix: the Environments section still says moving the line “after someone depends on it is exactly the rug-pull the promise above forbids”, a dangling reference to the promise that was deleted above it.)

10.0.1 ★ THE ALTERNATIVE THAT NEEDS NO CARVE-OUT: it may already be his intent

Section titled “10.0.1 ★ THE ALTERNATIVE THAT NEEDS NO CARVE-OUT: it may already be his intent”

Before re-deciding, notice that the outcome he wants may already exist.

What is already gated Hobby-and-up, ruled and written down, is the launcher menu and app-SSO: 2026-08-14-console-architecture.md §3:

Free tier (permanent): no launcher menu and no SSO into apps. The traefik launcher/menu overlay and app-SSO are paid (Hobby+) features.

And that is precisely the feature the mobile app exists to deliver. §10.3 works it through: the Android drawer aliases are the launcher menu rendered into another surface, and app-SSO is what makes tapping one land you logged in rather than at a login form. The one native-only capability in the entire proposal (§6.4) is therefore already behind Hobby without a single new ruling.

So there are two shapes, and only the owner can say which he meant:

“console gated to Hobby""console free, launcher paid”
what free losesthe whole management surface: stacks, health, events, app list, install/deploy/restorenothing it has today
relationship to TIERS.mda carve-out requiring an edit to the declared free tieralready consistent; no edit
relationship to console-architecture §3contradicts “every realm user may sign in”already what §3 says
new rulings neededyes: TIERS.md and console-architecture §3 both changenone
App Store 4.2 exposure (§10.3)a free download that does nothing = an empty paywallapp is free and useful; the icons are the paid part
paid feature the mobile app deliversconsole accessdrawer icons + app-SSO, the thing the app is for

If “console free, launcher paid” is what he meant, it is already satisfied and there is nothing to do. If he means the console itself, that is a TIERS.md edit and a console-architecture §3 edit, and it should be made on the corrected premise, knowingly, as a carve-out, rather than inherited from a briefing error.

This is flagged, not resolved. §12 Q5 carries it as the open question.

The rest of §10 is the original tension, retained, and it is the evidence §10.0 rests on. The owner raised this as a real review risk, and he is right that the risk shape matters. But the premise is contradicted by two documents, and correcting it makes the problem smaller and sharper rather than bigger.

The console is a Hobby (paid) feature and free tier does not get it. So a free-tier user who downloads the console app can do nothing.

TIERS.md, free tier: it is a long list, and it includes:

  • Full app catalog + install / deploy / update / restore / recover.
  • The full CLI is visible; paid commands tell you what tier unlocks them.
  • The CLI, health, and the full single-node experience.

TIERS.md, Hobby tier, and this sentence is decisive:

Those three are the whole of what every paid tier adds over free; Pro and Enterprise carry all of them too, unchanged.

The three are: named environments, the support bundle, and the MCP server. The console is not among them, and is not mentioned in TIERS.md at all.

Console-architecture §3 goes the other way explicitly:

Auth: per-estate confidential Keycloak client, role-gated screens. Every realm user may sign in; operator screens gate on the RBAC role matrix.

And its entitlement section names what is paid, precisely, and it is not the console:

Free tier (permanent): no launcher menu and no SSO into apps. The traefik launcher/menu overlay and app-SSO are paid (Hobby+) features.

So: the launcher menu and app-SSO are Hobby+. The console is not.

★ AMENDED: the promise that was in the way has been removed. This paragraph originally read: “There is also a promise in the way. TIERS.md records that the free tier was declared ‘before the first sale, deliberately’, with a no-rug commitment … exactly the move that section exists to prevent.”

That is no longer true. TIERS.md dropped the no-rug placement promise on 2026-08-16 (dd35fac98), and now says placement “is not a commitment about future placement, and it is deliberately not written as one”. The no-rug/no-brick language that survives is about the licensing runtime, soft-degrade, nothing stops, no data lost, and TIERS.md marks it “not to be confused” with feature placement.

So nothing prohibits moving the console behind Hobby. What remains is not a prohibition but a fact about cost: it is still a carve-out from the declared free tier, not an addition to it, because TIERS.md’s free tier says “the full single-node experience” and console-architecture §3 says “every realm user may sign in”. §10.0 is where that lands.

10.3 Why the corrected line is better for the App Store problem too

Section titled “10.3 Why the corrected line is better for the App Store problem too”

The minimum-functionality risk the owner feared largely evaporates, and what remains lands in a cleaner place:

  • A free-tier user’s console works. Stacks, health, events, the app list, install/deploy/update/restore. That is substantial, functional, and free, so there is no empty paywall to reject under 4.2, and the app’s content problem (§7.2) is about native substance, not entitlement.
  • What free tier lacks is exactly the launcher menu and app-SSO, which is exactly the Android alias feature. The drawer icons are the launcher menu rendered into another surface, and app-SSO is what makes tapping one land you logged in. So the alias feature is correctly Hobby+ with no new ruling at all, and its entitlement gate is already written down.
  • Which means the tier story reads cleanly to a reviewer and to a user: the app is free and useful; the icons are the paid part. That is a normal, defensible freemium shape, and it is what the existing rulings already produce.

Do not move the console to Hobby. Keep TIERS.md’s free tier as declared; keep console-architecture §3’s “every realm user may sign in”; gate the launcher menu, app-SSO, and therefore the Android drawer icons at Hobby+, which is already ruled.

Recorded as an owner question (§12 Q5) because the owner stated the opposite, and because if he intends to move the console behind Hobby that is a change to TIERS.md and to console-architecture §3, not a mobile decision.

★ AMENDED: status upgraded, recommendation unchanged. This is no longer a recommendation against a hypothetical: the owner has since ruled that the console is gated to Hobby, on the premise that it was “born paid” and therefore additive. §10.0 records why that premise is wrong and why the ruling needs re-deciding. This section’s recommendation stands as written, and it is now the alternative to a live ruling rather than advice on an open question. The clause about “the no-rug promise” above is stale; TIERS.md dropped it the same day (§10.2). Nothing forbids the carve-out; it is simply still a carve-out.


  1. Kill or claim the marketplace native lane. apps/marketplace/app.config.js declares iOS and Android with template residue identifiers (com.marketplace.app) that console-architecture §1 already ruled must never ship. Delete the lane (recommended) or rebrand it. Not both, not neither.
  2. PWA on the console: web app manifest, service worker, install affordance, web push. Rides console-architecture §2’s daemon-served SPA (owed work item 2 there), which is the prerequisite; today nothing serves console bytes on any estate, confirmed: no Go code embeds or serves the console SPA.
  3. PWA capability on the portal: manifest + service worker + web push for approval requests. No install promotion. (§8.2)
  4. Native public Keycloak client for the console app: PKCE, exact redirect URIs on the shc-console:// scheme or an App Link, never a wildcard; distinct from the launcher’s confidential client. (§4.4a)
  5. Measure and fix Keycloak SSO session persistence for mobile browsers: KEYCLOAK_IDENTITY / AUTH_SESSION_ID non-persistence, SSO Session Idle/Max, Remember Me. Blocks the drawer-icon feature from feeling like SSO, and benefits the PWA identically. (§4.4b)
  6. Measure the iOS Home Screen web app session boundary: whether the installed console shares Safari’s Keycloak session, and what happens to links opened out of it. (§7.1)
  7. Alias reconcile loop (Android APK lane): desired/actual set difference against the deployment list, idempotent, run on foreground / connection switch / push; per-app user opt-out inside desired, not after it. (§3.5)
  8. Cluster qualifier on launcher labels for the multi-connection case: client-side only, not in the launcher payload (10,250-byte ceiling, ruled). (§2.2)
  9. NetBird handoff: unreachability detection on a connection, deep-link to install/open NetBird. No VPN client, no network extension. (§6.2)
  10. Android OEM device matrix for setComponentEnabledSetting refresh behaviour, plus non-promising UI copy and a self-serve recovery path. (§3.4.3)
  11. Off-store Android distribution: signing identity, APK hosting from the estate, update channel, optional F-Droid. (§7.3)
  12. ★ A REAL, SEEDED, PUBLICLY REACHABLE DEMO CLUSTER: a live estate with stacks, health history, events and backups, reachable without a VPN (so: a deliberately-exposed, scoped, throttled tenant with rotated credentials), plus the credentials in App Store Connect’s demo-account fields and kept working across resubmissions. This is build work, not a policy note, and it gates any store submission on either platform. (§9.6.3)
  13. The 4.2 substance set, if a store submission is ever intended: Live Activities on long installs/backups, Home Screen health widgets, Local Network discovery, actionable push, Face ID/Keychain, App Intents, a Files provider extension. Named as owed because stripping features to reduce review surface makes rejection more likely, not less (§9.6.1), so this is an entry condition rather than a follow-up. (§9.6.2)
  14. A desktop release decision: the Tauri, GNOME and VS Code lanes exist and are CI-typechecked today (§0.1). Desktop reaches every objective in the matrix and needs neither of the two spikes mobile needs (owed items 5 and 6), because .desktop files and Start Menu shortcuts are fully dynamic with no build-time set and no confirmation dialog, and an embedded webview on the user’s own machine has no platform-isolation problem. macOS is the exception on per-app icons. Promotion, not construction. (§8.3)

Q1: Build stack: native, cross-platform, or PWA-first? This document recommends PWA-first for both platforms, plus an optional off-store Android APK from the existing apps/console native lane (§7.3). That is a recommendation and not a ruling. Note the premise correction in §0: the cross-platform lane already exists and is CI-typechecked, so the real question is promotion, not selection.

Q2: Does the console app ship before the portal app? Unresolved. The repo makes the console strictly cheaper: it has native lanes, routes and screens today; the portal is a Frappe bench with nothing (§1.3). But console-architecture §8 says “revisit promotion after the Portal ships”, i.e. the standing ruling sequences it the other way. These two facts point in opposite directions and only the owner can break the tie. If §8’s ordering stands, note it does not block the PWA console, which is a web change and sits inside owed work item 2.

Q3: Who maintains two app-store presences? Unresolved, and this document’s answer to Q1 is partly an attempt to make the question unnecessary: PWA-first plus off-store Android requires zero store presences. If the owner wants store distribution anyway, the standing cost is two developer accounts, two review queues, two signing-identity custody problems, expedited-review capability for security fixes, and a permanent obligation to support every daemon version in the field, for a two-person team. Name the owner before committing, not after the first rejection.

Q4: ★ Does the native console get a connection list, overriding console-architecture §7? §7 rules “strictly single-cluster, in both web and native… no connection switcher anywhere in the console”. Today’s ruling requires the opposite. §2.1 proposes a narrowing (web unchanged; native gets an address book; one active connection; no aggregate views ever). This edits a ruled item and needs an explicit yes or no.

Q5: ★★ Is the console a Hobby feature?, RE-OPENED. OWNER INPUT NEEDED. The owner has since RULED yes, but on a premise that was wrong. He was told the console was “born paid” and that gating it to Hobby was therefore a clean addition. It is not: TIERS.md’s free tier says “the full single-node experience” and console-architecture §3 says “every realm user may sign in”, so moving the console to Hobby takes something away from free. The no-rug placement promise was dropped from TIERS.md the same day (dd35fac98), so nothing forbids the carve-out, but it is still a carve-out, and the decision was made believing it was additive.

★ And the alternative may already be his intent, satisfied, with no carve-out at all: what is already gated Hobby-and-up is the launcher menu and app-SSO (console-architecture §3), precisely the feature the mobile app exists to deliver, since the drawer aliases are the launcher menu in another surface and app-SSO is what makes tapping one land you logged in. So “console free, launcher paid” needs no new ruling, keeps free tier as declared, and gives a cleaner 4.2 story (the app is free and useful; the icons are the paid part).

Do not implement either shape until the owner re-decides on the corrected premise. Full statement of both options: §10.0 and §10.0.1.

Q6: Is the marketplace a third native surface? apps/marketplace/app.config.js declares iOS and Android with template identifiers nobody has ruled on. Recommendation: delete the lane (§1.3).

Q7: When may an Android APK be submitted to Play, if ever? Not at v1 under §7.3. If the answer is “never”, say so, because it removes a whole class of future compliance work, and if it is “eventually”, the 4.2 minimum-functionality bar (§7.2) sets the entry condition: the alias reconcile, notifications and connection management must be real first. ★ Amended: §9.6 now states the entry conditions in full: the substance set (§9.6.2) and the working demo cluster (§9.6.3, owed work 12), which is build work with a lead time and cannot be produced at submission.

Q8: Does the daemon expose an inventory endpoint the reconcile loop can read, or does the app re-derive (tenant, environment, stack) grouping and environment precedence itself? Recommendation: expose it. A second implementation of launcher.md §16 in Kotlin will drift from the ruled one.


13. ★ MEASURED VERDICT: “log in once, tap anything” (spike, 2026-08-16)

Section titled “13. ★ MEASURED VERDICT: “log in once, tap anything” (spike, 2026-08-16)”

Run as a throwaway spike against (a) the live bitspur estate and (b) a local throwaway Keycloak brought up from the estate’s own pinned image, registry.gitlab.com/bitspur/selfhosted-cloud/shc/keycloak@sha256:2c8c0a92bba9a5ecdb7581b7a8e87c867b51a4c22e509f2a002687c0f9195cf9. No product code was written and no estate was changed.

  1. The cross-origin half works, and it is not close. One sign-in, then a second gated host on a different origin, a third on a different registrable domain, an ungated app with its own Keycloak client, and the native app’s own public client all completed silently: no prompt, no consent screen, a code on the first redirect. §13.2.
  2. The persistence half is broken by default, exactly as launcher.go predicted, and now measured end to end. KEYCLOAK_IDENTITY ships with no Max-Age and no Expires. Kill the browser process and the next gated host prompts. §13.3.
  3. Of the two candidate fixes, only one exists. Persistent SSO cookie lifetimes (Remember Me + the Remember-Me lifespans) is measured working. “The app silently re-establishes the browser session from its own refresh token” is not implementable against stock Keycloak; there is no endpoint that trades a token for a browser SSO cookie, and prompt=none with every hint attached still returns login_required. §13.4.

So the product premise survives, conditionally. “Log in once, tap anything, you are in” is true within one cookie jar, and it is a one-line realm setting away from being true across app restarts. It is false the moment the app opens URLs in a jar other than the one it signed in to, which is the one thing this lane could not measure. §13.5.

13.1 The question decomposes into two independent halves

Section titled “13.1 The question decomposes into two independent halves”

This is the most useful thing the spike produced, because it says which half is an SHC question and which half is a platform question:

QuestionOwnerStatus
(a) ServerGiven a Keycloak SSO session in the jar, does Keycloak mint a code for a second, different-origin relying party with no prompt?SHC / Keycloak configSETTLED: YES. §13.2
(b) ClientDoes the platform’s browser surface put both opens in the same jar?iOS / Android platformUNMEASURED. §13.5

A cookie jar is not an analogy for a browser here; for this question it is the browser. Two URLs opened against one jar are two URLs opened in one browser; two jars are two browsers. So (a) is fully measurable off-device, and it was.

13.2 Half (a): SETTLED. Cross-origin silent SSO works

Section titled “13.2 Half (a): SETTLED. Cross-origin silent SSO works”

On the live estate, agents.corp.bitspur.com 302s to auth.corp.bitspur.com/realms/corp/protocol/openid-connect/auth?client_id=shc-forward-auth&code_challenge=…&code_challenge_method=S256, and the same URL with prompt=none and no cookies returns, verbatim:

HTTP/2 302
location: https://agents.corp.bitspur.com/api/auth/oidc/callback?error=login_required&state=…

So the silent leg exists and answers correctly for an unknown caller.

On the throwaway rig, one interactive sign-in at host A, then: same jar, no further credentials:

#What was openedResult
M1first gated host, cold jarPROMPTED (baseline)
M2interactive sign-in at host A302 + code minted
M3second gated host, different origin, same shc-forward-auth clientSILENT
M4ungated app with its own client (gitlab shape), different registrable domainSILENT
M5native app, publicClient: true, exact redirect shc-console://auth/callbackSILENT
M6prompt=none silent check (the launcher’s hidden leg)SILENT

M4 matters more than M3: the estate’s gated hosts share one shc-forward-auth client, so M3 alone could have been client-level session reuse. M4 is a different client on a different registrable domain and it is still silent, which is the property §4.1 claims for the ungated apps (gitlab, huly, affine, nextcloud) and it is now measured rather than argued.

M5 validates §4.4(a) mechanically: a public client with an exact custom-scheme redirect URI completes the code flow in the shared jar and inherits the same session. The native client does not need, and does not get, a wildcard.

Control (two jars): a second, never-signed-in jar asking for the same already-authorised host gets PROMPTED, and prompt=none gets login_required. That is the WebView outcome §4 rules against, reproduced.

13.3 Half (b), second half of the brief: SETTLED, and it is worse than one prompt

Section titled “13.3 Half (b), second half of the brief: SETTLED, and it is worse than one prompt”

The raw Set-Cookie headers Keycloak emits on a successful login, captured verbatim from the rig:

--- rememberMe NOT ticked ---
KEYCLOAK_IDENTITY Version=1;Path=/…/realms/corp/;HttpOnly;SameSite=Lax
KEYCLOAK_SESSION Version=1;Path=/…/realms/corp/;Max-Age=36000;SameSite=Lax
--- rememberMe ticked ---
KEYCLOAK_IDENTITY Version=1;Path=/…/realms/corp/;Max-Age=2592000;HttpOnly;SameSite=Lax
KEYCLOAK_SESSION Version=1;Path=/…/realms/corp/;Max-Age=2592000;SameSite=Lax
KEYCLOAK_REMEMBER_ME Version=1;Path=/…/realms/corp/;Max-Age=31536000;HttpOnly;SameSite=Lax

KEYCLOAK_IDENTITY, the credential, carries no Max-Age and no Expires unless Remember Me is ticked. It is a session cookie. Modelling a browser process death as “drop every cookie with no expiry, keep the rest”:

After the browser process diesRemember Me OFFRemember Me ON
cookies survivingKEYCLOAK_SESSION, KC_AUTH_SESSION_HASHKEYCLOAK_IDENTITY, KEYCLOAK_SESSION, KEYCLOAK_REMEMBER_ME, KC_AUTH_SESSION_HASH
open a gated hostPROMPTEDSILENT
prompt=noneLOGIN_REQUIREDSILENT

Three findings inside that table are worth pulling out because each one is a trap:

  • KEYCLOAK_SESSION survives the restart and is not a credential. It is persistent (Max-Age=36000) and the request still prompts. Anything that probes for “is there a Keycloak cookie?” to decide whether to show a sign-in affordance will read this cookie and be wrong. Only the prompt=none leg answers the question, which is exactly what launcher.go already does.
  • KEYCLOAK_REMEMBER_ME alone does not revive anything. Measured directly: keep KEYCLOAK_REMEMBER_ME (365 days) and KEYCLOAK_SESSION, drop KEYCLOAK_IDENTITY; the next gated host is PROMPTED and prompt=none is LOGIN_REQUIRED. It pre-fills a username; it does not authenticate.
  • Remember Me is a checkbox the user must tick, and it is not pre-ticked. Measured on the live estate login page: rememberMe is enabled on the corp realm (the checkbox renders, so the realm flag is on) and the input carries no checked attribute. So the estate today is in the worst configuration available: the lever exists, and nobody pulls it.

On the live estate, AUTH_SESSION_ID and KC_RESTART were also confirmed non-persistent (Secure;HttpOnly;SameSite=None, no Max-Age), and KC_AUTH_SESSION_HASH carries Max-Age=60.

Section titled “Fix A: persistent SSO cookie lifetimes in Keycloak. RECOMMENDED.”

Measured, with the realm’s Remember-Me lifespans as the only variable:

ssoSessionIdleTimeoutRememberMe / …MaxLifespanRememberMeKEYCLOAK_IDENTITY persistsgated host after restart
0 / 0 (inherit the non-remember values)0.42 days (10 h)SILENT
2592000 / 259200030.00 daysSILENT

Note the first row: turning Remember Me on is necessary but not sufficient. With the Remember-Me lifespans left at 0 the persistent cookie still expires at ssoSessionMaxLifespan, 10 hours by default. “Log in once” then means “log in once a day”. The lifespans have to be raised too, and they are the knob that actually sets the promise.

Costs, stated honestly:

  • A 30-day persistent identity cookie on a phone is a 30-day bearer credential in the browser’s cookie store, replayable by anyone holding the device unlocked. It is the same trade every consumer app makes, and it is a real widening of the window in which a lost phone is an authenticated phone.
  • It is estate configuration, per realm, so it is a knob every operator has to be told about, and a default SHC has to choose. It is not an app change, which means (as §4.4(b) already says) a PWA gets the identical benefit for free. This is not a native-vs-PWA discriminator.
  • It needs a user-visible sign-out that actually ends the session (Keycloak end_session_endpoint), or a shared or family device keeps someone signed in for a month.
  • Remember Me being an unticked checkbox is the remaining gap. The realm flag is on today and does nothing until a human ticks it. Either the login theme pre-ticks it, or the promise stays a coin flip per login.

Fix B: the app re-establishes the browser session from its own refresh token. DOES NOT EXIST.

Section titled “Fix B: the app re-establishes the browser session from its own refresh token. DOES NOT EXIST.”

Measured, and it fails at the first step:

app completes its own public-client code flow in the shared browser -> SILENT
browser process dies -> surviving cookies: KC_AUTH_SESSION_HASH, KEYCLOAK_SESSION
app reopens with prompt=none -> LOGIN_REQUIRED
app reopens with prompt=none + login_hint -> LOGIN_REQUIRED

Stock Keycloak exposes no endpoint that trades a refresh token, offline or otherwise, for a browser SSO cookie. A refresh token buys the app its own access token, in the app’s own memory, where the browser cannot see it. The browser session and the app session are two sessions; the app holding one says nothing about the other. This is the same wall launcher.go already documents from the other side.

What the app can do, and it is worth naming so it is not mistaken for Fix B: on launch, run its own authorization request in the shared browser surface without prompt=none. If the Keycloak session is alive that is silent (measured, M5); if it is dead the user gets one login screen, at launch, where a login screen is expected, instead of a login screen at 3pm when they tap the Nextcloud icon. That relocates the prompt, it does not remove it, and it is worth doing in addition to Fix A, not instead of it.

Recommendation: ship Fix A, plus the launch-time re-auth as belt and braces. Do not put Fix B on a roadmap; it is not a thing.

13.5 ★ The four cells: UNMEASURED. Said plainly, as instructed.

Section titled “13.5 ★ The four cells: UNMEASURED. Said plainly, as instructed.”
native shellhome-screen PWA
iOSUNMEASUREDUNMEASURED
AndroidUNMEASUREDUNMEASURED

Why, exactly:

  • mobile_list_available_devices returns {"devices":[]}: no simulator, emulator or physical device is attached to this machine, and the box is headless linux/amd64 with no adb, no xcrun, no emulator on PATH.
  • The remote cloud device fleet is present but not authenticated (failed to get token from keyring), and reserving from it is a shared, billed resource this lane has no consent to spend. It was not allocated.
  • Independently: the estate cannot host the two-host test today either. A sweep of all 35 *.corp.bitspur.com hosts in Certificate Transparency, with an iOS Safari User-Agent and Accept: text/html, found exactly ONE live forward-auth-gated host: agents.corp.bitspur.com. picker answers 401 and devices 404; dtrack, messenger, openhands and project time out. The prior lane’s “three gated hosts” does not hold as of 2026-08-16 05:55 UTC. A second gated host has to be stood up before the on-device test is even runnable.
  • And there are no credentials for the corp realm in this environment; the cached shc-cli offline token is dead (invalid_grant: Offline user session not found).

A guess here would be worse than a gap, so there is no guess. What follows is the test to run, not a prediction of its result.

The exact procedure, per cell. Two gated hosts on different subdomains are needed; agents.corp.bitspur.com plus one more (§13.5 above; one must be stood up).

  1. Cold start: wipe the app and the browser’s site data.
  2. Open host A from the app. Sign in interactively. Tick Remember Me.
  3. Open host B from the app, the same way the product would. Record: prompt or no prompt.
  4. Force-quit the app and the browser process (Android: adb shell am force-stop on both; iOS: swipe both from the app switcher).
  5. Reopen host B from the app. Record: prompt or no prompt.
  6. Repeat 1–5 with Remember Me unticked; that is the default and therefore the real-world case.

The single highest-value thing that procedure will catch, and the reason step 3 must not be skipped as “obviously fine”: on iOS the app has two browser surfaces with different jars, and the natural implementation puts the login in one and the app-opens in the other. ASWebAuthenticationSession shares Safari’s cookie store, which is why it shows a consent alert. SFSafariViewController has had a per-app data store, isolated from Safari, since iOS 11. Sign in with ASWebAuthenticationSession, then open apps with SFSafariViewController, and the session lands in a jar the app never reads from; every tap prompts, and the product premise fails on iOS while passing on Android. The two-jar control in §13.2 is exactly what that failure looks like. Whether those two surfaces are one jar or two is the thing to measure first, before any other cell.

A home-screen PWA is a third container again (§7.1 already flags this), so the iOS PWA cell is not implied by either native result and has to be run on its own.

13.6 What this means for the product decision

Section titled “13.6 What this means for the product decision”
  • The value proposition is real and the mechanism is sound. Nothing in the estate’s design stands in the way of “sign in once, tap anything”. §13.2 is as strong a result as this question can have off-device.
  • It is gated on one realm setting, not on a build. Remember Me plus raised Remember-Me lifespans, pre-ticked. Until that lands, the honest promise is “sign in once per browser session”, and mobile browser sessions are short and end without the user noticing.
  • None of this argues for native over PWA. Every result above is a property of the cookie jar and the realm, both of which a PWA has too. §7’s PWA-first recommendation is untouched by this spike, and §4.4(b)‘s “prerequisite for both, discriminator for neither” is confirmed.
  • The one thing that could still kill the premise is a client-side jar split and it is an iOS implementation choice, not a platform verdict. §13.5.

  • Identity split: ../decisions/2026-08-16-portal-cluster-identity.md §1.5, §2, §4.1, §4.3: the L2 seal, request-and-approve, and what survives a seal. §1.2 adds the console app to the survives-L2 list.
  • Install and store boundary: ../decisions/2026-08-16-marketplace-identity-and-install.md §4 (no iframe, the cookie-jar precedent §4.2 extends to WebViews) and §5 (the new-tab signed handoff, which keeps the storefront out of the app).
  • Entitlement spine: ../decisions/2026-08-16-marketplace-entitlement-and-licensing.md: ERPNext invoice → broker → Keygen. §9.3 keeps all of it off the device.
  • Console surface: 2026-08-14-console-architecture.md §1 (identifiers), §2 (daemon-served SPA, the PWA vehicle), §3 (every realm user may sign in), §7 (contradicted: Q4), §8 (native lanes are insurance, the premise §0 corrects), and the free-tier entitlement lines (§10).
  • Portal surface: 2026-08-14-portal-architecture.md §7 (ERPNext/Keygen, Hyperswitch likely), §8 (multi-cluster is paid and portal-only), §9 (the portal is Frappe, §1.3, §8.2).
  • Launcher: ../architecture/flows/launcher.md §13 Q4 (category glyphs, no vendor logos, §3.4.1), Q5-overruled (stack-name labels, §2.2), Q7 (the 10,250-byte ceiling), §16 (group key, no cluster component, §2.2).
  • Access model: ../architecture/access-control.md (forward-auth flow; exposure: lan default, orthogonal to access) and traefik/plugin/launcher.go (host-only shc_access_token, the Keycloak SSO session, PKCE S256, non-persistent SSO cookies), §4, §6.1.
  • Tiers: ../../TIERS.md: the declared free tier and the three Hobby additions (§10).