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

API

The stagd.api.v1 API behind the dashboard, the CLI and the MCP server, over Connect. Every service and method, with their fields.

Everything Stagd does is in one API, stagd.api.v1, defined in Protocol Buffers and served with Connect. The dashboard, the CLI and stagd mcp use it, and so can your scripts. Its contract is the public Buf module buf.build/stagdhq/stagd, for generating a client in your language.

Calling it

Each method is an HTTP POST of JSON to /stagd.api.v1.<Service>/<Method>, with your session token:

curl https://app.stagd.dev/stagd.api.v1.AuthService/GetMe \
  -H "Authorization: Bearer $STAGD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Every call runs as the signed-in person, in their current org. No request names the org: it comes from the session. stagd login gets a token; the CLI’s --token and STAGD_TOKEN take one.

Reading the tables

  • Names are the JSON names: previewId, not preview_id.
  • Unset fields are left out of answers: a missing limit is 0, a missing list is empty, a missing flag is false.
  • Numbers that are int64 come as strings in JSON ("sizeBytes": "1820"), as Protocol Buffers’ JSON has them.
  • Timestamps are RFC 3339 strings ("2026-11-02T09:15:00Z"); durations are seconds with an s ("30s").
  • Enums are their values’ names ("PREVIEW_STATUS_LIVE").
  • Streams: a method marked as streaming answers with a stream of messages, which Connect’s clients read as they come; over plain HTTP it takes Connect’s streaming format, not one JSON body.

Errors

Errors use Connect’s codes: unauthenticated when you’re not signed in, permission_denied when your role can’t do something, not_found, already_exists, invalid_argument (a field breaks its rule in the tables below) and failed_precondition, with a message that says what to do.

Services

Service What it does
AuthService AuthService tells callers who they are
AccountService AccountService is the signed-in person’s own account
OrgService OrgService creates orgs and moves between them
InviteService InviteService brings people into the active org
ScmService ScmService connects code hosts to the active org and lists the repositories they give Stagd access to
ComputeService ComputeService connects the compute that previews run on to the active org
PreviewService PreviewService starts, watches and tears down preview environments
SecretService SecretService keeps the secrets previews get as variables
SeedService SeedService keeps the org’s seeds
IntegrationService IntegrationService connects the services an org’s previews use, beside compute and GitHub
ActivityService ActivityService is the org’s activity log
EventService EventService tells the dashboard when something in its org changed, so it refetches what it shows instead of polling

AuthService

AuthService tells callers who they are.

Signing in is not part of this service. Browsers sign in at /auth (GitHub, and other providers later), and the CLI signs in with device login (RFC 8628) at /auth/device/code and /auth/device/token. Both give a session token, sent to this API as Authorization: Bearer <token>.

AuthService.GetMe

POST /stagd.api.v1.AuthService/GetMe.

GetMe returns the signed-in user, the org this session acts in, and every org they belong to. Works before the user has any org.

Request (GetMeRequest):

No fields.

Answer (GetMeResponse):

Field Type
user User
active Membership The org this session acts in; unset when the user has no org yet.
memberships list of Membership
preferences Preferences How Stagd looks and behaves for them.
canCreateOrg bool Whether CreateOrg would let them make an org now. A server may run one org, or let each person create only one of their own.

AccountService

AccountService is the signed-in person’s own account: their profile, how Stagd looks for them, and where they’re signed in. It follows them across orgs, and anyone signed in may use it, viewers too.

AccountService.GetAccount

POST /stagd.api.v1.AccountService/GetAccount.

GetAccount returns the caller’s profile, the emails they may use, how they sign in, and their preferences.

Request (GetAccountRequest):

No fields.

Answer (GetAccountResponse):

Field Type
account Account

AccountService.UpdateProfile

POST /stagd.api.v1.AccountService/UpdateProfile.

UpdateProfile changes the caller’s display name and email. The email must be one of the account’s verified emails.

Request (UpdateProfileRequest):

Field Type
name string Required, at most 100 characters.
email string Required.

Answer (UpdateProfileResponse):

Field Type
account Account

AccountService.UpdatePreferences

POST /stagd.api.v1.AccountService/UpdatePreferences.

UpdatePreferences replaces the caller’s preferences.

Request (UpdatePreferencesRequest):

Field Type
preferences Preferences Required.

Answer (UpdatePreferencesResponse):

Field Type
preferences Preferences

AccountService.ListSessions

POST /stagd.api.v1.AccountService/ListSessions.

ListSessions lists where the caller is signed in: browsers and the CLI.

Request (ListSessionsRequest):

No fields.

Answer (ListSessionsResponse):

Field Type
sessions list of Session Most recently used first.

AccountService.RevokeSession

POST /stagd.api.v1.AccountService/RevokeSession.

RevokeSession signs one of the caller’s sessions out at once.

Request (RevokeSessionRequest):

Field Type
id string Required.

Answer (RevokeSessionResponse):

No fields.

AccountService.RevokeOtherSessions

POST /stagd.api.v1.AccountService/RevokeOtherSessions.

RevokeOtherSessions signs out every session of the caller’s but this one.

Request (RevokeOtherSessionsRequest):

No fields.

Answer (RevokeOtherSessionsResponse):

Field Type
revoked int32

OrgService

OrgService creates orgs and moves between them. Every other service acts in the session’s active org.

OrgService.CreateOrg

POST /stagd.api.v1.OrgService/CreateOrg.

CreateOrg creates an org with the caller as its owner, an admin, and makes it the session’s active org. Refused with FAILED_PRECONDITION when the server runs one org that exists already, or lets each person create only one and the caller has.

Request (CreateOrgRequest):

Field Type
name string Required, at most 64 characters.
slug string Required, 2 to 39 characters, matches ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$. Lower-case letters, digits and dashes, e.g. “acme”. Must be free.

Answer (CreateOrgResponse):

Field Type
membership Membership

OrgService.ListOrgs

POST /stagd.api.v1.OrgService/ListOrgs.

ListOrgs lists the orgs the caller belongs to.

Request (ListOrgsRequest):

No fields.

Answer (ListOrgsResponse):

Field Type
activeOrgId string The session’s active org; unset when the caller has none.
memberships list of Membership

OrgService.SwitchOrg

POST /stagd.api.v1.OrgService/SwitchOrg.

SwitchOrg makes another of the caller’s orgs the active one for this session.

Request (SwitchOrgRequest):

Field Type
slug string Required. A slug of an org the caller belongs to.

Answer (SwitchOrgResponse):

Field Type
active Membership

OrgService.ListMembers

POST /stagd.api.v1.OrgService/ListMembers.

ListMembers lists the people in the active org.

Request (ListMembersRequest):

No fields.

Answer (ListMembersResponse):

Field Type
members list of Member

OrgService.UpdateMemberRole

POST /stagd.api.v1.OrgService/UpdateMemberRole.

UpdateMemberRole changes someone’s role. The last admin can’t be demoted: make someone else an admin first. Nor can the owner: they hand the org on first (TransferOwnership).

Request (UpdateMemberRoleRequest):

Field Type
userId string Required.
role Role Required.

Answer (UpdateMemberRoleResponse):

Field Type
member Member

OrgService.RemoveMember

POST /stagd.api.v1.OrgService/RemoveMember.

RemoveMember takes someone out of the active org and ends their sessions in it. The last admin can’t be removed, nor the owner.

Request (RemoveMemberRequest):

Field Type
userId string Required.

Answer (RemoveMemberResponse):

No fields.

OrgService.TransferOwnership

POST /stagd.api.v1.OrgService/TransferOwnership.

TransferOwnership hands the org to another of its admins, who becomes its owner; the caller, its owner until then, stays an admin. Owner only.

Request (TransferOwnershipRequest):

Field Type
userId string Required. An admin of the org, who becomes its owner.

Answer (TransferOwnershipResponse):

No fields.

OrgService.DeleteOrg

POST /stagd.api.v1.OrgService/DeleteOrg.

DeleteOrg deletes the active org and everything Stagd keeps for it. The owner only, with the org’s slug typed as confirmation. The org is gone for its members at once, its previews are stopped and its members told by email. 30 days later its connections, repositories, secrets, seeds and activity are deleted, and Stagd’s GitHub App is uninstalled from its GitHub accounts; until then Stagd’s support can restore it. Backups keep it until they age out (90 days).

Request (DeleteOrgRequest):

Field Type
slug string Required. The active org’s slug, typed again: it must match.
reason LeaveReason
reasonText string At most 2000 characters. In the person’s own words; kept by Stagd without any of the org’s data.

Answer (DeleteOrgResponse):

Field Type
compute list of string Compute connections whose relay or access is still installed on the customer’s side, which Stagd can’t remove itself: by name, for the person to uninstall (stagd compute uninstall, or deleting the manifest).

OrgService.UpdateOrg

POST /stagd.api.v1.OrgService/UpdateOrg.

UpdateOrg changes the active org’s name, admins only. Its slug stays: it’s in links and the CLI’s commands.

Request (UpdateOrgRequest):

Field Type
name string Required, at most 64 characters. The org’s new name, e.g. “Acme Inc”; trimmed.

Answer (UpdateOrgResponse):

Field Type
membership Membership The caller’s membership in the org, with its new name.

OrgService.GetOnboarding

POST /stagd.api.v1.OrgService/GetOnboarding.

GetOnboarding is the active org’s way to its first live preview, worked out from what Stagd knows: the dashboard’s Home, stagd setup and the MCP server’s onboarding_status all read it, so they can’t disagree.

Request (GetOnboardingRequest):

No fields.

Answer (GetOnboardingResponse):

Field Type
onboarding Onboarding

OrgService.DismissOnboarding

POST /stagd.api.v1.OrgService/DismissOnboarding.

DismissOnboarding hides the steps for everyone in the org. Admins only.

Request (DismissOnboardingRequest):

No fields.

Answer (DismissOnboardingResponse):

Field Type
onboarding Onboarding

InviteService

InviteService brings people into the active org: invites by email or by code-host username, and one invite link. Accepting happens in the browser, at /join/, or on its own when someone signs in with an invited email or username.

InviteService.CreateInvites

POST /stagd.api.v1.InviteService/CreateInvites.

CreateInvites invites people with a role. Emails get a message with a link; usernames join when they next sign in with that account.

Request (CreateInvitesRequest):

Field Type
invitees list of string 1 to 50 items. Emails, or code-host usernames (GitHub’s, with or without @).
role Role Required.

Answer (CreateInvitesResponse):

Field Type
invites list of Invite
problems list of InviteProblem Invitees that weren’t invited, and why: already a member, not an email or a username.

InviteService.ListInvites

POST /stagd.api.v1.InviteService/ListInvites.

ListInvites lists the invites not yet accepted, revoked or expired.

Request (ListInvitesRequest):

No fields.

Answer (ListInvitesResponse):

Field Type
invites list of Invite

InviteService.ResendInvite

POST /stagd.api.v1.InviteService/ResendInvite.

ResendInvite sends the invite again with a new link and a new expiry.

Request (ResendInviteRequest):

Field Type
id string Required.

Answer (ResendInviteResponse):

