Environments

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, its custom domain, its API keys, its cron jobs, its webhooks, and its inbound email resolves here. Live moves only when a new release is promoted.

Preview. A branch build. Pushing any branch other than the default produces a preview release, served on a gated host with a double-hyphen label so it is never mistaken for the app's own origin. A preview has its own cloned data plane: it never reads or writes live data. Preview hosts are gated by default, shareable outside the workspace only through share links.

Dev. A person's working copy. A dev environment is keyed to the app, the person, and where their code runs, either a dev box inside the untrusted cluster or a laptop connected through the CLI tunnel. 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.

#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, 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.
   • Otherwise, a validated dev-session header, 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.

Each check produces one environment object that lazily answers which release a request is on, along with its manifest, app name, method map, and interface config. That object is a required parameter to every serve handler, 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, the person, and where their code runs: a dev box or a laptop. 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.

The dev box's preview is served on its own domain, separate from the app's, so unreleased, agent-authored code 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.