> For the complete documentation index, see [llms.txt](/llms.txt). > A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt). --- title: Environments description: Separate preview, staging, and production traffic, promote a verified deployment forward, roll back fast, and scope secrets per environment. last_verified: 2026-10-08 --- An **environment** is a named pointer to a deployment. Requests address an environment, such as preview, staging, or production, and AGNT5 resolves the pointer to the environment's current deployment at request time. Promoting or rolling back updates that pointer; the deployment image and record stay immutable, so the build you verified in staging is the same build that serves production. --- ## Deploy to an environment Every project starts with default environments. Create additional environments from the **Deployments** page in Studio; each environment renders as its own tab. `agnt5 deploy` targets the **preview** environment by default. Name an environment to target it directly: ```bash agnt5 deploy # preview (default) agnt5 deploy --env staging agnt5 deploy --env production # asks for confirmation ``` Set replica bounds at deploy time: ```bash agnt5 deploy --env staging --min-replicas 1 --max-replicas 4 ``` Preview deployments stop after 1 hour so a test deploy never lingers. Staging and production keep running until you replace or stop them. Pass `--max-run-duration` (for example `30m` or `forever`) to change this for any deployment. > **Tip:** The usual flow is deploy to preview, verify the deployment, then promote the same deployment forward. Promotion updates the environment pointer; it does not rebuild or mutate the deployment. --- ## Promote a deployment Promotion points a target environment at a deployment that already proved itself in a lower environment. Promote from the CLI: ```bash agnt5 deployment promote --latest --env staging # the most recent deployment agnt5 deployment promote --env production --yes # a specific deployment, no prompt ``` The target environment keeps serving its current deployment until the promoted one is ready, then traffic switches over. After the switch, `agnt5 deployment checks --env staging` compares the new deployment with the one it replaced (run failure rate, new error signatures, latency, and cost) at 15 minutes, 1 hour, and 24 hours. Or promote from Studio: 1. Open your project in Studio and go to **Deployments**. 2. Select the deployment you verified (for example in the **Staging** tab). 3. Choose **Promote**, pick the target environment, and optionally adjust min/max replicas for the target. 4. Confirm. The target environment's pointer moves to this deployment; you can scale the previously serving deployment to zero in the same step. Every promotion is recorded in the environment's **promotion history**, which is what makes rollback precise. --- ## Roll back Rollback points the environment at the previously serving deployment from its promotion history. Because that deployment's image still exists, rollback is a pointer move, not a rebuild. 1. In Studio, open **Deployments** and select the environment's tab. 2. Choose **Rollback** and confirm the deployment to restore. > **Warning:** Rollback changes which code serves traffic, but not your data or secrets. If the bad deploy also changed a secret or external state, revert those separately. --- ## Scale, stop, and resume Each deployment manages its own replicas: - **Scale**: adjust min/max replicas from the deployment's **Scale** action in Studio. - **Stop**: **Terminate** stops a deployment's workers; the deployment record and image remain, so it can serve again later. - **Resume**: **Start** brings a terminated deployment back up. Check what a deployment is doing right now: ```bash agnt5 deployment list # recent deployments and their status agnt5 deployment status # replicas, traffic, and status of the current deployment agnt5 deployment errors # scheduling failures, image pull errors ``` --- ## Environment-scoped secrets Secrets default to project scope — every deployment sees them. Scope a secret to one environment when staging and production need different values: ```bash # Project-wide agnt5 secrets set --name OPENAI_API_KEY --type api_key # Production-only value agnt5 secrets set --name OPENAI_API_KEY --type api_key --environment # See which secrets an environment resolves agnt5 secrets list --environment ``` An environment-scoped secret overrides the project-scoped secret of the same name for deployments serving that environment. Your worker reads the resolved value as an environment variable, and secrets are read when a deployment starts, so deploy after you change one. **Model**: environment = named pointer to a deployment, resolved at request ingress; deployments are immutable; promote/rollback move the pointer; each environment keeps a promotion history. Preview deployments stop after 1 hour by default; staging and production have no limit. **Commands**: `agnt5 deploy --env [--min-replicas N --max-replicas N --max-run-duration D]`, `agnt5 deployment {list,status,errors,promote,checks}`, `agnt5 secrets {set,list,get,delete} [--environment ]` ## Next steps * [Deploying](/docs/run/deploying.md): the full deploy-verify-observe loop that feeds promotion. * [Experiments](/docs/improve/experiments.md): gate a promotion on eval results by running the candidate deployment against a dataset. * [Local development](/docs/build/local-development.md): iterate with `agnt5 dev` before anything reaches a managed environment.