ReferenceAsk
Remy Reference/Architecture/Architecture/Environments
03Architecture

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.

LivePreviewDev
ReleaseThe live releaseThe branch's preview releaseA dev release per workspace
HostThe app's origin and custom domainsA gated double-hyphen preview hostThe dev box's preview host, via the sandbox proxy
Data planeThe live databasesA clone keyed by the preview releaseA clone keyed by the dev release
ExecutionA release sandboxA release sandboxThe dev box's tunnel
Who reaches itAnyone the app admitsWorkspace members and share-link holdersThe person, and their own preview

#The Boundary Decides Once

Three boundary checks turn a request into an environment:

  1. 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.
  2. 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.
  3. 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.

What This Gives an App
A public URL never serves code that was not promoted. An app that has never published answers 404 on its origin.
A preview is the branch's build on its own copy of the app's databases, safe to share and safe to abandon.
Every person developing the app has their own database and their own machine.
The same method code runs in all three environments through the same execution pipeline.
DiagramFIG. 03 — ENVIRONMENTS
hostsession credentialhook tokenEnvironment boundary1  preview host2  session env (declared)3  dev-session header4  hostResolved environmentrelease · manifest · app namemethod map · interface configLiveorigin + custom domainsanyone the app admitsPromoted releasethe promoted buildruns in release sandboxLive databasesthe live data planePreview{app}--{branch} · gatedmembers + share linksPreview releaseper branchruns in release sandboxPreview clonesnapshot · per releaseDevdev box host · own scopedeveloper + own previewDev releaseper workspacedev box or CLI tunnelDev clonesnapshot · per releaseDECIDED ONCEDATA PLANEclones never read or write liveprecedence · first match winsrequired on every serve handlernever re-derived downstream↳ exactly one of three
request signalenvironment surface / releasecloned data · isolatedgroupingflow · resolves to
One request, one environment. At the boundary, three signals (host, session credential, and hook token) are checked in a fixed order, and the first match wins. That match resolves to a single environment object (release, manifest, app name, method map, interface config), passed as a required parameter to every serve handler and never re-derived. Live serves the promoted release against the live databases. Preview and dev each run their own release against a cloned data plane, so neither can read or write live data.

``` 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.