Architecture
What runs inside your app and what Sunboard handles — the line between local and hosted.
Sunboard splits cleanly into two halves: the parts that run inside your app, and the parts Sunboard hosts for you. Knowing where that line falls makes the rest of the docs click.
What runs where
Your side (local)
Everything here lives in your codebase and runs on your infrastructure. Sunboard never sees your source code.
- The Sunboard SDK (
@sunboard/react) runs in your users' browsers, inside your app. - Your onboarding specs are authored by your coding agent and deployed to Sunboard. They aren't committed to your repo — the server is the source of truth and versions every deploy.
- Your selectors and
track()calls live in your components. - Your user identity — you tell the SDK who the current user is (
id+ anyproperties). That data flows from your app, not from a Sunboard cookie or tracker.
Sunboard's side (hosted)
- Stores your deployed onboarding versions, segment rules, and the
onboarding.*attributes collected from surveys. - Decides and serves which experience a given user should see — and nothing goes live until you promote it.
- Collects the activation events your app reports and turns them into analytics.
- Hosts the dashboard (and backs the CLI) where you author, promote, and target.
How a user session works
At runtime the SDK makes two kinds of calls to Sunboard, both with your publishable key:
That's the whole runtime loop: ask what to show, then report what happened. The SDK never decides what's live on its own — it always reflects what's currently live in the environment its key points to.
Two keys, two jobs
Sunboard uses two separate credentials, and keeping them straight is the key to the whole model:
Publishable key
NEXT_PUBLIC_SUNBOARD_KEY, safe to ship in the browser. One per environment: pk_test_ for the sandbox, pk_live_ for production. The key selects the environment and lets the SDK read experiences and report events; it cannot change what's live.
Your CLI login
From `sunboard login`, stored on your machine / CI. Authenticated access to author, deploy, promote, and read analytics.
Production changes are always deliberate
sunboard deploy activates a version in the sandbox, never production.
Production changes only through sunboard promote, a separate step you approve.
A leaked publishable key can read that environment's onboarding and report
events, but it can't publish or alter what your users see. See
Environments for the full workflow.