Stage and share

Put a version of your app at a private address on test data, and choose who can open it.

Staging is a private copy of your hosted app on test data, at one address that never changes: https://<project-slug>--staging.domino.page. Use it to show your team or a client what's coming before it goes live. It stays online when nobody is working on the app, unlike a preview from your own computer.

  • Members don't see it. By default only people with access to the project in Console can open staging. You can add a password for reviewers outside Console.
  • It is what goes live. A promotion carries the build serving staging to your live app.
  • What you can do in Console. Stage a Playground checkpoint with Stage, set a password or let your servers in under Settings → Staging access, follow builds under Deployments, and try quests as a test member with the test toolbar.

Each staging build comes from an exact commit pushed to your project's repository. domino stage builds it in Domino's isolated builder and, when the build succeeds, makes staging serve it. A failed build changes nothing: the previous one keeps serving.

Stage a commit

Integrate, check, and push

For Domino-hosted projects, use main for the team's accepted source and a work branch for each change. Fetch the latest main, preserve your existing work, and reconcile any newer team changes. Check and build the integrated result, merge through your repository's review process, and push to main before updating shared staging.

When resuming Playground or a local checkout, compare it with remote main and the current staging commit from domino builds --json. If previously staged work is absent from main, reconcile the histories first. Follow the source and release workflow for the complete procedure.

This is a workflow convention, not an enforced CLI restriction. domino stage builds a pushed commit; it does not commit, push, merge branches, or update Playground. Branch names do not select environments. Development and staging currently share test data and behavior definitions.

Stage the pushed commit

pnpm exec domino stage --commit <sha> --json

In a terminal, domino stage shows the target project, test environment, API URL, and full commit SHA before submitting the build. Press Enter to cancel without starting a build. Use --yes to skip confirmation, or keep --json for scripts.

Use the SHA of the integrated commit pushed to main. A short SHA works: stage resolves it to the full commit in your checkout and fails with Git's reason when it is unknown or ambiguous. A full SHA is sent as given, so your checkout does not need it. Without --commit, stage defaults to local HEAD and requires a clean working tree. If main advances before submission, reconcile and validate the newer result. Stage builds the exact pushed commit: a commit the project's repository doesn't have, mistyped or not pushed yet, is refused before any build starts (REJECTED, apiCode: "commit-not-found"). Push it, then stage again. If a submission loses its response, retry with the original full commit SHA and request ID shown by the CLI.

Before submitting, stage warns about what the staged app will lack, without blocking the build: required app secrets that are not set, and wallet sign-in that is off in test while the app signs members in with a wallet, and profiles that leave every leaderboard row with a generated name such as Participant 1a2b3c4d. Each warning names the command that fixes it. With --json, the result lists missing secrets in missingSecrets and the wallet sign-in and leaderboard name warnings in warnings (wallet-sign-in-off, generated-leaderboard-names).

Once the build is ready, stage also prints the deployment warnings of the quests and other resources it published to test, and --json adds them to warnings. For example, quests whose files you deleted stay published until you archive them, and stage names them under quests-not-in-bundle.

Follow the build

pnpm exec domino builds --json
pnpm exec domino logs BUILD_ID --json
  • Wait or not. domino stage waits for the build and fails with STAGE_BUILD_FAILED if it fails. --no-wait returns the build ID right after submission.
  • Pick a build. Run domino logs to select a recent build from its status, time, commit, and ID. Explicit domino logs BUILD_ID skips the build picker.
  • Pick a project. Without a configured project, builds and logs offer a project picker first.
  • Output. Logs print as text by default; --json returns the build ID and log text together.

Share the staging URL

Staged builds use https://<project-slug>--staging.domino.page. The address stays the same across builds. Addresses from before the move to domino.page, https://staging-<project-slug>.domino.run, no longer serve: they answer 410 Gone with a page naming the new address, and do not redirect.

Share the URL returned by the successful build. A failed build leaves the previous preview active. Staging uses test data and remains online after local development stops. Without --json, domino stage prints the URL with a reminder of who can open it.

Control who can open staging

Staging is never public. By default, visitors sign in with Domino Console and need access to the project in Test. Console's Open app links sign you in directly. The same holds for the app's member API: requests that name the staging address answer only for browsers that signed in to staging and call through the staging address, so a script calling the API directly with the staging origin gets staging-access-required.

To share with reviewers outside Console, open Settings → Staging access, choose Password, and save a password of at least 8 characters. Visitors then enter it on the staging page; Console members can still sign in instead.

Staging accessWho can open stagingEnds when
Console sign-in (default)People with read access to the project in Test.The session expires after 12 hours.
PasswordAnyone with the password, plus Console members.The session expires after 12 hours, or the password changes or is removed.
Server access (off by default)Your own servers, on the paths you list, with a staging server key. No browser session.The key is revoked or the path is removed, within a minute.

Changing staging access requires publish permission. Password attempts are limited to 10 per IP address (an IPv6 address counts by its /64) and 100 per project in 5 minutes, right or wrong; past that, attempts are refused for a few minutes. A staging session belongs to the address that issued it and does not carry over to another one, such as after a slug change.

Let a server call staging

