> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stardeck.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add to Home Screen

> Pin an internal or private app to your mobile home screen so it opens like a native app — 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.

<Note>
  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](/app-visibility) for the
  difference.
</Note>

## Pinning an app to your home screen

### iPhone & iPad (Safari)

1. Open the app through Stardeck — from the [**Pinned Apps rail**](https://www.stardeck.ai/dashboard) on your dashboard, or via [**Settings → General → Visit Site**](https://www.stardeck.ai/projects/~/dashboard/project/general).
2. In Safari, tap the **Share** button.
3. Choose **Add to Home Screen**.
4. Confirm the name and tap **Add**.

### Android (Chrome)

1. Open the app through Stardeck — from the **Pinned Apps rail** on your dashboard, or via **Settings → General → Visit Site**.
2. In Chrome, tap the **⋮** menu (top right).
3. Choose **Add to Home screen** (it may read **Install app**).
4. 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 shell** around it — navigation, an address bar, and the Starcat agent chat. 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**](https://www.stardeck.ai/projects/~/dashboard/project/general):

| Setting                          | What happens when you open the app                                                          |
| -------------------------------- | ------------------------------------------------------------------------------------------- |
| **Show app shell** (default, on) | Opens inside Stardeck with the shell around it — navigation, address bar, and Starcat chat. |
| **Standalone** (off)             | Skips the shell and opens the app directly at its published URL.                            |

Turn it **off** for a standalone experience — ideal for an app you've pinned to the home screen, where the surrounding Stardeck chrome would just get in the way.

<Note>
  The **Show app shell** toggle only appears for **internal** and **private** apps. Public apps are
  always served directly at their public URL, so there's no shell to toggle.
</Note>

## 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](/app-structure/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:

1. Set the app's **visibility** to internal or private (see [App Visibility](/app-visibility)).
2. Give the app its own **favicon / apple-touch-icon** so the home-screen icon is branded.
3. Turn **Show app shell** off in **Settings → General** for a clean standalone launch.
4. 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. For access rules, see [App Visibility](/app-visibility).*