Skip to main content
A Surface is a distinct experience inside one app. To its users it feels like its own mini app: its own name, generated URL, icon / PWA identity, launch behavior, and public or internal posture. Surfaces live inside one product. They are not separate Stardeck apps and not Modules. Modules are reusable capabilities; Surfaces are how people open and use parts of the product. See One Product, One App.

​
Add a Surface

The normal workflow is conversational:
  1. Ask the project agent for the experience you need — for example a POS for iPads, a kitchen display, or an internal admin.
  2. Review the result in preview.
  3. Commit or sync so the dashboard can discover the Surface.
  4. Publish the app so ready Surfaces go live.
  5. Use Launch from the Surfaces card when the Surface is live.
You do not need to hand-edit configuration files to get started. Tell the agent what audience and device the experience is for, and whether it should be public or internal.

​
Dashboard states

Open Settings and find the Surfaces card. Common labels: A Surface can appear in the dashboard soon after you commit. Its launch URL becomes usable after a production deploy.

​
Access and project visibility

Surface access is either public or internal. Project visibility still wins: There is no per-Surface private access setting. Private stays an app-level visibility choice. See App Visibility.
Internal is authentication, not admin authorization. Any signed-in organization member can open an internal Surface. If only some roles should use it (for example managers only), ask the agent to add an in-app permission check on that Surface. API routes used by the Surface authorize separately — they are not covered by the Surface access setting alone.

​
Publish, URLs, and launch identity

  • One app publish ships all ready Surfaces together.
  • Non-root Surface hosts are production-only in the current release. Preview keeps working inside the sandbox; dedicated Surface URLs appear after production deploy.
  • The root Surface uses the app’s primary host (including any custom domain bound to that host).
  • Non-root Surfaces use their generated Stardeck Surface URLs today — there is no per-Surface custom-domain picker.
  • If you need an internal experience on the root of a public app, make the whole app internal instead. An internal root Surface in a public app cannot receive the separate edge boundary.
Each Surface can have its own PWA name, icon, and launch path. Internal Surfaces can also override Show app shell so a pinned iPad or phone experience opens without Stardeck chrome. See Add to Home Screen.

​
Examples

  • Restaurant: customer ordering, POS, kitchen display, and back office as Surfaces of one system — Restaurant Surfaces
  • Service business: marketing site, customer portal, and staff admin as Surfaces of one booking product
If the next experience needs its own product ownership, tenant boundary, or release cadence, step back to When to Create a Separate App.