Environments

How Sunboard separates a sandbox from production, and the deploy → test → promote workflow that ships onboarding safely.

Every Sunboard project has two environments: Production and Sandbox. They are fully separate worlds. Each has its own experiences, segments, surveys, users, and analytics, so anything you do in the sandbox is invisible to your live users until you choose to ship it.

You author and test in the sandbox, then promote the tested version to production. Your AI agent works only in the sandbox; production is reached through a deliberate promote that you approve.

The key is the environment

Each environment has its own browser-safe publishable key, and the key itself selects the environment:

pk_live_… (Production)

Your deployed app uses this key. The SDK reads and reports against the production world — your real users.

pk_test_… (Sandbox)

Local development uses this key. The SDK reads and reports against the sandbox, so test runs never touch production.

sunboard init writes the test key to your local .env.local, so your dev app runs against the sandbox out of the box. The live key goes wherever you deploy:

.env.local

NEXT_PUBLIC_SUNBOARD_KEY=pk_test_xxx

Written for you by sunboard init. Your dev app reads and writes the sandbox.

Vercel / Netlify / your host's env vars

NEXT_PUBLIC_SUNBOARD_KEY=pk_live_xxx

Paste the live key into your deployment's environment variables. Your shipped app reads and writes production.

There is nothing to configure in your code: the same provider runs in both environments, and the key it's given decides which world it sees.

The workflow

Author and deploy to the sandbox

Your agent (or you) authors the onboarding and runs sunboard deploy. Deploy activates the new version in the sandbox, where it's immediately live for testing.

Test it on the sandbox key

Run your app locally. Because .env.local holds the pk_test_ key, you see the real loop with real persistence, segmentation, and routing — survey answers write attributes, segments route you, and experiences render. Reset the sandbox's test users anytime to run it again:

sunboard env clear --environment development

Promote to production

When it looks right, ship the tested version:

sunboard promote <experience>      # one experience (carries its bound segments)
sunboard promote --survey          # the onboarding survey

Promote copies the exact version you tested into production (verified by content hash) and shows a diff before it writes. Production analytics are untouched, and you can roll back by promoting an earlier version.

Promotion is per-experience, on purpose

There is no "promote everything" button. You promote one experience (or the survey) at a time, each with its own diff, so the sandbox and production can intentionally differ while you iterate on one thing. Promoting an experience also carries the rules of the segment(s) it's bound to, and warns you if a shared segment will re-target another live experience.

Editing something that's already live

To change an experience that's already in production, mirror production into the sandbox first, edit there, then promote back:

sunboard env clone --from production --to development

This clears the sandbox's existing users, runtime data, and hosted content, then copies production's live experiences, bindings, segment rules, and survey. You start from exactly what users see, without copying production users or analytics. Cloning only goes into the sandbox — the path into production is always promote.

In the dashboard

The dashboard has a Sandbox / Production toggle that scopes everything you see — the flow overview, experiences, segments, the publishable key, and analytics — to one environment at a time. From the sandbox view, each experience and the survey has a Promote to production button, the same diff-and-confirm step as the CLI, for when you'd rather ship by hand than have the agent do it.

Command reference

Command	What it does
`sunboard deploy`	Upload a version and activate it in the sandbox.
`sunboard promote <experience>`	Copy the tested experience to production (diff + confirm).
`sunboard promote --survey`	Promote the active onboarding survey to production.
`sunboard env clone --from production --to development`	Destructively rebuild the sandbox from production's live content; production users and analytics are not copied.
`sunboard env clear --environment development`	Delete the sandbox's test users and runtime data (content kept).
`sunboard pull [--environment <key>]`	Export an environment's live specs to local YAML files.