Field Type
invite Invite

InviteService.RevokeInvite

POST /stagd.api.v1.InviteService/RevokeInvite.

RevokeInvite cancels an invite; its link stops working.

Request (RevokeInviteRequest):

Field Type
id string Required.

Answer (RevokeInviteResponse):

No fields.

POST /stagd.api.v1.InviteService/GetInviteLink.

GetInviteLink returns the org’s invite link; none while it’s off (the default) or expired. The link is only shown to admins.

Request (GetInviteLinkRequest):

No fields.

Answer (GetInviteLinkResponse):

Field Type
link InviteLink Unset while the link is off.

POST /stagd.api.v1.InviteService/ResetInviteLink.

ResetInviteLink turns the invite link on, or replaces it, optionally with another role; an old one stops working.

Request (ResetInviteLinkRequest):

Field Type
role Role The role people join with; the current one when unset.

Answer (ResetInviteLinkResponse):

Field Type
link InviteLink

POST /stagd.api.v1.InviteService/DisableInviteLink.

DisableInviteLink turns the invite link off; it stops working.

Request (DisableInviteLinkRequest):

No fields.

Answer (DisableInviteLinkResponse):

No fields.

ScmService

ScmService connects code hosts to the active org and lists the repositories they give Stagd access to.

Connecting works the same way from the dashboard and the CLI:

  1. StartConnect returns a link to the code host (for GitHub, the Stagd GitHub App’s install page) and a state tied to this org.
  2. The person opens the link and picks repositories. The code host sends them back to Stagd, which checks state and links the installation to the org.
  3. The client calls GetConnectStatus with state until it is CONNECTED.

ScmService.StartConnect

POST /stagd.api.v1.ScmService/StartConnect.

StartConnect begins connecting a code host account to the active org.

Request (StartConnectRequest):

Field Type
provider ScmProvider Only SCM_PROVIDER_GITHUB.

Answer (StartConnectResponse):

Field Type
url string Where to send the person: the code host’s install or consent page.
state string Opaque; pass to GetConnectStatus.
expireTime timestamp

ScmService.GetConnectStatus

POST /stagd.api.v1.ScmService/GetConnectStatus.

GetConnectStatus reports how a connect started by StartConnect is going.

Request (GetConnectStatusRequest):

Field Type
state string Required.

Answer (GetConnectStatusResponse):

Field Type
status ConnectStatus
connection Connection Set when CONNECTED.
error string Set when FAILED, in words a person can act on.

ScmService.ListConnections

POST /stagd.api.v1.ScmService/ListConnections.

ListConnections lists the code host accounts connected to the active org.

Request (ListConnectionsRequest):

No fields.

Answer (ListConnectionsResponse):

Field Type
connections list of Connection

ScmService.DeleteConnection

POST /stagd.api.v1.ScmService/DeleteConnection.

DeleteConnection disconnects a code host account. Its repositories stop getting previews; running previews are torn down.

Request (DeleteConnectionRequest):

Field Type
id string Required.

Answer (DeleteConnectionResponse):

No fields.

ScmService.ListRepositories

POST /stagd.api.v1.ScmService/ListRepositories.

ListRepositories lists the repositories the active org can preview.

Request (ListRepositoriesRequest):

Field Type
connectionId string Only this connection’s repositories; all of them when empty.

Answer (ListRepositoriesResponse):

Field Type
repositories list of Repository

ScmService.SetPreviewsEnabled

POST /stagd.api.v1.ScmService/SetPreviewsEnabled.

SetPreviewsEnabled turns previews on or off for a repository. Turning them off tears down its running previews.

Request (SetPreviewsEnabledRequest):

Field Type
repository string Required. A repository id or “owner/name”.
enabled bool

Answer (SetPreviewsEnabledResponse):

Field Type
repository Repository
destroyed int32 Previews torn down because previews were turned off.

ScmService.CheckRepository

POST /stagd.api.v1.ScmService/CheckRepository.

CheckRepository looks at how a repository’s app is described on its default branch (its setup), unless it looked in the last few minutes. Only for repositories with previews on: Stagd never reads the others.

Request (CheckRepositoryRequest):

Field Type
repository string Required. A repository id or “owner/name”.
force bool Look again even if it looked lately, e.g. right after a push.

Answer (CheckRepositoryResponse):

Field Type
repository Repository

ScmService.SetRepositoryHidden

POST /stagd.api.v1.ScmService/SetRepositoryHidden.

SetRepositoryHidden hides a repository from the org’s lists, or shows it again. Its previews are left as they are.

Request (SetRepositoryHiddenRequest):

Field Type
repository string Required. A repository id or “owner/name”.
hidden bool

Answer (SetRepositoryHiddenResponse):

Field Type
repository Repository

ComputeService

ComputeService connects the compute that previews run on to the active org. Previews run on the customer’s own compute; Stagd only orchestrates.

Compute is pluggable: every provider (Namespace first, then Fly.io, Azure Container Apps, Kubernetes, Unikraft Cloud, and later Stagd-managed compute) sits behind the same interface. ListProviders describes each provider’s credential and setting fields, so clients build their connect forms from it instead of knowing providers themselves.

ComputeService.ListProviders

POST /stagd.api.v1.ComputeService/ListProviders.

ListProviders lists the compute providers this Stagd server supports.

Request (ListProvidersRequest):

No fields.

Answer (ListProvidersResponse):

Field Type
providers list of ProviderInfo

ComputeService.CreateComputeConnection

POST /stagd.api.v1.ComputeService/CreateComputeConnection.

CreateConnection checks the credentials with the provider and, if they work, saves them (encrypted) as a connection of the active org.

Request (CreateComputeConnectionRequest):

Field Type
provider ComputeProvider Required.
name string Required, at most 64 characters, matches ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$.
values map of string to string Every field the provider lists, by key: secret and non-secret alike.

Answer (CreateComputeConnectionResponse):

Field Type
connection ComputeConnection
relayToken string For a connection through stagd relay: the token the relay connects with. Only ever shown here; Stagd keeps a hash.
relayInstallUrl string Deprecated. Never set: a Kubernetes cluster’s install is CreateInstallManifest’s manifest, piped to kubectl, not a link.
relayInstallExpireTime timestamp Deprecated.
tunnelToken string For a Docker host, when Stagd reaches previews through a Cloudflare Tunnel of the connection’s own: what cloudflared runs it with, next to the relay (stagd compute connect docker –run). Only ever shown here.

ComputeService.ListComputeConnections

POST /stagd.api.v1.ComputeService/ListComputeConnections.

Request (ListComputeConnectionsRequest):

No fields.

Answer (ListComputeConnectionsResponse):

Field Type
connections list of ComputeConnection

ComputeService.TestComputeConnection

POST /stagd.api.v1.ComputeService/TestComputeConnection.

TestConnection checks a saved connection’s credentials again.

Request (TestComputeConnectionRequest):

Field Type
id string Required.

Answer (TestComputeConnectionResponse):

Field Type
connection ComputeConnection

ComputeService.UpdateComputeConnection

POST /stagd.api.v1.ComputeService/UpdateComputeConnection.

UpdateConnection changes a connection’s fields, e.g. a new token, and checks the result with the provider before saving it. A secret not given stays as it was.

Request (UpdateComputeConnectionRequest):

Field Type
id string Required.
values map of string to string Only the fields to change, by key.

Answer (UpdateComputeConnectionResponse):

Field Type
connection ComputeConnection

ComputeService.SetDefaultComputeConnection

POST /stagd.api.v1.ComputeService/SetDefaultComputeConnection.

SetDefaultConnection makes a connection the one new previews run on.

Request (SetDefaultComputeConnectionRequest):

Field Type
id string Required.

Answer (SetDefaultComputeConnectionResponse):

Field Type
connection ComputeConnection

ComputeService.DeleteComputeConnection

POST /stagd.api.v1.ComputeService/DeleteComputeConnection.

DeleteConnection forgets a connection and its credentials.

Request (DeleteComputeConnectionRequest):

Field Type
id string Required.

Answer (DeleteComputeConnectionResponse):

No fields.

ComputeService.CreateRelayInstall

POST /stagd.api.v1.ComputeService/CreateRelayInstall.

CreateRelayInstall gives a relay connection a new relay token: the old one stops working, and a relay using it is cut off. For a Docker host’s relay (and cloudflared, with its tunnel’s token); Kubernetes uses CreateInstallManifest.

Request (CreateRelayInstallRequest):

Field Type
id string Required.

Answer (CreateRelayInstallResponse):

Field Type
relayToken string The new token the relay connects with. Only ever shown here.
relayInstallUrl string Deprecated. Never set: Kubernetes uses CreateInstallManifest.
relayInstallExpireTime timestamp Deprecated.
tunnelToken string When Stagd reaches the Docker host’s previews through a Cloudflare Tunnel of the connection’s own: what cloudflared runs it with, next to the relay (stagd compute install –run). Only ever shown here.

ComputeService.CreateInstallManifest

POST /stagd.api.v1.ComputeService/CreateInstallManifest.

CreateInstallManifest is everything a Kubernetes connection’s cluster needs, as one manifest for kubectl apply -f -: Stagd’s access, the relay, and what the connection chooses (the builder, the Cloudflare Tunnel with its token). While its relay is connected, an install updates it and keeps its token: the manifest leaves out the relay’s secret, so the one in the cluster stays. Otherwise, or with new_token, the relay gets a new token (the old one stops working) and the manifest has it. The tokens are in the manifest and nowhere else.

Request (CreateInstallManifestRequest):

Field Type
id string Required.
newToken bool A new relay token even while the relay is connected: the relay running now is cut off until the manifest is applied.

Answer (CreateInstallManifestResponse):

Field Type
manifest string Multi-document YAML, for kubectl apply -f -. It can hold the new relay token and the tunnel’s: print it, pipe it, don’t keep it around.
newToken bool Whether the relay got a new token, in the manifest; when not, the relay keeps the one in the cluster’s stagd-relay secret.

ComputeService.GetComputeConnectionDetails

POST /stagd.api.v1.ComputeService/GetComputeConnectionDetails.

GetComputeConnectionDetails is everything Stagd can tell about one connection, asked for now: its relay and tunnel as they are, what the compute says about itself, and what’s been done to it. Slower than ListComputeConnections, which answers from what Stagd keeps.

Request (GetComputeConnectionDetailsRequest):

Field Type
id string Required.

Answer (GetComputeConnectionDetailsResponse):

Field Type
connection ComputeConnection With its relay and tunnel asked for now, so with their details.
facts list of ComputeFact What the compute says about itself, e.g. a Docker host’s CPUs, memory and engine, or a cluster’s version and nodes; empty when it can’t be asked.
factsProblem string Why there are no facts, or not all of them, e.g. “the relay isn’t connected”; empty when there’s nothing missing.
activity list of Activity What’s been done to the connection, newest first: made, changed, new relay tokens. At most 20.

PreviewService

PreviewService starts, watches and tears down preview environments.

A webhook from a code host and a call to CreatePreview take the same path: a pull request opening on GitHub is just one more way to start a preview. That is what lets teams without a connected code host start previews from CI or the CLI.

