Preview from your own computer

Your developer can run the app on their own computer and share an HTTPS link to it, so you can click through a change before anyone stages it. The preview uses test data, so nothing it does reaches live members.

The link works only while it runs. When your developer stops the preview, the link goes offline. For a link that stays up, stage the pushed commit.
No computer needed in Console. Playground runs the same kind of preview for you in Developers → Build.

domino dev is the command behind it: it runs the app on the device against hosted test data and shares it through an HTTPS preview URL.

Start a preview

Install from the lockfile

For a Domino starter, install dependencies from the lockfile.

Check the remote configuration

pnpm exec domino doctor --remote --json

Start development

pnpm exec domino dev

The CLI:

connects the app to hosted test data,
synchronizes authored behavior,
starts the development server,
prints an HTTPS preview URL.

Members sign in through the app.

Option	Use it to
`--port <port>`	Choose the port the app's dev server listens on; the CLI passes it as `DOMINO_APP_PORT`
`--cloudflared <path>`	Use a Cloudflare Tunnel connector you installed, instead of the one the CLI downloads

One preview per checkout. A checkout keeps the same preview address between runs. Starting a second preview from it fails with "This worktree already has a running preview" until the first stops, or 90 seconds after it stopped responding.
Sleep does not stop the app. If your device sleeps or pauses past those 90 seconds, domino dev takes the preview back when it resumes and reconnects it without restarting your dev server. It stops instead if another run started this checkout's preview in the meantime, or if Domino refuses the preview, for example because you lost publish permission.
Experimental. domino dev's result, output, and preview transport may change in a minor release.

In Console's Developers → Build, use Select to point the agent at an element, Console to inspect browser messages and attach them to a prompt, the device menu to check 768px and 390px layouts, and the address bar with Back and Forward to open and move between pages. The address follows navigation inside the preview. See preview controls. The development-preview gateway supplies these tools without changing the app repository. Staged apps do not include the bridge.

Edit resources while it runs

The CLI checks source files for changes about once a second, skipping node_modules, dist, .git, .domino, .domino-build, and .wrangler directories. This keeps quest synchronization from consuming the sandbox's file watcher limit. Your app's development server handles app hot reload separately.

New files join automatically. Resource files matching the discover patterns in relay.json join the next synchronization. Adding a .quest.ts or .quest-type.ts file under the starter's quests/ directory does not need another manifest entry.
Each update reports itself. After publishing changed resources, domino dev prints Hosted test quests updated. An update that fails prints Quest update failed: and the error, and keeps the last published version. The next good update after a failure prints Hosted test quests are up to date. when it publishes nothing new, for example after you revert the change that broke it. Playground's Map shows the failure until then.
Deleted files are not archived. Deleting a file stops including it in future bundles; it does not archive the remote quest. Run domino quests archive <key> --reason "…", or archive it in Console. See Archive a quest.

Preview addresses use https://<project-slug>--<workspace-hash>.domino.page.

Part	Details
`<project-slug>`	Globally unique, derived from the project name: Phantom Breakpoint 2026 becomes `phantom-breakpoint-2026`. A name whose slug is taken, reserved by Domino, or shorter than 3 characters receives a short suffix. Slugs stay fixed, use lowercase letters, numbers, and hyphens, and are limited to 35 characters. Find yours under Project settings → General → Project slug.
`<workspace-hash>`	19 characters. Separates workspaces and makes addresses hard to guess. Restarting the same workspace keeps its address.

Use the preview for work you are ready to show. The app is reachable through that address; member sign-in still controls member access.

Check before you stage

pnpm test
pnpm exec domino check
pnpm build
pnpm exec domino deploy --preview --environment test --json

pnpm test runs your tests, including the quest unit tests in tests/quests.test.ts (Test quests locally). check runs configured app checks, bundles quest definitions, and validates offers, badges and your other data definitions as Relay will, naming the file and field of any that fail. Remote preview validates the effective settings.

Act as a test member on the preview

