Skip to content
SHC Docs

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.

#CapabilityWhy it is legibleIn reach now?
1Home Screen widgets: estate health, stack up/down countsVisible on the Home Screen without opening the app; impossible on webYes. Needs a WidgetKit extension target + an App Group for the shared snapshot. Sample data renders in the gallery before any login.
2Live Activities on long installs and backups: Lock Screen + Dynamic IslandUnambiguously impossible on the web, and the single most persuasive artifact in a review videoYes, and the data already exists. installOperations.ts is already a subscribable long-running-operation store; a Live Activity is that store rendered to ActivityKit.
3Local Network discovery (Bonjour) for on-LAN estatesThe NSLocalNetworkUsageDescription prompt is itself proof of native capability, shown at first runYes, and it is genuinely useful; self-hosted estates are frequently on the LAN.
4Face ID / Keychain unlock for the estate sessionStandard for ops clients; one prompt, high legibilityYes. The token store (packages/apps-menu/src/auth/token.ts) is already the single credential chokepoint.
5Actionable push: an install finished, a backup failed, a cert is expiringRequires a server-side push path from the daemonNot yet. Needs APNs/FCM plumbing in shcd. Second wave.
6App Intents / Shortcuts: “restart the stack”, “how is my estate”Siri and Spotlight surface it outside the appYes, cheap once the daemon client is callable outside React.
7Files provider extension over estate storageStrong, but the largest buildNo. 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 bitspur or promanager; 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.

Ordered by what blocks a first submission.

  1. Demo cluster (§2). Blocks submission outright. Owner decisions owed on estate, hostname, and reseed cadence.
  2. Estate connection at runtime. apps/console/src/app.ts resolves the daemon base URL from config.get("FRAPPE_URL") and falls back to window.location.origin, which native does not have, so it lands on the provider’s http://localhost:8000 default. 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.
  3. Native public OIDC client. KEYCLOAK_PUBLIC_CLIENT_ID=console-public exists in .env.example and packages/config/config.json, and docker/keycloak/realm.json defines a public console-public client: but nothing reads that key, and the client’s only redirect URI is http://localhost:3456/*. The confidential server-side console client cannot be reused by a native app. Owed: exact redirect URIs on the shc-console scheme plus the universal-link/app-link HTTPS pair, PKCE, and per-estate provisioning of the public client.
  4. 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.
  5. No eas.json anywhere in the repo, no signing identities, no provisioning profiles, no Play service account. The build lane exists; the release lane does not.
  6. No PrivacyInfo.xcprivacy and no Play Data Safety declaration. Required for both stores.
  7. The 4.2 capabilities (§1), recommended set 1/2/3/4/6.
  8. First-run states for no-cluster and free-tier (§3): owner decision.
  9. Android <activity-alias> drawer integration. Deployed apps get launcher entries: aliases declared at build time with android:enabled="false", toggled at runtime via setComponentEnabledSetting, and reconciled against the deployment list so an uninstalled app turns its alias OFF. Nothing in the tree does this today (grep -rn activity-alias returns nothing). This is Android-only; iOS has no equivalent and must not be given a fake one.
  10. Realtime. apps/console/src/app.ts documents 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.

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.