PreviewService.CreatePreview

POST /stagd.api.v1.PreviewService/CreatePreview.

CreatePreview starts a preview, or updates the existing one for the same change request or branch to the new commit.

Request (CreatePreviewRequest):

Field Type
repository string Required. A repository id, or its “owner/name”.
source PreviewSource Required.

Answer (CreatePreviewResponse):

Field Type
preview Preview

PreviewService.ListSources

POST /stagd.api.v1.PreviewService/ListSources.

ListSources lists what a repository’s previews can be of, from its code host: its open pull requests (not from forks: those never get previews), newest first, and its branches. Only for repositories with previews on: Stagd never reads the others.

Request (ListSourcesRequest):

Field Type
repository string Required. A repository id or “owner/name”.

Answer (ListSourcesResponse):

Field Type
changes list of ChangeRequest Open pull requests, most recently updated first; at most 100.
branches list of string Branch names, the default branch first; at most 100.

PreviewService.GetPreview

POST /stagd.api.v1.PreviewService/GetPreview.

Request (GetPreviewRequest):

Field Type
id string Required.

Answer (GetPreviewResponse):

Field Type
preview Preview

PreviewService.ListPreviews

POST /stagd.api.v1.PreviewService/ListPreviews.

Request (ListPreviewsRequest):

Field Type
repository string A repository id or “owner/name”; all repositories when empty.
statuses list of PreviewStatus Only previews in these states; all but DESTROYED when empty.
pageSize int32 0 to 200.
pageToken string

Answer (ListPreviewsResponse):

Field Type
previews list of Preview
nextPageToken string

PreviewService.WatchPreview

POST /stagd.api.v1.PreviewService/WatchPreview. Streams its answers.

WatchPreview streams the preview’s state until it is live, failed or destroyed, starting with its current state.

Request (WatchPreviewRequest):

Field Type
id string Required.

Answer (WatchPreviewResponse):

Field Type
preview Preview
message string A log line or step that explains the change, e.g. “api: building (2/3)”.
component string The component the message is about; empty when it’s about the whole preview.

PreviewService.ListPreviewEvents

POST /stagd.api.v1.PreviewService/ListPreviewEvents.

ListPreviewEvents returns what happened to a preview: all of it, oldest first; or, with a page_size, a page at a time, newest first.

Request (ListPreviewEventsRequest):

Field Type
id string Required.
pageSize int32 0 to 200. With a page size, events come newest first, a page at a time; without one, all of them, oldest first.
pageToken string The next_page_token of the page before: the events older than it.

Answer (ListPreviewEventsResponse):

Field Type
events list of PreviewEvent
nextPageToken string Set when there are older events; empty on the last page and without a page size.

PreviewService.WakePreview

POST /stagd.api.v1.PreviewService/WakePreview.

WakePreview starts a sleeping preview again.

Request (WakePreviewRequest):

Field Type
id string Required.

Answer (WakePreviewResponse):

Field Type
preview Preview

PreviewService.DestroyPreview

POST /stagd.api.v1.PreviewService/DestroyPreview.

DestroyPreview tears a preview down now.

Request (DestroyPreviewRequest):

Field Type
id string Required.

Answer (DestroyPreviewResponse):

Field Type
preview Preview

PreviewService.GetPreviewFailure

POST /stagd.api.v1.PreviewService/GetPreviewFailure.

GetPreviewFailure answers what was collected about a failed preview’s current failure: its explanation, and the masked error and log lines it was explained from, for a coding agent to read with its own model.

Request (GetPreviewFailureRequest):

Field Type
id string Required. The failed preview’s id.

Answer (GetPreviewFailureResponse):

Field Type
failure PreviewFailure

PreviewService.ListTesters

POST /stagd.api.v1.PreviewService/ListTesters.

ListTesters lists the users stagd.yaml names for signing in to the preview (testers), and how each signs in.

Request (ListTestersRequest):

Field Type
id string Required.

Answer (ListTestersResponse):

Field Type
testers list of PreviewTester In stagd.yaml’s order, as at the preview’s last deploy.

PreviewService.CheckTesters

POST /stagd.api.v1.PreviewService/CheckTesters.

CheckTesters signs in to the preview as each tester, as stagd.yaml says, and says how each step went.

Request (CheckTestersRequest):

Field Type
id string Required.
names list of string Testers by name; every one when empty.

Answer (CheckTestersResponse):

Field Type
checks list of TesterCheck

PreviewService.GetPreviewPolicy

POST /stagd.api.v1.PreviewService/GetPreviewPolicy.

GetPreviewPolicy returns who may open previews and how their URLs look: the org’s default, or a repository’s (its own, or the default it inherits).

Request (GetPreviewPolicyRequest):

Field Type
repository string A repository id or “owner/name”; empty for the org’s default.

Answer (GetPreviewPolicyResponse):

Field Type
policy PreviewPolicy
inherited bool For a repository: true when it has no override and follows the org’s default.
start PreviewStartInEffect When pull requests get previews, with where that comes from.

PreviewService.UpdatePreviewPolicy

POST /stagd.api.v1.PreviewService/UpdatePreviewPolicy.

UpdatePreviewPolicy sets the org’s default, or a repository’s override. Access applies to existing previews on their next deploy; URL style only to new previews, so links already shared keep working.

Request (UpdatePreviewPolicyRequest):

Field Type
policy PreviewPolicy Required.
reset bool With a repository: drop its override, so it follows the org’s default again. Its start (when previews start) is kept: set start to unspecified for that.
startOnly bool Only the start and its label: the rest of the policy stays as it is, and a repository without an override keeps following the org’s for the rest.

Answer (UpdatePreviewPolicyResponse):

Field Type
policy PreviewPolicy
inherited bool
start PreviewStartInEffect

PreviewService.ValidateApp

POST /stagd.api.v1.PreviewService/ValidateApp.

ValidateApp checks a repository’s stagd.yaml and compose file exactly as previews read them, without starting anything (stagd validate). The client sends the files it has; when stagd.yaml points at another file, the response asks for it in requested, and the client calls again.

Request (ValidateAppRequest):

Field Type
files map of string to string At most 16 entries. Root-relative path → contents, e.g. “stagd.yaml”, “deploy/compose.yaml”.
absent list of string At most 32 items. Paths the client looked for and didn’t find.

Answer (ValidateAppResponse):

Field Type
requested list of string Files the server needs to answer and the client didn’t send or rule out; send them (or list them as absent) and call again.
files list of string The files the answer comes from, e.g. [“stagd.yaml”, “deploy/compose.yaml”].
problems list of string Empty when previews would start; each says what to fix.
notes list of string What a preview leaves out on purpose, e.g. bind mounts.
components list of AppComponent
ingresses list of PreviewIngress Ingress names, components and ports; URLs come with a real preview.
config stagd.config.v1.Config stagd.yaml as previews read it, defaults filled in: unset when it has problems, empty when there’s no stagd.yaml.
starter string A stagd.yaml to start from, made from the compose file, as a repository’s page offers it: set when there’s no stagd.yaml. stagd init writes it.

PreviewService.ListMail

POST /stagd.api.v1.PreviewService/ListMail.

ListMail lists the mail a preview captured, newest first. Only for previews with mail capture on (stagd.yaml services: { mail: {} }) and running: a sleeping preview keeps its mail, but has to wake to show it.

Request (ListMailRequest):

Field Type
previewId string Required.
limit int32 0 to 500. At most this many, newest first; 0 means 50.
after string Only messages that arrived after this cursor, from an earlier ListMail or WaitForMail; empty means all.
filter MailFilter

Answer (ListMailResponse):

Field Type
messages list of MailSummary
total int32 How many the preview captured in all; messages may stop at limit.
cursor string Where the inbox stands now, matching the filter or not: pass it as after to get only what arrives from here on.

PreviewService.GetMail

POST /stagd.api.v1.PreviewService/GetMail.

GetMail returns one captured message with its text, HTML and headers.

Request (GetMailRequest):

Field Type
previewId string Required.
id string Required.

Answer (GetMailResponse):

Field Type
message MailMessage

PreviewService.ClearMail

POST /stagd.api.v1.PreviewService/ClearMail.

ClearMail deletes everything a preview captured.

Request (ClearMailRequest):

Field Type
previewId string Required.

Answer (ClearMailResponse):

No fields.

PreviewService.DeleteMail

POST /stagd.api.v1.PreviewService/DeleteMail.

DeleteMail deletes one message a preview captured.

Request (DeleteMailRequest):

Field Type
previewId string Required.
id string Required. The message’s id, from ListMail.

Answer (DeleteMailResponse):

No fields.

PreviewService.WaitForMail

POST /stagd.api.v1.PreviewService/WaitForMail.

WaitForMail answers as soon as a message matching the filter arrives after the cursor, or with none when the timeout passes: what a test waits on after the step that should send it, and how it checks that a step sent nothing.

Request (WaitForMailRequest):

Field Type
previewId string Required.
after string As in ListMail: take it before the step that should send the message. Empty means any message captured so far counts too.
filter MailFilter
timeout duration 0s to 1m. How long to wait: up to a minute; unset means 30 seconds.
limit int32 0 to 500. At most this many, newest first; 0 means 50.

Answer (WaitForMailResponse):

Field Type
messages list of MailSummary The matching messages after the cursor, newest first; none when the timeout passed without one.
cursor string

PreviewService.ListTexts

POST /stagd.api.v1.PreviewService/ListTexts.

ListTexts lists the text messages (SMS) a preview’s app sent, newest first, caught by Stagd’s mock of the vendors’ APIs. Only for previews with text capture on (stagd.yaml services: { sms: {} }) and running.

Request (ListTextsRequest):

Field Type
previewId string Required.
limit int32 0 to 500. At most this many, newest first; 0 means 50.
after string Only those that arrived after this cursor, from an earlier ListTexts or WaitForTexts; empty means all.
filter TextFilter

Answer (ListTextsResponse):

Field Type
texts list of TextMessage
cursor string Where the texts stand now, matching the filter or not: pass it as after to get only what arrives from here on.

PreviewService.WaitForTexts

POST /stagd.api.v1.PreviewService/WaitForTexts.

WaitForTexts is WaitForMail for text messages.

Request (WaitForTextsRequest):

Field Type
previewId string Required.
after string As in ListTexts: take it before the step that should send the text. Empty means any captured so far counts too.
filter TextFilter
timeout duration 0s to 1m. How long to wait: up to a minute; unset means 30 seconds.
limit int32 0 to 500. At most this many, newest first; 0 means 50.

Answer (WaitForTextsResponse):

Field Type
texts list of TextMessage The matching texts after the cursor, newest first; none when the timeout passed without one.
cursor string

PreviewService.GetServiceUsage

POST /stagd.api.v1.PreviewService/GetServiceUsage.

GetServiceUsage returns CPU and memory per service of a preview over a window up to 24 hours. Stagd samples them every 30 seconds while a preview is live, on compute that can say: nothing while it sleeps, so the series have gaps.

Request (GetServiceUsageRequest):

Field Type
previewId string Required.
window duration 1m to 24h. How far back: up to 24 hours. Points are averaged into about 120 buckets.

