Environment lifecycle

Beyond deploys, an environment has a set of lifecycle actions you use to keep it in the shape you want — reseed it from production, reset it, pause it to save resources, move content between environments, and catch its outbound mail. Each action is exposed in the dashboard and through the environments API.

The lifecycle actions

Action	Effect
create	Provision a new environment. Preview/staging environments are cloned from production at create time.
refresh	Reseed the environment’s database and files from production, discarding its current data.
reset	Return the environment to a clean baseline, clearing changes made since it was created.
suspend	Pause the environment — it stops serving and stops consuming runtime resources.
resume	Bring a suspended environment back online.
renew	Extend an ephemeral environment’s lifetime so it isn’t reaped.
email catching	Trap all outbound mail in the environment instead of delivering it, so test sends never reach real inboxes.
clone-content	Copy database and/or files from one environment into another, directionally, with an optional dry-run.

How these run

Under the hood these actions are executed by the Forge host runtime on the node serving the environment. You never call it directly — the dashboard and the API are the supported surfaces, and each action returns a job you can track.

Refresh vs reset

The two are easy to confuse:

• refresh pulls fresh data down from production — use it when a preview has drifted and you want production-shaped data again.
• reset clears changes and returns the environment to its baseline — use it when you want a clean slate, not necessarily today’s production data.

Refresh a preview from production

curl -X POST https://api.managed.dev/v1/sites/site_01J7.../environments/env_01J8.../refresh \
  -H "Authorization: Bearer mfk_live_..." \
  -H "Idempotency-Key: a31c...09"

Clone-content

clone-content moves content between environments without redeploying code. It’s directional — you name the source and the target — and selectable — you choose db, files, or both. Run it with dry_run first to see what would change before committing.

Dashboard

Open the target environment, choose Clone content, pick the source environment and the selectors (database, files, or both), and run a dry-run before applying.

The Clone content dialog for the staging environment, with production selected as the source, database and files selectors checked, and a “Dry run” button showing a preview of what will be copied.

API

Clone production content into staging (dry-run)

curl -X POST https://api.managed.dev/v1/sites/site_01J7.../environments/env_01J8.../clone-content \
  -H "Authorization: Bearer mfk_live_..." \
  -H "Idempotency-Key: 55de...c4" \
  -H "Content-Type: application/json" \
  -d '{ "from_env": "production", "selectors": ["db", "files"], "dry_run": true }'

Drop dry_run (or set it false) to apply. The call returns 202 Accepted with an async job.

PII hard-cut carries through

Because clone-content can copy a production database into another environment, the target inherits the same fail-closed hard-cut floor: observability on the cloned-into environment never surfaces rows from before the clone. Pre-clone visitor data stays invisible.

Email catching

Test environments shouldn’t send real email. With email catching enabled, an environment traps every outbound message — password resets, order receipts, notification plugins — instead of delivering it, and you inspect what would have been sent. Production delivers normally through managed transactional mail; previews and staging catch by default so a test order never emails a real customer.

The email-catching inbox for a preview environment, listing trapped outbound messages with sender, recipient, subject, and a rendered preview of each captured email.

Suspend & renew

Suspending an environment stops it serving and frees its runtime resources — handy for a preview you’ll come back to but don’t need running right now. Resume brings it back. Renewing extends an ephemeral environment’s lifetime so the platform doesn’t reap it while you still need it.

Next steps

Configuration & secretsPer-environment config and secrets, with inheritance from the site.

Environments API referenceCreate, delete, and drive every lifecycle action programmatically.