Native release readiness: iOS and Android
Status: open design. The owner ruled that iOS, Android, and the PWA ship, and the store submission work is not done. Supersedes ruling 8 of
2026-08-14-console-architecture.md, which is amended in place rather than left to contradict this page.
This is a promotion of existing lanes, not a rewrite. Nothing here asks
for a new app. apps/console/app.config.js already declares Expo / React
Native for platforms: ["ios", "android"] under
com.selfhostedcloud.console with the shc-console scheme, and
package.json already carries prebuild:ios, prebuild:android, ios and
android scripts. There is no AndroidManifest.xml or ios/ directory in
the tree because one prebuild generates them; their absence is the
design, not a gap.
1. What the app is, and why that is the whole submission strategy
Section titled “1. What the app is, and why that is the whole submission strategy”Submit an estate monitoring and operations client that also launches apps. Not a launcher.
A grid of tiles opening web views is exactly what App Review guideline 4.2
exists to catch, and the trait that trips it is thinness, so stripping
features to look simple makes rejection more likely, not less. The
established, repeatedly-approved category is the enterprise SSO/ops client:
Okta Verify, Microsoft Intune Company Portal, Citrix Workspace, the
DigitalOcean app, Portainer. All of them ship precisely this shape: an
inventory you monitor, operations you run, and app entry points alongside.
The console already is that app: features/console/src/ carries a stacks
list, a stack detail with Overview / Logs / Events / Backups / Config /
Secrets / Permissions / Storage / Management tabs, an apps catalog with real
installs (daemon/installApp.ts), and an events tail. That is the argument;
it needs native capability on top of it, not more screens.
Native capabilities that carry 4.2, most legible to a reviewer first
Section titled “Native capabilities that carry 4.2, most legible to a reviewer first”Ordered by how visible each is to a reviewer who has not logged in. Any three clears 4.2 comfortably. Widgets + Live Activities is the strongest pair, because neither requires the reviewer to authenticate.
| # | Capability | Why it is legible | In reach now? |
|---|---|---|---|
| 1 | Home Screen widgets: estate health, stack up/down counts | Visible on the Home Screen without opening the app; impossible on web | Yes. Needs a WidgetKit extension target + an App Group for the shared snapshot. Sample data renders in the gallery before any login. |
| 2 | Live Activities on long installs and backups: Lock Screen + Dynamic Island | Unambiguously impossible on the web, and the single most persuasive artifact in a review video | Yes, and the data already exists. installOperations.ts is already a subscribable long-running-operation store; a Live Activity is that store rendered to ActivityKit. |
| 3 | Local Network discovery (Bonjour) for on-LAN estates | The NSLocalNetworkUsageDescription prompt is itself proof of native capability, shown at first run | Yes, and it is genuinely useful; self-hosted estates are frequently on the LAN. |
| 4 | Face ID / Keychain unlock for the estate session | Standard for ops clients; one prompt, high legibility | Yes. The token store (packages/apps-menu/src/auth/token.ts) is already the single credential chokepoint. |
| 5 | Actionable push: an install finished, a backup failed, a cert is expiring | Requires a server-side push path from the daemon | Not yet. Needs APNs/FCM plumbing in shcd. Second wave. |
| 6 | App Intents / Shortcuts: “restart the stack”, “how is my estate” | Siri and Spotlight surface it outside the app | Yes, cheap once the daemon client is callable outside React. |
| 7 | Files provider extension over estate storage | Strong, but the largest build | No. Third wave. |
Recommended submission set: 1, 2, 3, 4, 6. Five capabilities, none of which requires new daemon work, and two of which (1 and 2) a reviewer sees without credentials.
2. The gate that sinks more submissions than the guidelines do
Section titled “2. The gate that sinks more submissions than the guidelines do”App Review has no SHC estate. An app that opens to a login form pointed at a server the reviewer cannot reach is rejected under minimum functionality, and Apple explicitly requires a working demo account for anything behind a login. This is a hard prerequisite, not a nice-to-have, and it is the single most likely cause of a first-submission rejection.
Concretely, and this needs an owner decision on each line:
- Which estate. A dedicated public demo estate is the right answer, not a
tenant on
bitspurorpromanager; a reviewer poking at production ops controls is not a risk worth carrying. Proposed: a small dedicated node with its own hostname (demo.selfhostedcloud.org) reachable without a VPN. - Which tenant. One tenant, seeded, entitled at the tier the app requires; see §3. The demo account must be a real Keycloak user in that realm, not a bypass, or the login path being reviewed is not the shipped login path.
- What data. Enough that every tab has content: several installed stacks in mixed states (running / stopped / one deliberately unhealthy), backup history with at least one completed and one failed run, an event log with recent entries, and one long-running operation reachable on demand so the reviewer can see the Live Activity fire.
- How it stays alive. This is the part that rots. The demo estate needs a scheduled reseed (nightly reset to a known snapshot) and a monitor that pages if it is down, because a demo cluster that is unreachable during a re-review costs a full review cycle. Treat it as production.
- Credentials in the review notes, on every submission, for both stores.
3. The tier problem: the same trip wire from the other side
Section titled “3. The tier problem: the same trip wire from the other side”The owner ruled that the console requires Hobby (paid). So a free-tier user who downloads the app can do nothing, and “nothing” is minimum functionality again, arriving from a second direction. Two first-run states need designing, and both are currently undefined:
- No cluster at all (fresh install, nobody signed in). Must not be an empty login form. Should be: what SHC is, the Bonjour “find an estate on this network” affordance (capability 3; it does real work with no account), a manual “connect to an estate” entry, and a link out to the Portal on the web to create one. Read-only value before any credential.
- Free tier, signed in. Must show something true and useful rather than a wall. Proposal: keep read-only monitoring (stacks list, status, logs, events) available on Free, and gate the operations (install, restart, secrets, backups) behind Hobby with an explanation and no purchase affordance (§4). This also makes the app defensible: a monitoring client that monitors is not thin, whatever tier you are on. This is a product decision the owner must confirm, because it moves a line ruling 8’s entitlement section drew elsewhere.
The directional “Hobby free for the first 3 months” note in the console architecture doc, if adopted, dissolves most of this, but it cannot be relied on before it is ruled.
4. No in-app purchases: built that way deliberately
Section titled “4. No in-app purchases: built that way deliberately”No prices, no purchase UI, no upgrade button, no checkout in the native build. Purchases and approvals happen on the web, in the Portal, through SHC’s own processor.
This is not a workaround. It is what the already-ruled request-and-approve design produces on its own, and it is robust to store-rule changes precisely because there is no in-app purchase flow to re-litigate. Guideline 3.1.1 requires IAP for digital goods consumed in the app and not for services consumed outside it; an SHC subscription runs on infrastructure the customer owns and operates.
Enforced, not documented. scripts/native-store-guard.sh runs in
make lint. It sweeps the trees one prebuild actually compiles
(apps/console/routes, apps/console/src, features/console/src,
packages/apps-menu/src, 53 sources today) for purchase vocabulary, and
pins the published identifiers on both platforms. The failure mode it exists
for is not somebody adding a Buy button to the app; it is somebody adding one
to a shared screen for the Portal, where it is correct, and the next
prebuild inheriting it. Its own mutation proofs live in
tests/unit/ci/native_store_guard_test.go, including the two that a
source-grepping guard usually gets wrong: prose in a doc comment must not
trip it, and a checkout URL inside a string literal must.
Two corrections to stale framing that should not be repeated:
- Guideline 4.7 today covers “Mini apps, Mini Games, Streaming Games, Chatbots, Plug-ins, and Game Emulators” and is about code executing on the device. The “you are shipping your own app store” framing is stale; the console launches remote services it does not execute.
- Sign in with Apple (4.8) is triggered by third-party / social login. First-party Keycloak does not trigger it. It would the day “Sign in with Google” is offered; that is a real constraint on the identity roadmap, not a hypothetical.
5. Open work ledger
Section titled “5. Open work ledger”Ordered by what blocks a first submission.
- Demo cluster (§2). Blocks submission outright. Owner decisions owed on estate, hostname, and reseed cadence.
- Estate connection at runtime.
apps/console/src/app.tsresolves the daemon base URL fromconfig.get("FRAPPE_URL")and falls back towindow.location.origin, which native does not have, so it lands on the provider’shttp://localhost:8000default. Web is same-origin by construction; native must ask which estate it is talking to. This does not violate ruling 7 (strictly single-cluster): one connection per session, no switcher, cross-cluster navigation stays the Portal’s job. - Native public OIDC client.
KEYCLOAK_PUBLIC_CLIENT_ID=console-publicexists in.env.exampleandpackages/config/config.json, anddocker/keycloak/realm.jsondefines a publicconsole-publicclient: but nothing reads that key, and the client’s only redirect URI ishttp://localhost:3456/*. The confidential server-sideconsoleclient cannot be reused by a native app. Owed: exact redirect URIs on theshc-consolescheme plus the universal-link/app-link HTTPS pair, PKCE, and per-estate provisioning of the public client. - Store assets. There are none. No app icon, no adaptive icon, no
splash, no store screenshots;
apps/console/public/holds two font files. Both stores hard-block on these. - No
eas.jsonanywhere in the repo, no signing identities, no provisioning profiles, no Play service account. The build lane exists; the release lane does not. - No
PrivacyInfo.xcprivacyand no Play Data Safety declaration. Required for both stores. - The 4.2 capabilities (§1), recommended set 1/2/3/4/6.
- First-run states for no-cluster and free-tier (§3): owner decision.
- Android
<activity-alias>drawer integration. Deployed apps get launcher entries: aliases declared at build time withandroid:enabled="false", toggled at runtime viasetComponentEnabledSetting, and reconciled against the deployment list so an uninstalled app turns its alias OFF. Nothing in the tree does this today (grep -rn activity-aliasreturns nothing). This is Android-only; iOS has no equivalent and must not be given a fake one. - Realtime.
apps/console/src/app.tsdocuments that the daemon serves SSE, not socket.io, so live document updates do not work and screens poll. Acceptable for v1 on native; it is what capability 5 (push) later replaces.
6. apps/marketplace: raised, not decided
Section titled “6. apps/marketplace: raised, not decided”apps/marketplace/app.config.js declares a second native lane under
bundleIdentifier: "com.marketplace.app" / package: "com.marketplace.app",
untouched template residue of exactly the kind ruling 1 banned for the
console. This lane is unruled: the owner’s 2026-08-16 ruling named iOS,
Android, desktop and PWA for the console, and a prior proposal recommended
deleting the marketplace native lane outright.
This lane will not silently keep it or silently kill it. The options:
- Delete the native platforms from the marketplace lane (keep it web).
Consistent with the marketplace being a central web property at
marketplace.selfhostedcloud.org, and with the console’s Apps screen already being the daemon’s own catalog on-device. - Promote it and give it real identifiers (
com.selfhostedcloud.marketplace), its own assets, its own store listing, its own review argument, noting a standalone marketplace app is a much harder 4.2 case than the console, because browsing a catalog is closer to the repackaged-website shape.
Recommendation: delete the native platforms from the marketplace lane.
The guard in §4 deliberately flags com.marketplace.app as residue, so
whichever way this is ruled, it gets fixed rather than shipped.