Answer (GetServiceUsageResponse):

Field Type
services list of ServiceUsage By service name; services never sampled aren’t here.

PreviewService.ListLogs

POST /stagd.api.v1.PreviewService/ListLogs.

ListLogs returns the latest lines a preview’s services wrote, read from its compute when asked: Stagd keeps no copy. Each line is read for its level and message, and JSON and logfmt lines for their fields. The preview’s secrets are hidden. A sleeping preview has to wake first; a torn-down one’s logs are gone.

Request (ListLogsRequest):

Field Type
previewId string Required.
services list of string Only these services; all when empty.
since timestamp Lines at or after this time; as far back as kept when unset. To follow a preview’s logs, ask again with the last line’s time.
limit int32 0 to 5000. At most this many of the latest lines; 500 when unset.

Answer (ListLogsResponse):

Field Type
lines list of LogLine Oldest first.
truncated bool There were more lines than the limit; older ones were left out.

PreviewService.ListBuildLogs

POST /stagd.api.v1.PreviewService/ListBuildLogs.

ListBuildLogs returns what each service’s build printed, for those its compute builds, read from the compute when asked: Stagd keeps no copy. There while it builds, to follow by asking again, and after, until the preview’s instance goes; the preview’s secrets are hidden.

Request (ListBuildLogsRequest):

Field Type
previewId string Required.

Answer (ListBuildLogsResponse):

Field Type
builds list of BuildLog One per service that’s built, in the order they build.

PreviewService.ListTraces

POST /stagd.api.v1.PreviewService/ListTraces.

ListTraces lists a preview’s traces, newest first, from its own OpenTelemetry endpoint (stagd.yaml services: { otel: {} }), read when asked: Stagd keeps no copy. A sleeping preview has to wake first.

Request (ListTracesRequest):

Field Type
previewId string Required.
service string Only traces with spans from this service; all when empty.
since timestamp Traces started at or after this time; the last 15 minutes when unset.
until timestamp Traces started before this time; now when unset.
errorsOnly bool Only traces where a span failed, or the root answered 5xx.
minDuration duration Only traces that took at least this long.
limit int32 0 to 500. At most this many of the newest; 100 when unset.

Answer (ListTracesResponse):

Field Type
traces list of TraceSummary Newest first.
services list of string The services that sent traces, by name.

PreviewService.GetTrace

POST /stagd.api.v1.PreviewService/GetTrace.

GetTrace returns one trace’s spans, for a waterfall.

Request (GetTraceRequest):

Field Type
previewId string Required.
traceId string Matches ^[0-9a-f]{32}$.

Answer (GetTraceResponse):

Field Type
traceId string
spans list of Span Oldest first.

SecretService

SecretService keeps the secrets previews get as variables: the org’s, and a repository’s own, which win by name. A preview’s compose file uses them like any variable (${SESSION_SECRET}, or a bare - SESSION_SECRET). Values are encrypted at rest. Listing gives names only; an admin reads a value with RevealSecret, which the activity log records.

SecretService.ListSecrets

POST /stagd.api.v1.SecretService/ListSecrets.

Request (ListSecretsRequest):

Field Type
repository string A repository id or “owner/name”; empty for the org’s own.

Answer (ListSecretsResponse):

Field Type
secrets list of Secret

SecretService.SetSecrets

POST /stagd.api.v1.SecretService/SetSecrets.

SetSecrets creates or replaces secrets, all or none.

Request (SetSecretsRequest):

Field Type
repository string A repository id or “owner/name”; empty for the org’s own.
values map of string to string 1 to 100 entries.

Answer (SetSecretsResponse):

Field Type
secrets list of Secret
unmasked list of string Secrets too short to be masked in logs: Stagd can’t redact them from build and start output it shows.

SecretService.DeleteSecret

POST /stagd.api.v1.SecretService/DeleteSecret.

Request (DeleteSecretRequest):

Field Type
repository string
name string Required.

Answer (DeleteSecretResponse):

No fields.

SecretService.RevealSecret

POST /stagd.api.v1.SecretService/RevealSecret.

RevealSecret answers a secret’s value, for admins only. Each reveal is in the activity log, by name.

Request (RevealSecretRequest):

Field Type
repository string A repository id or “owner/name”; empty for the org’s own.
name string Required.

Answer (RevealSecretResponse):

Field Type
value string

SeedService

SeedService keeps the org’s seeds: the data a preview’s database starts with, a database dump (pg_dump’s now; MySQL’s and others’ as Stagd runs those databases) in a blob store one of the org’s integrations reaches: Azure Blob Storage, or S3 and the stores that speak it. stagd.yaml names a seed (services: { postgres: { seed: } }); what it is, only the org’s admins say, so a pull request can’t point its preview at other data.

SeedService.ListSeeds

POST /stagd.api.v1.SeedService/ListSeeds.

Request (ListSeedsRequest):

No fields.

Answer (ListSeedsResponse):

Field Type
seeds list of Seed

SeedService.CreateSeed

POST /stagd.api.v1.SeedService/CreateSeed.

CreateSeed saves a seed once its integration finds a file at its path.

Request (CreateSeedRequest):

Field Type
name string Required, at most 64 characters, matches ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$.
integration string Required. An id or a name.
path string Required, at most 1024 characters.

Answer (CreateSeedResponse):

Field Type
seed Seed

SeedService.UpdateSeed

POST /stagd.api.v1.SeedService/UpdateSeed.

UpdateSeed changes where a seed is; the file is looked up again.

Request (UpdateSeedRequest):

Field Type
seed string Required. An id or a name.
integration string Left empty, it stays as it is.
path string At most 1024 characters.

Answer (UpdateSeedResponse):

Field Type
seed Seed

SeedService.DeleteSeed

POST /stagd.api.v1.SeedService/DeleteSeed.

Request (DeleteSeedRequest):

Field Type
seed string Required.

Answer (DeleteSeedResponse):

No fields.

SeedService.FindSeedFile

POST /stagd.api.v1.SeedService/FindSeedFile.

FindSeedFile says which file a path finds now, without saving anything: for a form, before the seed is saved.

Request (FindSeedFileRequest):

Field Type
integration string Required.
path string Required, at most 1024 characters.

Answer (FindSeedFileResponse):

Field Type
file SeedFile

IntegrationService

IntegrationService connects the services an org’s previews use, beside compute and GitHub: Neon for a database branch per preview now; key vaults, secret stores and blob stores for seeding later. Each kind lists its own fields, so clients build their forms from it.

IntegrationService.ListIntegrationKinds

POST /stagd.api.v1.IntegrationService/ListIntegrationKinds.

Request (ListIntegrationKindsRequest):

No fields.

Answer (ListIntegrationKindsResponse):

Field Type
kinds list of IntegrationKind

IntegrationService.CreateIntegration

POST /stagd.api.v1.IntegrationService/CreateIntegration.

CreateIntegration checks the values with the service and saves them, the secret ones encrypted, if they work.

Request (CreateIntegrationRequest):

Field Type
kind string Required.
name string Required, at most 64 characters, matches ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$.
values map of string to string Every field the kind lists, by key: secret and not.

Answer (CreateIntegrationResponse):

Field Type
integration Integration

IntegrationService.ListIntegrations

POST /stagd.api.v1.IntegrationService/ListIntegrations.

Request (ListIntegrationsRequest):

No fields.

Answer (ListIntegrationsResponse):

Field Type
integrations list of Integration

IntegrationService.UpdateIntegration

POST /stagd.api.v1.IntegrationService/UpdateIntegration.

UpdateIntegration changes settings, and secrets when given again.

Request (UpdateIntegrationRequest):

Field Type
integration string Required. An id or a name.
values map of string to string Only the fields to change; a secret not given stays as it was.

Answer (UpdateIntegrationResponse):

Field Type
integration Integration

IntegrationService.TestIntegration

POST /stagd.api.v1.IntegrationService/TestIntegration.

Request (TestIntegrationRequest):

Field Type
integration string Required.

Answer (TestIntegrationResponse):

Field Type
integration Integration

IntegrationService.DeleteIntegration

POST /stagd.api.v1.IntegrationService/DeleteIntegration.

DeleteIntegration forgets it and its credentials; refused while a preview still has something from it, e.g. a database branch.

Request (DeleteIntegrationRequest):

Field Type
integration string Required.

Answer (DeleteIntegrationResponse):

No fields.

ActivityService

ActivityService is the org’s activity log: who changed what its previews depend on (secrets, compute, integrations, access), and when. It never holds a secret’s value.

ActivityService.ListActivity

POST /stagd.api.v1.ActivityService/ListActivity.

Request (ListActivityRequest):

Field Type
pageSize int32 0 to 500. At most this many, newest first; 50 when unset.
pageToken string The next_page_token of the page before, asked with the same filters.
area string Only this area, empty for all: “secrets”, “seeds”, “compute”, “integrations”, “repositories”, “github”, “members” or “workspace”.
actor string At most 320 characters. Only what this person did, by email; empty for everyone.

Answer (ListActivityResponse):

Field Type
activity list of Activity
nextPageToken string Empty on the last page.

EventService

EventService tells the dashboard when something in its org changed, so it refetches what it shows instead of polling. It says what changed, never the data itself: the client reads that through the usual calls, with their permission checks.

EventService.WatchEvents

POST /stagd.api.v1.EventService/WatchEvents. Streams its answers.

WatchEvents streams the active org’s changes until the client goes away. A heartbeat (kind unspecified) comes every 25 seconds, so proxies keep the connection open. Viewers only hear about previews. A client that reconnects may have missed changes: it refetches what it shows.

Request (WatchEventsRequest):

No fields.

Answer (WatchEventsResponse):

Field Type
kind ChangeKind
id string The thing’s id, e.g. a preview’s; empty when the kind is enough.

Types

The messages and enums the requests and answers use.

Account

Field Type
user User
emails list of string The verified emails the account may use as its email, the current one among them.
signInMethods list of SignInMethod How the person signs in.
preferences Preferences

Activity

Field Type
id string
createTime timestamp
actor string Who, by email; empty for Stagd itself.
via string How: “web”, “cli”, “stagd”, “relay”, or “github” for what someone did on GitHub (detail “by” holds their login).
action string What happened, “.”: e.g. “secret.set”, “compute.default_set”. Every one is listed in the platform’s docs/activity.md.
target string What it happened to, in words.
detail map of string to string

AppComponent

One component as a preview would run it.

Field Type
name string
buildContext string Built from this context, or
image string pulled as this image.

BuildLog

BuildLog is one service’s build output. Whether it’s building, built or failed is the preview’s component for the service.

Field Type
service string
text string As printed, its last 512 KB; the preview’s secrets hidden.
truncated bool There was more before; the start was left out.

ChangeKind

What kind of thing changed.

