Early access is open. Stagd is free during the beta. Sign up
Concepts

How Stagd works

Stagd is a control plane. Your code, images, data and previews stay in your accounts.

The pieces

  • The control plane (Stagd) receives GitHub events, keeps track of every preview, and tells your compute what to run.
  • Your compute runs the previews. It’s an account you connect, such as a Namespace workspace.
  • Your registry holds the images Stagd builds, pinned by digest.
  • The preview edge serves each preview on stable addresses, wakes it if it’s asleep, and asks for sign-in where you’ve turned that on.

A preview’s life

  1. A pull request opens. Within a few seconds the PR gets a check and a comment saying a preview is on its way.
  2. Stagd restores your seed data, builds the services that changed, and starts them on your compute.
  3. The comment and check update with the link once the preview is healthy.
  4. After 45 minutes without visits the preview sleeps. Opening its link wakes it: you see “Waking up…” for a few seconds, then your app.
  5. When the PR is merged or closed, or 24 hours after its last commit, the preview is torn down.

Both times can be changed for your org, or for one repository in stagd.yaml: see how long previews run.

Preview URLs

Previews live on a domain of their own, apart from Stagd’s, because they run your code. Each preview gets one address per public part of your app:

  • the main one, linked from the pull request: https://pr-42-web-acme.stagd.run
  • one for each other part, such as an API: https://api--pr-42-web-acme.stagd.run

The addresses stay the same for as long as the preview lives, through sleeps and new commits.

Who can open a preview

By default anyone with the link can open a preview. You can turn on sign-in protection so only members of your Stagd org can open it, keep some parts open even then (for example an API a third party calls), and add a random token to the URL so it’s hard to guess:

stagd preview policy --access org --public-ingress api --unguessable-urls
stagd preview policy --repo acme-inc/web --access public

Without --repo you set the org’s default; with it, one repository’s own rules. --reset sends a repository back to the org’s default. Access applies to existing previews on their next deploy; a URL never changes once the preview exists, so links you’ve shared keep working.

With sign-in protection on, someone opening a preview is asked to sign in to Stagd once; if they’re a member of your org they go straight on to the page they asked for. People outside your org see who they’re signed in as and that they need an invite.

Hard to guess isn’t private A token in the URL stops people guessing it, but links get pasted into chats and tickets. Use org access for anything that shouldn’t be public.

Your app, described once

Stagd reads your compose.yaml (Describe your app) and turns it into a description of what to run that doesn’t depend on any provider. Each compute provider turns that description into its own format, so switching providers doesn’t mean rewriting your setup.

The same API everywhere

The dashboard, the CLI, CI jobs and coding agents all use the same API, as the signed-in person. See the API reference.

For language models and agents: this page as Markdown, or every page through llms.txt.