Skip to main content
Environments provide structured management for deployments, ensuring controlled rollouts, stable endpoints, and autoscaling. They help teams stage, test, and release models without affecting production traffic. Deployments can be promoted to an environment (e.g., “staging”) to validate outputs before moving to production, allowing for safer model iteration and evaluation.

​
Using environments to manage deployments

Environments support structured validation before promoting a deployment, including:
  • Automated tests and evaluations
  • Manual testing in pre-production
  • Gradual traffic shifts with canary deployments
  • Shadow serving for real-world analysis
Promoting a deployment ensures it inherits environment-specific scaling and monitoring settings, such as: A production environment operates like any other environment but has restrictions:
  • It can’t be deleted unless the entire model is removed.
  • You can’t create additional environments named “production.”

​
Creating custom environments

In addition to the standard production environment, you can create as many custom environments as needed. There are two ways to create a custom environment:
  1. In the model management page on the Baseten dashboard.
  2. Via the create environment endpoint in the model management API.

​
Promoting deployments to environments

When you promote a deployment, Baseten follows a three-step process:
  1. A new deployment is created with a unique deployment ID.
  2. The deployment initializes resources and becomes active.
  3. The new deployment replaces the existing deployment in that environment.
  • If there was no previous deployment, default autoscaling settings are applied.
  • If a previous deployment existed, the new one inherits autoscaling settings, and the old deployment is demoted and scales to zero.

​
Promoting a published deployment

If a published deployment (not a development deployment) is promoted:
  • Its autoscaling settings are updated to match the environment.
  • If inactive, it must be activated before promotion.
Previous deployments are demoted but remain in the system, retaining their deployment ID and scaling behavior.

​
Deploying directly to an environment

You can deploy directly to a named environment by specifying --environment in truss push: 
cd my_model/
truss push --environment {environment_name}
Only one active promotion per environment is allowed at a time.

​
Accessing environments in your code

The environment name is available in model.py via the environment keyword argument: 
def __init__(self, **kwargs):
    self._environment = kwargs["environment"]
To ensure the environment variable remains updated, enable** “Re-deploy when promoting” **in the UI or via the REST API. This guarantees the environment is fully initialized after a promotion.

​
Regional environments

Regional environments restrict inference traffic to a specific geographic region for data residency compliance. When your organization enables regional environments, each environment gets a dedicated regional endpoint that routes directly to infrastructure in the designated region.
Your Baseten account team configures regional environments at the organization level. Contact them to enable regional environments.

​
Regional endpoint format

Regional endpoints embed the environment name in the hostname instead of the URL path:
Call a model’s regional endpoint with /predict or /async_predict.
https://model-{model_id}-{env_name}.api.baseten.co/predict
For example, a model with ID abc123 in the prod-us environment:
https://model-abc123-prod-us.api.baseten.co/predict
The regional endpoint URL appears in your model’s API endpoint section in the Baseten dashboard once your organization has regional environments enabled.

​
API restrictions on regional endpoints

Regional endpoints derive the environment exclusively from the hostname. Path-based routing (/environments/, /production/, /deployment/) is rejected. For gRPC, do not set x-baseten-environment or x-baseten-deployment metadata headers.

​
Deleting environments

You can delete environments, except for production. To remove a production deployment, first promote another deployment to production or delete the entire model.
  • Deleted environments are removed from the overview but remain in billing history.
  • They do not consume resources after deletion.
  • API requests to a deleted environment return a 404 error.
Deletion is permanent - consider deactivation instead.

​
Regional environments

If you have data residency or compliance requirements, Baseten supports regional environments. Regional environments guarantee that inference traffic stays within a designated geographic region by constraining replicas to designated regions and routing requests to region-specific workload planes through a dedicated endpoint.