Value
CHANGE_KIND_UNSPECIFIED A heartbeat: nothing changed.
CHANGE_KIND_PREVIEW A preview: its state, components, events or title.
CHANGE_KIND_COMPUTE A compute connection.
CHANGE_KIND_CONNECTION A code host connection, e.g. the GitHub App installation.
CHANGE_KIND_REPOSITORY A repository: shared, unshared, previews on or off.
CHANGE_KIND_SECRET A secret’s name or where it applies; never its value.
CHANGE_KIND_MEMBER A member or an invite.
CHANGE_KIND_INTEGRATION An integration, e.g. Neon.
CHANGE_KIND_POLICY The preview policy: access, sleep and expiry.

ChangeRequest

ChangeRequest is a GitHub pull request or a GitLab merge request.

Field Type
number int64, as a string
title string
headRef string The branch with the changes.
headSha string
baseRef string The branch it merges into.
author string The author’s login on the code host.
url string

ComponentPhase

Value
COMPONENT_PHASE_UNSPECIFIED
COMPONENT_PHASE_PENDING
COMPONENT_PHASE_BUILDING
COMPONENT_PHASE_BUILT Built, or nothing to build (a prebuilt or unchanged image).
COMPONENT_PHASE_STARTING
COMPONENT_PHASE_RUNNING
COMPONENT_PHASE_FAILED

ComputeCapabilities

ComputeCapabilities says what a provider can do. Stagd works around what it can’t: without sleep, a sleeping preview is destroyed and recreated on wake; without volume snapshots, data is seeded on every create.

Field Type
sleep bool Instances can be stopped and resumed.
volumeSnapshots bool A volume can be snapshotted once and restored into new instances.
regions list of string Where instances can run, e.g. “eu”, “us”.
maxLifetime duration The longest an instance can live; unset when there is no limit.

ComputeConnection

ComputeConnection is one compute account linked to an org.

Field Type
id string
provider ComputeProvider
name string A name chosen by the org, e.g. “namespace-eu”. Unique in the org.
settings map of string to string The non-secret field values, e.g. {“region”: “eu”}.
account string What the provider reported about the account when last checked, e.g. the workspace name.
status ComputeConnectionStatus
statusMessage string
capabilities ComputeCapabilities
default bool New previews run on the default connection.
createdBy User
createTime timestamp
checkTime timestamp
tunnel StagdTunnel Set when the connection’s previews are reached through a Cloudflare Tunnel Stagd made for the cluster (Kubernetes, settings “previews”).
ingress StagdIngress Deprecated. Never set: Stagd’s own ingress in clusters was replaced by the tunnel.
relay StagdRelay For a connection through stagd relay, while its relay is connected: its release, and whether there’s a newer one.

ComputeConnectionStatus

Value
COMPUTE_CONNECTION_STATUS_UNSPECIFIED
COMPUTE_CONNECTION_STATUS_ACTIVE The last check worked.
COMPUTE_CONNECTION_STATUS_FAILING The last check failed; see status_message.

ComputeFact

ComputeFact is one thing the compute says about itself, e.g. {“CPUs”, “8”}, in the provider’s own terms, to show as it is.

Field Type
label string
value string

ComputeProvider

Value
COMPUTE_PROVIDER_UNSPECIFIED
COMPUTE_PROVIDER_FAKE A stand-in that runs nothing; local development and tests only.
COMPUTE_PROVIDER_NAMESPACE
COMPUTE_PROVIDER_FLY Planned.
COMPUTE_PROVIDER_AZURE_CONTAINER_APPS Planned.
COMPUTE_PROVIDER_KUBERNETES Any cluster, directly or through stagd relay.
COMPUTE_PROVIDER_UNIKRAFT Planned.
COMPUTE_PROVIDER_DOCKER A Docker host, through stagd relay.

Connection

Connection is one code host account linked to an org: for GitHub, one installation of the Stagd GitHub App on a user or organization.

Field Type
id string
provider ScmProvider
account string The account’s login on the code host, e.g. “acme-inc”.
externalId string The code host’s id for the link: the GitHub App installation id.
status ConnectionStatus
createdBy User Who connected it.
createTime timestamp
manageUrl string Where to change it on the code host: which repositories it shares, new permissions to accept. For GitHub, the installation’s settings page.
unapproved list of UnapprovedGrant What Stagd’s App asks for now that this installation hasn’t approved yet. A code host keeps an installation on what it approved until its owner approves more, at manage_url; until then, what needs these doesn’t work for its repositories. Empty when it has everything, or when Stagd couldn’t ask.

ConnectionStatus

Value
CONNECTION_STATUS_UNSPECIFIED
CONNECTION_STATUS_ACTIVE
CONNECTION_STATUS_SUSPENDED The code host suspended the installation; webhooks stop arriving.
CONNECTION_STATUS_REMOVED Uninstalled on the code host’s side.

ConnectStatus

Value
CONNECT_STATUS_UNSPECIFIED
CONNECT_STATUS_PENDING Waiting for the person to finish on the code host.
CONNECT_STATUS_CONNECTED
CONNECT_STATUS_FAILED
CONNECT_STATUS_EXPIRED

Integration

Field Type
id string
kind string
name string
settings map of string to string The non-secret field values.
account string What the service reported about the account at the last check.
status IntegrationStatus
statusMessage string
createdBy string Who connected it, by email.
createTime timestamp
checkTime timestamp
expireTime timestamp When its credentials stop working, as the service says, e.g. an Azure SAS token’s expiry; unset when they don’t.

IntegrationField

Field Type
key string
label string
help string
secret bool Encrypted at rest and never returned.
required bool
multiline bool Several lines, e.g. a list.
checkbox bool A yes or no: its value is “true”, or empty for no.
shownWith string The key of a checkbox field this one belongs to, or “key=value” for an option of a choice: shown, and asked for, only while that one is ticked or chosen.
options list of IntegrationFieldOption A choice of one, e.g. how to sign in: the value is an option’s value, the first option’s when none is given.

IntegrationFieldOption

Field Type
value string
label string
help string

IntegrationKind

Field Type
id string e.g. “neon”.
name string
description string
fields list of IntegrationField

IntegrationStatus

Value
INTEGRATION_STATUS_UNSPECIFIED
INTEGRATION_STATUS_ACTIVE
INTEGRATION_STATUS_FAILING

Invite

Field Type
id string
email string One of the two.
login string
role Role
invitedBy User
createdAt timestamp
expiresAt timestamp
url string The invite’s own link, only in CreateInvites’ and ResendInvite’s answers: to send by hand when the server sends no email, or for a username.
emailed bool An email went out with the link.
Field Type
url string
role Role
expiresAt timestamp

InviteProblem

Field Type
invitee string
reason string

LeaveReason

Why an org is deleted, to learn from; optional.

Value
LEAVE_REASON_UNSPECIFIED
LEAVE_REASON_TOO_EXPENSIVE
LEAVE_REASON_MISSING_FEATURE
LEAVE_REASON_HARD_TO_SET_UP
LEAVE_REASON_OTHER_TOOL
LEAVE_REASON_JUST_TRYING
LEAVE_REASON_OTHER

LogField

Field Type
key string
value string Strings as they are, other JSON values as JSON: 1540, false, [“a”].

LogFormat

How a line was written.

Value
LOG_FORMAT_UNSPECIFIED Plain text.
LOG_FORMAT_JSON
LOG_FORMAT_LOGFMT

LogLevel

How bad a line says it is.

Value
LOG_LEVEL_UNSPECIFIED The line doesn’t say.
LOG_LEVEL_DEBUG
LOG_LEVEL_INFO
LOG_LEVEL_WARN
LOG_LEVEL_ERROR Errors, and worse: fatal, panic, critical.

LogLine

One line a service wrote.

Field Type
time timestamp When the engine got it.
service string
level LogLevel
message string The message: a structured line’s msg or message, a plain line whole.
fields list of LogField A structured line’s other keys, in the order written; nested objects are dotted keys (user.id). Its time, level and message aren’t here.
format LogFormat
text string The line as written, secrets hidden.

MailAddress

Field Type
name string
address string

MailAttachment

Field Type
partId string Mailpit’s part id.
fileName string
contentType string
sizeBytes int64, as a string

MailFilter

Which messages: each field set must match. Case-insensitive.

Field Type
to string Part of an address or name it went to: in To, Cc or Bcc (which holds whoever it was delivered to that the headers don’t name).
from string Part of the sender’s address or name.
subject string Part of the subject.

MailHeader

Field Type
name string
value string

MailMessage

Field Type
summary MailSummary
cc list of MailAddress As summary.cc.
text string
html string As the app sent it. Show it sandboxed: it’s the preview’s content.
headers list of MailHeader
attachments list of MailAttachment
links list of string The links in the HTML and the text, each once, in order.
unfilled list of UnfilledText Text a template seems to have left unfilled, in the subject, the text or the HTML as it reads: {{name}}, ${name}, undefined, null, NaN, [object Object], Invalid Date.

MailSummary

A captured message, without its body.

Field Type
id string
from MailAddress
to list of MailAddress
subject string
snippet string The start of the text, for lists.
receiveTime timestamp
sizeBytes int64, as a string
cc list of MailAddress
bcc list of MailAddress Whoever it was delivered to that To and Cc don’t name.
attachmentCount int32

Member

Field Type
user User
role string “admin”, “member” or “viewer”; kept as text for older clients.
roleKind Role
joinedVia string How they joined: “created” (made the org), “invite”, “link”, “server” (a single-org server lets everyone in).
joinedAt timestamp
lastActiveAt timestamp Their last request in this org; unset when unknown.
login string Their code-host login, e.g. GitHub’s, when they have one.
owner bool The org’s owner: an admin who also may delete the org or hand it on. Exactly one member is.

Membership

Membership is a user’s place in one org.

Field Type
org Org
role string admin | member | viewer (“owner” from servers before roles; read it as admin)
owner bool Whether they own the org: an admin who also may delete it or hand it on.

Onboarding

Field Type
steps list of OnboardingStep The steps in order: the required ones, then the optional ones.
done int32 How many required steps are done, of how many.
required int32
next string The id of the first required step not done; empty when all are.
completeTime timestamp When the org’s first preview went live; unset until then.
dismissTime timestamp When an admin dismissed it, and who; unset until then.
dismissedBy string
admins list of User Its admins, for others waiting on an admin step.

OnboardingStep

OnboardingStep is one step on the way to the first live preview.

Field Type
id string “github”, “repositories”, “compute”, “secrets”, “first_preview”, “describe” or “invite”; clients may show steps they don’t know by title.
title string
done bool
optional bool Doesn’t hold the way open, e.g. inviting the team; listed after the required steps.
adminOnly bool Only an admin can do it; others wait for one (Onboarding.admins).
detail string Done: what was set up, e.g. “acme-inc on GitHub”. Not done: what’s missing or how, in a sentence.
url string Where it’s done or seen, in the dashboard.
skipped bool Done because there’s nothing to do, e.g. no secrets the app needs.

Org

Org is one customer account. It belongs to Stagd and is not the same thing as a GitHub organization: one Stagd org can connect several GitHub accounts, and later other code hosts.

Field Type
id string
slug string Human name for URLs and the CLI, e.g. “acme”.
name string
createTime timestamp

Preferences

Preferences are how Stagd looks and behaves for one person, in every org.

