> 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-06-07 --- 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 ``` > **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. 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. Via the API: ```bash curl -X POST 'https://api.agnt5.com/api/v1/deployments/promote' \ -H "X-API-KEY: " \ -H "Content-Type: application/json" \ -d '{"source_deployment_id": "", "target_environment_id": ""}' ``` --- ## 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. Via the API: `POST /api/v1/deployments/rollback`. > **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, or via `POST /api/v1/deployments//scale-up` and `/scale-down`. - **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 status # replicas, uptime, status of the latest 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. **Model**: environment = named pointer to a deployment, resolved at request ingress; deployments are immutable; promote/rollback move the pointer (`POST /api/v1/deployments/promote`, `POST /api/v1/deployments/rollback`); promotion history per environment at `GET /api/v1/environments//promotion-history`. **Commands**: `agnt5 deploy --env [--min-replicas N --max-replicas N]`, `agnt5 deployment {status,errors}`, `agnt5 secrets {set,list,get,delete} [--environment ]` **Environment APIs**: `GET/POST /api/v1/environments`, `GET/PUT/DELETE /api/v1/environments/`; deployment lifecycle: `POST /api/v1/deployments//{start,terminate,scale-up,scale-down}`. ## 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.