Skip to main content

​
States

Environments and instances share one status: 
creating     → row exists, no deploy yet
deploying    → one or more components in flight
healthy      → every component is healthy (TTL clock starts here)
degraded     → at least one component failed, but others keep serving
failed       → every component failed on first deploy
tearing_down → teardown in progress
torn_down    → gone; the row stays for history
degraded is soft — redeploying the failing component flips it back to healthy.

​
Primary instance

New environments enable the primary by default, and deploy it as soon as they’re created — both from Deploy a repo and from the composer (untick it there for a definition-only environment). With the primary off, an environment is a pure definition — it runs nothing until a PR spawns a preview or you press Deploy now. Turning the primary on later (Enable primary on the Deployments tab) brings up an always-on instance at the tracked refs immediately; turning it off tears it down. The primary is the one instance with no TTL — it stays up until you disable it. Each deploy first syncs it from the definition, so composition, variable, and domain edits ship on the next deploy.

​
PR previews

PR opened       → spawn an instance and deploy
PR synchronized → redeploy the PR's component only (siblings stay frozen)
PR closed       → tear the instance down
The PR’s component runs at its branch; siblings are pinned to the commit they spawned with, so a preview is reproducible. If a sibling’s branch has moved on and you want the preview to pick it up, use Refresh (below).

​
Dev instances

A dev instance is a full copy of an environment spun up from sw dev up to test a branch. It’s tied to the CLI session: the CLI heartbeats to keep it alive, Ctrl-C tears it down, and if the CLI dies it’s reaped within a few minutes. A hard cap (8 hours) limits it regardless.

​
Manual instances

A manual instance (Deploy now) is a disposable copy at the latest tracked commits. Pushes don’t touch it — use its Deploy latest to re-resolve every ref to HEAD and pull the environment’s current variables and secrets. It expires on a one-shot TTL (the plan’s deployment TTL, or 24 hours if the plan has none).

​
TTL

An environment’s TTL comes from your plan, not the composer. The clock starts at healthy, so build time doesn’t eat your window. PR previews inherit the environment’s TTL; the primary has none; dev instances use a short rolling window refreshed by the CLI.

​
Refresh

Refresh on an instance re-resolves every sibling component (not the PR’s own) to the parent environment’s current tracked-ref HEAD and redeploys them. Use it when a sibling’s main has moved on since the PR opened.

​
Teardown

Teardown supersedes every in-flight component deploy and removes the instance. The row and its log stay for history. Tearing down a base environment doesn’t cascade to its active PR previews — close the PRs (or tear down each instance) to remove those.