The preview has the same test toolbar as staging, for whoever opens it with a preview link: act as a test member, move them to the next day, and pass their quests, before anything is staged. Your coding agent uses it to check the app's signed-in screens. Everyone else who opens the preview sees the app as before, without the toolbar.

A preview link works only on the preview it was minted for, and only while that preview runs.

devPreview links

POST /management/v1/staging/link with preview set to the URL domino dev printed (domino api POST /staging/link body.json with { "path": "/", "preview": "https://<slug>--<hash>.domino.page" }) returns a one-minute URL on that preview, as a staging link does. Opening it sets a session for that preview host alone, valid 12 hours, which domino dev's app never receives. The link names the same operators a staging link does, and Domino checks their publish permission and key on every toolbar request. A URL that is not a running preview of the project answers 404 preview-not-found, and the test environment is required. Without the link's session, the preview's /__domino/toolbar/ paths answer 403 operator-required. In every routing mode, the preview reserves /__domino/staging-access for the link and the /__domino/toolbar/ paths for the toolbar. It answers /__domino/toolbar.js with the toolbar's script only for the link's session, and adds that script only to that session's pages. The agent steps are under "Check participant flows on staging" in the Domino skill's campaign testing reference (references/campaign-testing.md).

For a persistent preview, stage the pushed commit.

Configure an existing app

To develop an app you already have, add an app section to its relay.json and make its dev script listen on DOMINO_APP_PORT. Configure a hosted app covers the settings, routing, member sign-in, Worker variables, secrets, storage, and the management key your server code receives.

When Vite is ready but the preview does not start

In Console's Playground, select Upgrade with AI if the project needs a newer CLI or still uses bundled package archives. The Playground checks for CLI 1.0.0 or newer before starting the preview, while keeping the agent available. Older CLIs build quests the API no longer accepts, which shows as Unsupported evaluator protocol when the preview starts. It does not change your dependencies until you select the upgrade action. After the agent finishes, select Start the preview.

If Vite reports that it is ready but the CLI says "The app did not start. Check its dev script.", check the CLI version installed in your project. Older CLIs check the app without requesting HTML. Apps with a browser-only page fallback, including the Classic starter, can return 404 to that check even though the page works in a browser. Upgrade the project's @domino-sdk/relay-cli and restart the preview. Current readiness checks request HTML from both the local app and its shared preview URL.

If startup still fails, confirm that the dev script listens on DOMINO_APP_PORT and that / returns a successful response to a request with Accept: text/html.

When Vite blocks the preview host

Current starters configure the preview hostname from DOMINO_PREVIEW_ORIGIN through dominoHosting(). An older app may show an allowed-host error. To fix it:

On the Cloudflare Vite plugin, use dominoHosting()'s server settings, or add the exact preview hostname to Vite's server.allowedHosts.
Configure HMR for that HTTPS preview.
Preserve your existing Vite settings. Do not allow every host.

When Vite reaches the file watcher limit

If Vite exits with ENOSPC and syscall: 'watch', the environment could not allocate another file watcher. Reduce unnecessary watched directories or enable Vite's server.watch.usePolling. Polling uses more CPU.

Domino's hosted playground and build sandboxes configure at least 524,288 watches per user at startup. For domino dev on your own Linux machine, check fs.inotify.max_user_watches on that machine. See Vite's file watcher troubleshooting.

Always on test data

domino dev always uses the hosted test environment with real sign-in and providers. The local runtime, --offline, and --review-mode options have been removed. Keep your project in the test environment while developing.

Symptom	What to do
A hosted app shows "Participant sign-in is unavailable"	Domino has not finished configuring sign-in on the shared API. Contact Domino; changing your app will not fix it.
Your server route receives 404 "Participant requests must come through a registered app or identity integration"	Check that the app runs as a staged build or a `domino dev` preview.
You use an SDK release before 0.10.0	Pass `hosted: true` to `proxyParticipant`.

For configuration or build failures, read Troubleshooting.