Environments

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:

agnt5 deploy                     # preview (default)
agnt5 deploy --env staging
agnt5 deploy --env production    # asks for confirmation

Set replica bounds at deploy time:

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:

curl -X POST 'https://api.agnt5.com/api/v1/deployments/promote' \
  -H "X-API-KEY: <token>" \
  -H "Content-Type: application/json" \
  -d '{"source_deployment_id": "<deployment-id>", "target_environment_id": "<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/<id>/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:

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:

# 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 <environment-id>

# See which secrets an environment resolves
agnt5 secrets list --environment <environment-id>

An environment-scoped secret overrides the project-scoped secret of the same name for deployments serving that environment.

Next steps

• Deploying: the full deploy-verify-observe loop that feeds promotion.
• Experiments: gate a promotion on eval results by running the candidate deployment against a dataset.
• Local development: iterate with agnt5 dev before anything reaches a managed environment.