Field Type
theme Theme
timeZone string An IANA time zone, e.g. “Europe/Oslo”; empty follows the browser.
reduceMotion bool No animated build bars or live pulses.

Preview

Preview is one preview environment.

Field Type
id string
repository Repository
change ChangeRequest Set when the preview is for a change request.
branch string The branch it runs.
sha string The commit it runs (or is building).
status PreviewStatus
error string Why it failed, in words a person can act on; set when FAILED.
url string The primary ingress’s stable URL, e.g. https://pr-42-web-acme.stagd.dev. Every ingress URL wakes the preview if it’s asleep.
trigger PreviewTrigger
startedBy string Who started it: the change request’s author, or the API caller.
createTime timestamp
updateTime timestamp
expireTime timestamp When it will be torn down if nothing happens before.
ingresses list of PreviewIngress Every public URL, the primary one first.
components list of PreviewComponent The app’s parts and what each is doing.
access PreviewAccess Who may open it; individual ingresses may be public (see ingresses).
note string stagd.yaml’s comment: what someone opening the preview needs to know, e.g. “Sign in with code 123456”. Also on the pull request comment.
waiting string What a queued preview waits for before it deploys, from stagd.yaml’s wait: the commit’s checks and how they stand, e.g. “build-images (running)”. Empty when it isn’t waiting.
compute PreviewCompute The compute it runs on: the org’s default when it started, or the one its stagd.yaml names (compute:). Unset once that connection is deleted.
thumbnailTime timestamp When Stagd last took a picture of its primary ingress, as it went live; unset while it has none. The dashboard shows it on the preview’s card, from /thumbnails/.jpg on the server, for people in the preview’s org.
seed PreviewSeed The first of seeds, for clients from before there could be several.
seeds list of PreviewSeed The seeds its databases started from, and their files, as of its last deploy on a new instance: stagd.yaml’s services: { postgres: { seed } }, and mysql, mariadb, mongodb.
failure PreviewFailure Why it failed, as far as Stagd can tell from what it failed on and the logs it left: set when FAILED, unset when nothing was found to say.
testers int32 How many testers its stagd.yaml names (ListTesters), as at its last deploy.

PreviewAccess

Who may open a preview.

Value
PREVIEW_ACCESS_UNSPECIFIED
PREVIEW_ACCESS_ORG Members of the org, signed in to Stagd. Opt-in.
PREVIEW_ACCESS_PUBLIC Anyone with the link. The default.

PreviewComponent

Field Type
name string The service name, e.g. “web”, “api”, “db”.
phase ComponentPhase
message string What it’s doing or why it failed, e.g. “building (2/3)”.
builtin string Set when Stagd runs it itself: mail, otel or postgres.

PreviewCompute

PreviewCompute is the compute connection a preview runs on.

Field Type
id string
name string As on Settings → Compute, e.g. “kind”.
provider ComputeProvider

PreviewEvent

Field Type
time timestamp
status PreviewStatus
component string The component it’s about; empty for the whole preview.
message string

PreviewFailure

A failed deploy explained: where it failed, the lines that show why, and the likely cause and fix. Secrets and anything that looks like a key are masked out of it.

Field Type
stage string Where in the deploy: config, checks, source, build, pull, seed, start.
service string The compose service it’s about; empty for the whole preview.
cause string The cause, in a sentence; empty when no explanation was found.
fix string What to change; backticks around code.
confidence PreviewFailureConfidence How sure: high when the fix is mechanical, likely when it’s the usual reason.
evidence list of PreviewFailureEvidence The lines that show it, at most five.
explainedBy string What explained it: a rule’s id, e.g. rule:seed-download.
createTime timestamp
error string Stagd’s error, keys masked. Only from GetPreviewFailure.
logExcerpt string The failing service’s last log lines (its build’s, for a build), secrets and keys masked, under “== ” headings; at most 64 KB. Only from GetPreviewFailure.

PreviewFailureConfidence

Value
PREVIEW_FAILURE_CONFIDENCE_UNSPECIFIED
PREVIEW_FAILURE_CONFIDENCE_HIGH
PREVIEW_FAILURE_CONFIDENCE_LIKELY

PreviewFailureEvidence

One line that shows why, and where it’s from: “error”, “ logs” or “ build”.

Field Type
source string
text string

PreviewIngress

A public URL into the preview. Every ingress is one DNS label under stagd.dev: the primary one is https://.stagd.dev, the others https://–.stagd.dev.

Field Type
name string Lower-case letters, digits and dashes, e.g. “web”, “api”, “admin”.
component string The component it routes to, and its port.
port int32
url string
primary bool The preview’s main link, the one on the pull request.
protected bool Only org members, signed in to Stagd, can open it.
builtin string Set on ingresses Stagd adds for its own services: “mail” is the captured mail’s inbox. They’re always protected.

PreviewPolicy

PreviewPolicy is who may open previews and how their URLs look.

Field Type
repository string A repository id or “owner/name”; empty for the org’s default.
access PreviewAccess
publicIngresses list of string Ingresses anyone can reach even when access is ORG, e.g. “api” for a third-party webhook. Matched by ingress name.
unguessableUrls bool Add a random token to every new preview’s host, e.g. pr-42-web-acme-k3x9q2m7wd. Makes URLs hard to guess; it doesn’t replace access control, since links get shared.
hideMailFromViewers bool Viewers don’t see the previews’ captured mail. They see it by default: a sign-up or reset email is often what they’re checking.
sleepAfter duration 45m to 24h. How long a preview nobody opens stays awake before it sleeps; opening it wakes it again. Unset for Stagd’s default, 45 minutes, which is also the least; up to 24 hours. A repository’s stagd.yaml can set its own (lifecycle: { sleep_after: 2h }), which wins.
expireAfter duration 1h to 48h. How long a preview lives without a new commit before it’s torn down; a new commit starts it over. Unset for Stagd’s default, 24 hours; from 1 to 48 hours. stagd.yaml can set its own (lifecycle: { expire_after: 36h }).
start PreviewStart When a pull request gets a preview. Unset: a repository follows the org’s default, and the org’s default is on demand. A repository’s stagd.yaml can set its own (previews: always), which wins over both.
startLabel string At most 50 characters. With PREVIEW_START_LABEL: the GitHub label that deploys a pull request’s preview when it’s added and tears it down when it’s removed, e.g. “preview”. It has to exist in each repository.

PreviewSeed

One part of the app: a service from the compose file. A seed a preview’s database started from: its name in Stagd (empty for a URL in stagd.yaml), and the file.

Field Type
name string
file SeedFile
database string The database it seeded: postgres, mysql, mariadb or mongodb.

PreviewSource

Where a preview’s code comes from.

Field Type
changeNumber int64, as a string More than 0. Not with branch. A pull or merge request on the repository’s code host.
branch string Not with changeNumber. A branch. With sha set, that commit; else the branch’s head on the code host.
sha string Matches ^([0-9a-f]{7,40})?$. Pin a commit. Required for generic repositories, where Stagd can’t ask a code host for the branch head.

PreviewStart

PreviewStart is when a pull request gets a preview.

Value
PREVIEW_START_UNSPECIFIED A repository: follow the org’s default. The org: on demand.
PREVIEW_START_ON_DEMAND When someone asks: /stagd deploy, or Stagd’s dashboard, CLI or MCP.
PREVIEW_START_ALWAYS Every pull request, when it’s opened and on each new commit.
PREVIEW_START_LABEL Pull requests with start_label: adding it deploys, removing it tears down.

PreviewStartInEffect

PreviewStartInEffect is when a repository’s (or the org’s) pull requests get previews, all settings considered, and which one decided.

Field Type
start PreviewStart
label string
source PreviewStartSource

PreviewStartSource

PreviewStartSource is where the start that applies comes from, first to last: the repository’s stagd.yaml, its override, the org’s default, Stagd’s.

Value
PREVIEW_START_SOURCE_UNSPECIFIED
PREVIEW_START_SOURCE_STAGD
PREVIEW_START_SOURCE_ORG
PREVIEW_START_SOURCE_REPOSITORY
PREVIEW_START_SOURCE_STAGD_YAML previews: in stagd.yaml on the repository’s default branch; a pull request’s own stagd.yaml is read when its events arrive.

PreviewStatus

PreviewStatus follows the environment’s state machine: queued → provisioning → building → deploying → live → sleeping → destroyed.

Value
PREVIEW_STATUS_UNSPECIFIED
PREVIEW_STATUS_QUEUED
PREVIEW_STATUS_PROVISIONING Restoring data: a volume snapshot or a Neon branch.
PREVIEW_STATUS_BUILDING
PREVIEW_STATUS_DEPLOYING
PREVIEW_STATUS_LIVE
PREVIEW_STATUS_SLEEPING Idle; the preview URL wakes it.
PREVIEW_STATUS_FAILED
PREVIEW_STATUS_DESTROYED

PreviewTester

A user Stagd signs in as on the preview (stagd.yaml’s testers).

Field Type
name string
note string
email string
username string
signIn string The sign-in it uses, by its name under stagd.yaml’s sign_in.
how string How to sign in as it, for a person, e.g. “email, then code 123456”, with values written in stagd.yaml; a secret only by its name.
password string The password, when stagd.yaml has it written out; for members.
passwordSecret string The secret it’s from, when stagd.yaml names one, e.g. ADMIN_PASSWORD.
headers bool Whether it signs in with headers (an API’s token) rather than a form.

PreviewTrigger

What started a preview.

Value
PREVIEW_TRIGGER_UNSPECIFIED
PREVIEW_TRIGGER_WEBHOOK A code host event: a pull request opened or pushed to.
PREVIEW_TRIGGER_API CreatePreview, from the dashboard, the CLI, CI or an agent.
PREVIEW_TRIGGER_COMMENT A /stagd command in a pull request comment.

ProviderField

ProviderField is one value a provider needs to connect, e.g. an API token or a region.

Field Type
key string
label string
help string How to get or choose the value.
secret bool Secret values are encrypted at rest and never returned by the API.
required bool
choices list of string When set, the value must be one of these.

ProviderInfo

Field Type
provider ComputeProvider
name string
description string
fields list of ProviderField
capabilities ComputeCapabilities

Repository

Repository is a repository Stagd can build previews for.

Field Type
id string
connectionId string The connection it was reached through; empty for generic repositories.
provider ScmProvider
fullName string “owner/name” on the code host, or a name chosen for a generic repository.
externalId string The code host’s own id for the repository.
defaultBranch string
private bool
url string Link to the repository on the code host.
previewsEnabled bool Previews are opt-in per repository: until they’re enabled, Stagd ignores its pull requests and never reads its code.
setup RepositorySetup How the app is described on the default branch, as previews would read it; unset until Stagd has looked, and never while previews are off.
hidden bool Hidden by an org admin: left out of the lists (repositories, the new-preview picker, the command palette) unless asked for. Only the lists: previews carry on as they are.

RepositorySetup

RepositorySetup is what Stagd found on a repository’s default branch: whether it has a stagd.yaml, the compose file it reads, and what would stop a preview, the same check as stagd validate.

