Environments
The three environments a request can run in, how it lands in one, and why that decision is never re-derived downstream.
A request to a Remy app runs in exactly one of three environments: live, preview, or dev. This chapter covers what each one is, how a request lands in one, and why that decision is made once, at the boundary, and never re-derived downstream.
#The Three Environments
Live. The app's promoted release. Every request to the app's own origin or its custom domain resolves here, and so do its cron jobs, its webhooks, and its inbound email. An API key carries no world of its own: it follows the host it is presented on. The live release is the one the app was last promoted to, and it moves only when a new release is promoted.
Preview. A branch build. Pushing any branch other than the default produces a release with preview status, served on a gated host whose label contains a double hyphen, so it is never mistaken for the app's own origin. There are two forms: a host for the immutable build, and a stable alias host for a branch's current preview. A preview has its own databases, a clone of live's keyed by the preview release id and taken on the preview's first request, whether a page or an API call. Its app-data reads and writes never touch live's. Nothing else is isolated:
- A preview's methods use the app's one file store.
- They use the secrets' dev values, or the prod values where a builder set only those.
- They send real email and place real calls.
- Signing in to a preview creates a real app-user record.
Preview hosts are gated by default and shareable outside the workspace only through share links.
Dev. A person's working copy. A dev environment is keyed to one workspace: the app and the person, whose code runs in their dev box inside the untrusted cluster. Each person with edit access has their own dev database, cloned from live at session start, which they can reset or truncate. Dev is not a branch. A branch is a git ref anyone can move, and the platform tracks nothing about branches beyond which one is production.
| Live | Preview | Dev | |
|---|---|---|---|
| Release | The live release | The branch's preview release | A dev release per workspace |
| Host | The app's origin and custom domains | A gated double-hyphen preview host | The dev box's preview host, via the sandbox proxy |
| Data plane | The live databases | A clone keyed by the preview release | A clone keyed by the dev release |
| Execution | A release sandbox | A release sandbox | The dev box's tunnel |
| Who reaches it | Anyone the app admits | Workspace members and share-link holders | The person, and their own preview |
#The Boundary Decides Once
Three boundary checks turn a request into an environment:
- The host. An app's own origin serves live; a gated double-hyphen origin serves that branch's build. A host is only ever one of those two things.
- The session. The credential a request carries can refine the host's answer, but only in a fixed order, stated once, highest priority first:
- A preview host wins outright: a dev-session token presented there cannot retarget a gated origin.
- Otherwise, the session's own declared environment governs, dev before preview. A preview session reaches its build only on the preview's own host; the voice worker's session is the one exception.
- Otherwise, a dev-session header naming one of the app's dev releases, the tunnel's escape hatch for requests it proxies in from outside.
- Otherwise, whatever the host said.
- The hook token. A callback carries the environment its hook token was minted in, so a call from inside a sandbox lands in the same world as the request that started it. Dev and preview descendants stay on the parent's release. Live descendants follow whatever is live when they ask, as live SQL does.
A credential that says dev or preview but cannot name a release that qualifies resolves to that world with nothing in it, never to live. A request that said dev or preview is answered with a 404 or a refusal rather than with production.
Each check produces one environment object that lazily answers, with memoization, which release a request is on, along with its release id, method map, and interface config. The serve path requires the host's target, so every serve request has its environment decided before any handler runs. The handlers that run code, read config, or touch data receive the environment itself rather than a bare tag, so a new surface cannot be built without deciding its environment.
Downstream code may read which of the three worlds it is in, but it may not re-derive which release, config, or data plane it is on. All three cases answer those questions the same way, and a call site cannot tell them apart.
#What Dev Is Keyed To
A dev environment is keyed to the app and the person. The dev release is per workspace and is resumed rather than recreated, so hook tokens and data-plane keys stay valid across a box restart. It lasts until the person leaves the app's workspace or goes thirty days without a box in the app, at which point the workspace is retired and its data deleted. See Dev Boxes.
The dev box's preview is served on a per-session host under the sandbox domain, a separate registrable domain from the app apex. Unreleased, agent-authored code therefore never shares a cookie scope with deployed apps or with the preview gate. The control channel and language server are authenticated routes on the API host, a different origin again, so code running in a preview cannot reach the box's control surfaces.
``` Figure 03, "Environments": a comparison of three worlds above a decision funnel. Three columns, Live | Preview | Dev, compared row by row: Host: the app's origin plus custom domains | the gated double-hyphen preview host | the dev box's per-session host on the sandbox domain Release: the promoted release | the branch's preview release | the dev release (per person) Data plane: the live databases | a clone keyed by the preview release | a clone keyed by the dev release Runs on: a release sandbox | a release sandbox | the dev box's tunnel The Preview and Dev data-plane nodes are drawn as stacked duplicates (a ghost sheet behind the node) so they read as copies of live's. Below, a funnel of three boundaries feeding one object. The host feeds the host check. The session feeds the session check, with the precedence list beside it: preview host, then session environment, then dev-session header, then host. The hook token feeds the hook-token check. All three arrows converge on one Environment object (which world, release, release id, method map, interface config), annotated "decided once" and "never re-derived downstream", which feeds every handler that runs code, reads config, or touches data. There is no trust boundary in this figure, so there is no crimson.