Add to Home Screen
Pin an internal or private app to a phone or tablet home screen so it opens full-screen with its own icon.
Overview
Internal and private apps don't have a public URL you bookmark directly — you open them through Stardeck. But for apps you use every day (a POS, a floor dashboard, a stock-room scanner), opening Stardeck first and tapping through is friction. Home screen pinning lets you add the app straight to your phone or tablet home screen so it launches like a native app: its own icon, full-screen, opening on the exact view you pinned.
Two pieces make this work:
- Per-app home-screen pin — when you "Add to Home Screen" from Safari or Chrome, the pin captures this app (and the exact view you're on), not the Stardeck site as a whole.
- Standalone mode — an optional per-app toggle that strips the Stardeck shell so the app owns the entire screen.
Pinning is most useful for internal and private apps. Public apps already live on a stable public URL you can bookmark or pin directly — see App Visibility for the difference.
Pinning an app to your home screen
iPhone & iPad (Safari)
- Open the app through Stardeck. See Opening internal or private apps.
- In Safari, tap the Share button.
- Choose Add to Home Screen.
- Confirm the name and tap Add.
Android (Chrome)
- Open the app through Stardeck. See Opening internal or private apps.
- In Chrome, tap the ⋮ menu (top right).
- Choose Add to Home screen (it may read Install app).
- Confirm the name and tap Add / Install.
The new icon launches the app directly. Because each app serves its own pin target, the icon opens that app — not the Stardeck dashboard — and lands on the same view you were looking at when you pinned it.
Standalone mode (Show app shell)
By default, opening an internal or private app shows the Stardeck app frame around it, with tabs for the app, its surfaces, the Guide, Build, Code, and Settings. That's handy while you're building and iterating, but for a real day-to-day business app you often want the app to own the whole screen.
Each internal or private app has a Show app shell toggle under Settings → General:
| Setting | What happens when you open the app |
|---|---|
| Show app shell (default, on) | Opens inside the Stardeck app frame, with its tabs around the app. |
| Standalone (off) | Skips the shell and opens the app directly at its published URL. |
Turn it off for a standalone experience, for example an app pinned to a shared iPad.
The toggle applies to people who can't edit the app. Anyone who can edit it (the Edit Apps
permission, or a grant on the app) always gets the frame, so test standalone mode signed in as a
staff member. Your coding agent can flip the toggle with update_app_settings.
The Show app shell toggle only appears for internal and private apps. People who can't edit a public app always get it directly at its public URL.
App icon
When you pin an app, the home-screen icon and the browser tab favicon use your deployed app's own icon — its favicon or apple-touch-icon — not the generic Stardeck mark. If your app doesn't define one, Stardeck falls back to its default icon.
To control the icon your users see, set a favicon / apple-touch-icon in your app the same way you would for any web app. Stardeck forwards it automatically.
Surfaces: per-experience install identity
If your product has multiple Surfaces, each Surface can have its own PWA name, icon, and launch path. Pin the Surface you want on that device — for example an iPad POS versus a kitchen display — instead of expecting one app-wide pin to cover every experience.
Internal Surfaces also support a per-Surface Show app shell override so a pinned station can open without Stardeck chrome.
Putting it together
For an app that should feel native on a phone or tablet:
- Set the app's visibility to internal or private (see App Visibility).
- Give the app its own favicon / apple-touch-icon so the home-screen icon is branded.
- Turn Show app shell off in Settings → General for a clean standalone launch.
- Open the app and Add to Home Screen from Safari (iOS) or Chrome (Android).
The result: a branded icon that opens your app full-screen, straight to the right view, with no Stardeck chrome in the way.
Pinning controls how an app launches, not who can reach it. Next, set who can open it in App Visibility.