Some apps are an API for another backend, such as a partner's server that must test against your staging app before you go live. A server has no browser to sign in with, so you can open chosen paths to servers that send a staging server key. It is off until you list a path.

  1. Open Settings → Staging access with the Test environment selected. Under Server access, add the path prefixes the server calls, such as /api/ and /webhooks/, and select Save paths.
  2. Under Keys, name a key and select Create key. Copy it right away: Console shows it once.
  3. Give the key to the server. It sends the key in the X-Domino-Staging-Key header on each request:
curl -H "X-Domino-Staging-Key: $STAGING_SERVER_KEY" \
  "https://<project-slug>--staging.domino.page/api/v1/leaderboard?limit=1"
  • Prefixes. A request is let in when its path starts with a listed prefix: /api also covers /apiary, so end a prefix with / to cover one folder. A project lists up to 20 prefixes of up to 200 characters, without a query string. / alone, and anything that covers /__domino, /relay or /.well-known, is refused.
  • Apps with server code. Server paths reach your app as sent only with transparent routing. With legacy routing, staging still accepts only GET and HEAD and removes Authorization, so a webhook POST answers 405.
  • What the app receives. Staging removes the key before the request reaches your app, and the request gets no member session: calls to the member API through your app's /relay proxy are refused as they are for any visitor without staging access. Responses stay out of caches and search engines.
  • Everything else is unchanged. Paths you did not list, and requests without a key or with a wrong one, get the same 401 as any visitor without staging access, so the answer doesn't tell anyone which paths are open.
  • Wrong keys are limited per address. After 10 wrong keys from one IP address (an IPv6 address counts by its /64) within 5 minutes, that address's requests to server paths are refused for up to 5 minutes, right key or not. Other addresses are not affected: your server's valid key keeps working even while someone else sends wrong keys, and wrong keys from many addresses are only recorded in Domino's logs when they reach 100 for the project within 5 minutes. A refused request answers the same 401 either way.
  • Keys. A project holds up to 5 keys. Console lists each key's name, last four characters, and when it was last used. Revoke stops a key within a minute; removing a path does the same for that path.

Changing server access and creating or revoking keys require publish permission in Test, and each change is recorded in the project's audit history.

Try quests with the test toolbar

People who signed in with Console and hold publish permission see the test toolbar on staging. With it you can act as a test member, move them to the next day, pass their quests, follow their activity, send tracker records, and link wallets and X or Discord accounts to them. Everyone else sees nothing new, including visitors who signed in with the staging password.

Your coding agent can use the toolbar too, to check the app's screens as a test member. It opens staging with a one-time staging link minted by your domino login session, your API key, or an organization automation key, and acts as you, or as the automation key.

What a build does

Each build runs in a fresh, isolated sandbox with no Domino or Cloudflare credentials:

PhaseWhat happens
Installpnpm install --frozen-lockfile; packageManager must pin an exact pnpm 10 version, such as pnpm@10.18.0
CheckYour checkScript
BuildYour buildScript, which emits the app and the .domino-build resource artifacts
PackCollects the output, enforces the output limits, and stages your quests and catalog
DeployBinds secrets, the management key, and storage, applies SQL migrations, and uploads the app
ActivateSwitches staging to the new build and activates its quests, catalog, trackers, engagement, leaderboards, and referrals in test
  • Build environment. Scripts see only CI=true. Live serves the same build, so nothing in the build says test or live; check at runtime instead (Tell test from live). App secrets, the management key, and storage reach the deployed Worker, never the build.
  • Time limits. Install has 5 minutes, and check, build, and pack 3 minutes each. The whole build step has 15 minutes and is retried once, unless the source is over a limit below.
  • Source limits. The commit's source archive, the gzipped tarball of the whole commit, may be at most 20 MB. Unpacked, it may hold at most 20,000 files and folders and 100 MB. A commit over a limit fails while fetching its source, with a message that names the limit, such as "The source archive is over the 20 MB limit". The build log ends with the same message. Remove or shrink large committed files, such as images, and push again.
  • One build at a time. A project accepts a new build only after the running one finishes, or after 30 minutes.
  • All or nothing. A failed build changes nothing that serves: the previous build, its routing, and its resources stay active. SQL migrations are the exception; see Write migrations.
  • Immutable. Every build is fixed at its commit. Changing secrets, settings, or relay.json takes effect on the next stage.

Follow builds in Console

Select your project and the Test environment, then open Deployments under Developers. The page shows the latest 30 hosted app builds, including failed attempts.

ElementWhat it shows or does
All, Ready, Building, FailedFilter the list by build status.
ScreenshotA capture of the app after a successful build, when one could be taken.
CurrentMarks the build actually serving your test app, even when a newer build fails.
A buildIts commit message when available, short commit SHA, publisher, creation time, total duration, and build steps. Progress and logs update automatically while commands run. Failed builds open their logs automatically.
CopyCopies the build output for troubleshooting. Logs retain the latest 500,000 characters, including automatic build retries. Find in logs searches them.
Open appOpens the current test app. Older builds do not have separate preview links.
ReconnectAppears if updates disconnect. Console keeps the last received data visible.

Creating a project from a starter usually stages its first build automatically: the untouched starter, with its sample resources in test. If no build appears, run domino stage. Start every later build with domino stage. Console does not retry, cancel, roll back, or publish apps to production. Quest Studio publications are separate from this hosted app build history.

Where next

On this page