Field Type
configFile string “stagd.yaml” or “.stagd.yaml”; empty when the repository has none and Stagd reads the compose file alone.
composeFile string The compose file, e.g. “compose.yaml” or “deploy/compose.preview.yaml”; empty when none was found.
ingresses list of string The URLs previews get, by ingress name, the primary one first.
problems list of string What would stop a preview, in words a person can act on; empty when it would deploy.
starter string A stagd.yaml to start from, made from what was found; set when the repository has none.
checkTime timestamp
secrets list of string The secrets the app needs: names the compose file and stagd.yaml refer to as ${NAME} without a default, that stagd.yaml’s env doesn’t set and Stagd doesn’t provide (its own are STAGD_*). Sorted. Whether each has a value is for ListSecrets to say: a repository’s own or the workspace’s.

Role

What someone may do in an org. One of its admins is also its owner (Member.owner, Membership.owner): the one who may delete it or hand it on.

Value
ROLE_UNSPECIFIED
ROLE_ADMIN Everything, members and settings included.
ROLE_MEMBER Previews: deploy, tear down, read; no settings.
ROLE_VIEWER Opens the workspace’s previews, and reads their captured mail unless the preview access policy hides it; no dashboard beyond the list of previews. For people who review rather than build: product, design, QA. They sign in with a code by email; no code-host account needed.

ScmProvider

ScmProvider is the code host a repository lives on.

Value
SCM_PROVIDER_UNSPECIFIED
SCM_PROVIDER_GITHUB
SCM_PROVIDER_GITLAB Planned.
SCM_PROVIDER_BITBUCKET Planned.
SCM_PROVIDER_GENERIC No code host integration: previews are started from CI or the CLI, and source comes as an uploaded archive or a prebuilt image.

Secret

Secret is a secret’s name and when it last changed; never its value.

Field Type
name string
repository string “owner/name”, or empty for the org’s.
updateTime timestamp
updatedBy string Who set it last, by email; empty once they’re deleted.

Seed

Field Type
id string
name string As stagd.yaml names it, e.g. app-anonymized.
integrationId string The integration whose store it’s in: its id and name.
integrationName string
path string A file’s name, or a prefix ending in / for the newest file under it.
file SeedFile The file the path found at the last look.
problem string Why the last look found nothing, when it didn’t.
createdBy string Who made it, by email.
createTime timestamp
checkTime timestamp

SeedFile

A file a seed restores.

Field Type
name string Its name in the store, e.g. seeds/platform/2026-10-28.dump.
sizeBytes int64, as a string
modifyTime timestamp

ServiceUsage

One service’s CPU and memory over the window, and how it runs now.

Field Type
service string
points list of UsagePoint Oldest first, one per bucket that has samples.
sampledAt timestamp From the latest sample.
cpuPercent number Of one CPU: 150 is one and a half.
memoryBytes int64, as a string
memoryLimitBytes int64, as a string What the service may use; without a limit of its own, the machine’s memory.
restarts int32
startedAt timestamp
image string

Session

Session is one signed-in browser or CLI.

Field Type
id string
kind SessionKind
userAgent string The browser’s user agent, for a web session.
clientVersion string For a CLI session: what the CLI said about itself when it logged in.
clientPlatform string
deviceName string
signInMethod string How it signed in: “github”, “email”, or “device” for a CLI login approved in the browser.
createTime timestamp
lastSeenTime timestamp
expireTime timestamp
current bool The session this call came from.

SessionKind

Value
SESSION_KIND_UNSPECIFIED
SESSION_KIND_WEB
SESSION_KIND_CLI

SignInMethod

SignInMethod is one way someone signs in, e.g. GitHub as @ada, or a code sent to an email.

Field Type
provider string “github”, “email”, …
login string The username or email at that provider.

Span

Field Type
spanId string
parentSpanId string Empty for the root; or the caller’s span outside this trace’s spans.
name string
service string
kind SpanKind
startTime timestamp
duration duration
error bool
statusMessage string
attributes list of LogField Keys and values, as in a log line’s fields.
events list of SpanEvent

SpanEvent

Something a span recorded as it happened, e.g. an exception.

Field Type
name string
time timestamp
attributes list of LogField

SpanKind

What a span did.

Value
SPAN_KIND_UNSPECIFIED
SPAN_KIND_INTERNAL
SPAN_KIND_SERVER Handled a request.
SPAN_KIND_CLIENT Made a request: another service, a database.
SPAN_KIND_PRODUCER
SPAN_KIND_CONSUMER

stagd.config.v1.App

Where the app is described: a compose file only, for now (Helm, Kustomize and manifests come later).

Field Type
compose string The compose file’s path in the repository, e.g. deploy/compose.yaml. Left out, compose.yaml (or compose.yml, docker-compose.yaml…) at the root.

stagd.config.v1.AzureBlob

Forks Azure Blob Storage containers, each under its own name.

Field Type
from list of string At least 1 items. The org’s Azure Blob Storage integrations whose containers to fork, by name, as on the Integrations page. Each integration’s SAS needs read and list (sp=rl), and nothing more.

stagd.config.v1.Build

A service’s image: built from the repository, or one built elsewhere.

Field Type
context string Not with image. Built from this directory in the repository, e.g. “.” or services/api.
image string Not with context. Pulled as it is, e.g. ghcr.io/acme/api:${STAGD_SHA}: pushed by CI.
dockerfile string With context: the Dockerfile’s path, from the context.
target string With context: the Dockerfile’s stage to build.
args map of string to string With context: build arguments.
wait duration 1m to 2h. With image: how long to keep trying to pull it, as CI may push it after the deploy starts; between 1m and 2h. Left out, a missing image fails the deploy at once.

stagd.config.v1.Commands

Field Type
handled string What happens to a /stagd comment once it’s handled: delete (the default), collapse or keep.

stagd.config.v1.Config

Config is a repository’s stagd.yaml, as Stagd reads it: the optional file at the repository’s root that says where the app is described and what Stagd adds on top.

The messages have stagd.yaml’s own shape: a message’s JSON (protojson, with the proto field names) is the file in its plain form. A file may also use a few shorthands, which read as their plain form:

previews: always previews: { when: always } services: { mail: true } services: { mail: {} } mail: false (or otel) left out

A reader fills in the defaults, e.g. a Neon database’s name, and gives durations as protojson’s (“1200s” for 20m). Who may open previews is never set here: a pull request mustn’t be able to loosen its own preview’s access by editing a file. That’s set in Stagd.

stagd/config/v1/testdata in the stagd repository holds files with how they read, or the problems they have: every reader runs them.

Field Type
version int32 The file’s format: 1, the only one so far.
app stagd.config.v1.App Where the app is described.
ingress map of string to stagd.config.v1.Ingress The preview’s URLs by name, e.g. web: { service: web, port: 3000 }. When set, it replaces the dev.stagd.* labels in the compose file.
build map of string to stagd.config.v1.Build Where each service’s image comes from, by the compose file’s service name.
services stagd.config.v1.Services What Stagd runs next to the app.
env map of string to string Variables the compose file can use, like compose’s .env file. Values may use Stagd’s variables and secrets, ${STAGD_PR_NUMBER} or ${SESSION_SECRET}; a secret wins over a variable of the same name.
database stagd.config.v1.Database The preview’s own database.
previews stagd.config.v1.Previews When pull requests get previews: when someone asks with /stagd deploy (on-demand, the default), always, or while they have a label.
comment string Added to the pull request comment once the preview is live, e.g. how to sign in. Markdown.
commands stagd.config.v1.Commands What happens to /stagd commands.
wait stagd.config.v1.Wait GitHub checks on the commit that must pass before it deploys, e.g. the workflow that pushes the images.
registries map of string to stagd.config.v1.Registry Logins for pulling private images, by the registry’s host, e.g. ghcr.io.
lifecycle stagd.config.v1.Lifecycle How long previews stay awake and live, in place of the org’s setting.
compute string The compute connection previews run on, by its name on Settings → Compute, e.g. kind. Left out, the org’s default.
testers map of string to stagd.config.v1.Tester At most 20 entries. The users Stagd signs in as on the preview, by name, e.g. admin or member: users the app already has, in its seed or let in by a test login. Stagd signs in as them to check the sign-in works, and later to run tests; people see them on the preview’s QA tab.
signIn map of string to stagd.config.v1.SignIn At most 10 entries. How the app signs people in, by name, e.g. email-otp or token. A tester names the one it uses; with only one, every tester uses it.

stagd.config.v1.Database

The preview’s own database.

Field Type
neon stagd.config.v1.Neon A branch of a Neon database, forked for each preview.

stagd.config.v1.Fill

Field Type
field string Required.
value string

stagd.config.v1.Form

A sign-in page, and the steps a browser takes on it.

Field Type
url string Matches ^/[^ #]*$. The page’s path on the primary ingress, e.g. /login.
steps list of stagd.config.v1.Step 1 to 20 items.

stagd.config.v1.Ingress

One of the preview’s URLs: a service’s port.

Field Type
service string Required. The compose file’s service.
port int32 1 to 65535.
primary bool The URL the pull request comment and the dashboard link to first.

stagd.config.v1.Lifecycle

How long previews stay awake and live, in place of the org’s setting.

Field Type
sleepAfter duration 45m to 24h. How long a preview nobody opens stays awake: 45m to 24h.
expireAfter duration 1h to 48h. How long a preview lives without a new commit: 1h to 48h.

stagd.config.v1.Mail

Captures mail in Mailpit, the preview’s inbox. Every way Stagd catches is pointed at it unless catch names some: smtp (SMTP_HOST, SMTP_PORT, SMTP_URL, MAIL_HOST, EMAIL_HOST), resend (RESEND_BASE_URL, RESEND_API_URL) and ses (AWS_ENDPOINT_URL_SES, AWS_ENDPOINT_URL_SESV2). Without catch, ways added later are caught too, so a preview never sends real mail by surprise; with it, only those named.

Field Type
skip list of string Deprecated, at most 2 items. Deprecated: the ways left alone, the rest caught. Read as catch with those taken out; use catch.
catch list of string At least 1 items. Only these ways are pointed at the inbox, e.g. [smtp] for Mailpit alone: stagd-mock runs only for resend or ses. The rest reach the real vendor.

stagd.config.v1.MariaDB

Field Type
version string The version: 11.4 or 11.8; 11.8 when left out.
database string Matches ^[a-z_][a-z0-9_]{0,62}$. The database the app uses: preview when left out.
seed string Matches `^(https://.*

stagd.config.v1.MongoDB

Field Type
version string The version: 7.0 or 8.0; 8.0 when left out.
database string Matches ^[a-z_][a-z0-9_]{0,62}$. The database the app uses: preview when left out.
seed string Matches `^(https://.*

stagd.config.v1.MySQL

Field Type
version string The version: 8.4 or 9; 8.4 when left out.
database string Matches ^[a-z_][a-z0-9_]{0,62}$. The database the app uses: preview when left out.
seed string Matches `^(https://.*

stagd.config.v1.Neon

A Neon branch per preview, forked from a parent branch. Which parents may be forked is the org’s Neon integration’s to say: a pull request that could name any parent could fork production into its preview.

Field Type
integration string Which of the org’s Neon integrations, when it has several.
project string Required.
parent string Required. The branch to fork: its id or name.
database string The database, neondb by default.
role string The role the URLs sign in as, neondb_owner by default.
pooled bool Whether url is the pooled URL.
params map of string to string Added to the URLs, e.g. sslmode: verify-full.
env map of string to string The variables the URLs are given as, by kind: url (pooled or not, as pooled says), pooled and unpooled. By default url: DATABASE_URL.

stagd.config.v1.OTel

Field Type
export stagd.config.v1.OTelExport Where a copy of what the app sends goes on to: the team’s own backend.
ignore list of string Request paths whose traces aren’t kept, a * matching the rest, e.g. [/healthz, /internal/*].

stagd.config.v1.OTelExport

Field Type
endpoint string Required. An OTLP endpoint, e.g. https://otlp.example.com.
protocol string How it’s sent: http/protobuf (the default) or grpc.
headers map of string to string Headers sent with it, e.g. Authorization: “Bearer ${DASH0_TOKEN}”.

stagd.config.v1.Postgres

Field Type
version string The major version: 16, 17, 18 (the default) or 19. A seed made with a newer pg_dump than this doesn’t restore.
database string Matches ^[a-z_][a-z0-9_]{0,62}$. The database the app uses: postgres when left out.
seed string Matches `^(https://.*
extensions list of string Extensions made in the database as it’s created, before the seed restores, by the name CREATE EXTENSION takes: Postgres’s own (contrib: pg_trgm, pgcrypto, uuid-ossp, citext, hstore …) and any the PostgreSQL apt repository packages (vector, postgis, pg_cron, h3, hypopg …), which Stagd installs as the database starts, on Debian’s image of the version. Those that load at start (pg_cron, pg_stat_statements, timescaledb …) are preloaded.

stagd.config.v1.Previews

When pull requests get previews.

Field Type
when string Not with label. on-demand, when someone asks with /stagd deploy; or always.
label string At most 50 characters. Not with when. A GitHub label: adding it deploys the preview, removing it tears the preview down.

stagd.config.v1.Registry

A login for pulling images from one registry.

Field Type
username string Required.
password string Matches \$\{. A secret of Stagd’s, written as “${NAME}”: a password in the repository is a leaked password.

stagd.config.v1.S3

Forks S3 buckets, each under its own name.

Field Type
from list of string At least 1 items. The org’s S3 integrations whose buckets to fork, by name, as on the Integrations page. They’re read at one endpoint, in one region, with one key: integrations that differ in those can’t be forked together. Each key needs s3:ListBucket and s3:GetObject, and nothing more.

stagd.config.v1.Services

What Stagd runs next to the app.

Field Type
mail stagd.config.v1.Mail Captures the mail the app sends (Mailpit), for the dashboard and the preview’s own inbox.
otel stagd.config.v1.OTel An OpenTelemetry endpoint for the app’s traces, with a viewer (Jaeger).
postgres stagd.config.v1.Postgres A Postgres database for the preview, started from a seed when there is one. The app gets its URL in DATABASE_URL.
mysql stagd.config.v1.MySQL A MySQL database for the preview, started from a seed (a mysqldump) when there is one. The app gets its URL in MYSQL_URL, and in DATABASE_URL unless another database has it.
mariadb stagd.config.v1.MariaDB A MariaDB database, as mysql is: MYSQL_URL and DATABASE_URL.
mongodb stagd.config.v1.MongoDB A MongoDB database for the preview, started from a seed (a mongodump archive) when there is one. The app gets its URL in MONGODB_URI.
sms stagd.config.v1.Sms Catches the text messages (SMS) the app sends through Amazon SNS, for the dashboard’s Messages tab: SNS is pointed at Stagd’s mock in previews.
azureBlob stagd.config.v1.AzureBlob A fork of the org’s Azure Blob Storage containers (blobfork): the app reads every file of the real ones, and what it writes or deletes stays in the preview. The app gets AZURE_STORAGE_CONNECTION_STRING.
s3 stagd.config.v1.S3 A fork of the org’s S3 buckets (blobfork), as azure_blob is for Azure: the app gets AWS_ENDPOINT_URL_S3, and its own AWS key works there.

stagd.config.v1.SignedIn

How Stagd tells a sign-in worked. Exactly one.

Field Type
text string Not with url or request. This text shows on the page, e.g. Sign out.
url string Not with text or request. The browser ends on this path, e.g. /dashboard; a * matches the rest.
request string Not with text or url. A GET of this path answers 2xx, e.g. /api/me: for headers.

stagd.config.v1.SignIn

One way the app signs people in: a form a browser fills in, or headers sent with every request (an API’s token). Exactly one of form and headers.

Field Type
form stagd.config.v1.Form
headers map of string to string Sent with every request, e.g. Authorization: “Bearer ${tester.token}”.
signedIn stagd.config.v1.SignedIn Required. How Stagd tells the sign-in worked.

stagd.config.v1.Sms

Catches text messages: Amazon SNS, pointed at Stagd’s mock (AWS_ENDPOINT_URL_SNS).

No fields.

stagd.config.v1.Step

One thing the browser does. Values may use ${tester.*}, secrets as “${NAME}”, and, after wait_for_mail, ${mail.code} and ${mail.link}.

Field Type
fill stagd.config.v1.Fill Not with click or open or waitFor or waitForMail. Types into a field, found by its label, placeholder or name.
click string Not with fill or open or waitFor or waitForMail. Clicks a button or link, found by its text.
open string Not with fill or click or waitFor or waitForMail. Goes to a path on the preview, or ${mail.link}.
waitFor string Not with fill or click or open or waitForMail. Waits for this text to show on the page.
waitForMail stagd.config.v1.WaitForMail Not with fill or click or open or waitFor. Waits for an email the step before sent, and reads its code or link.

stagd.config.v1.Tester

A user Stagd signs in as. Its values are what the sign-in’s steps and headers use as ${tester.email}, ${tester.username}, ${tester.password} and ${tester.token}; each may be plain, or a secret of Stagd’s written as “${NAME}”.

Field Type
note string At most 200 characters. Who they are, for people and models, e.g. “org admin, sees billing”.
email string
username string
password string
token string
signIn string The sign-in it uses, by its name under sign_in; left out when there’s only one.

stagd.config.v1.Wait

Field Type
checks list of string 1 to 20 items. Check run or workflow names, e.g. [build-images]; one failing fails the preview at once.
timeout duration 1m to 2h. How long to wait for them, from when the deploy starts: 30m by default, 1m to 2h.

stagd.config.v1.WaitForMail

An email in the preview’s inbox (services: { mail: {} }), sent after the step before this one started.

Field Type
to string Who it’s to: ${tester.email} by default.
subject string Part of its subject, when the app sends other mail too.
within duration 5s to 2m. How long to wait: 30s by default, 5s to 2m.
code string A regular expression for ${mail.code}, its first group the code: by default the first 4 to 8 digits on their own in the subject, then the text.
link string A regular expression for ${mail.link}, matched against the links to the preview: by default the first.

StagdIngress

Unused: Stagd’s own ingress in clusters, replaced by StagdTunnel.

Field Type
host string
address string
certificateExpireTime timestamp
problem string
checkTime timestamp

StagdRelay

A connection’s relay, as it said when it connected.

Field Type
version string The relay’s release, e.g. “v0.4.1”; for a build that isn’t a release, what it calls itself, e.g. “v0.4.1-3-g1a2b3c4” or “dev”.
connectTime timestamp
latestVersion string The newest release, e.g. “v0.5.0”, when it’s newer than the relay’s; empty when the relay is up to date, isn’t a release, or Stagd can’t tell. The connection’s install command updates it.
updateRecommended bool Whether it should be updated rather than may be: a minor release or more behind, e.g. v0.4.1 with v0.5.0 out, not v0.5.0 with v0.5.1.
remoteAddress string Where it connects from: the address Stagd sees, and the Cloudflare location it reached, e.g. “CPH”. Only in GetComputeConnectionDetails.
location string
roundTrip duration A ping’s round trip over its connection, from Stagd to the relay and back. Only in GetComputeConnectionDetails; unset when it didn’t answer.

StagdTunnel

The Cloudflare Tunnel Stagd made for a cluster (deploy/kubernetes/stagd-tunnel.yaml), as Stagd last found it.

Field Type
host string The tunnel’s host name, e.g. “tunnel-0f3a9c2e81d4.stagd.run”: Stagd’s edge sends preview requests there; visitors never see it.
locations list of string The Cloudflare locations its connectors are at, e.g. “cph01”; empty while none is connected.
problem string What stops previews being reached through it, e.g. “waiting for cloudflared in the cluster to connect”; empty when they are.
checkTime timestamp When Stagd last looked; unset before it has.
connectors list of TunnelConnector Its connectors as Cloudflare has them now. Only in GetComputeConnectionDetails.

TesterCheck

How signing in as one tester went.

Field Type
name string
ok bool
error string Why it didn’t work, e.g. “step 3: no field named Code”.
steps list of TesterStep
url string Where the browser ended, for a form.
screenshot bytes, base64 The page when it stopped, as a JPEG, when it didn’t work.

TesterStep

Field Type
text string What it did, e.g. “fill Email” or “wait for mail to admin@acme.test”.
ok bool
error string
duration duration

TextFilter

Which text messages: each field set must match. Case-insensitive.

Field Type
to string Part of the number it went to, e.g. 4791234567.
body string Part of the body.

TextMessage

A text message the app sent, as the vendor’s API was asked to send it.

Field Type
id string
vendor string The API it went through, e.g. “sns”.
to string A phone number, e.g. +4791234567.
from string
body string
sendTime timestamp

Theme

Value
THEME_UNSPECIFIED Follows the operating system.
THEME_LIGHT
THEME_DARK

TraceSummary

A trace for a list: its root span, how long it all took, whether anything failed.

Field Type
traceId string
name string The root span’s name and service.
service string
startTime timestamp
duration duration
spanCount int32
services list of string
error bool
httpMethod string From the root span’s HTTP attributes, when it has them.
httpStatusCode int32

TunnelConnector

One connection from cloudflared next to the relay to Cloudflare; each cloudflared keeps several, at nearby locations.

Field Type
location string The Cloudflare location, e.g. “cph01”.
version string cloudflared’s release, e.g. “2026.9.1”.
originAddress string The address it connects from, as Cloudflare sees it.
openTime timestamp

UnapprovedGrant

UnapprovedGrant is one permission or event a code host installation hasn’t approved.

Field Type
name string As the code host names it: a permission (“checks”) or an event (“check_run”).
title string In words, with the access asked for: “Checks (read and write)”, “Check run events”.
why string What Stagd needs it for: “Preview checks on pull requests”.

UnfilledText

Field Type
part string “subject”, “text” or “html”.
found string What was found, e.g. “{{name}}”.
near string The words around it.

UsagePoint

Average CPU and peak memory over one bucket of time.

Field Type
time timestamp
cpuPercent number
memoryBytes int64, as a string

User

User is someone who can sign in.

Field Type
id string
email string
name string
imageUrl string

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