Environments

An environment is an isolated instance of your project with its own containers, domains, database, and configuration. Every project has at least one environment (production). Additional environments, such as staging or preview environments, let you test changes safely before they affect real users. There is no default cap on the number of environments per project — limits are opt-in and configured by an admin when needed.

What is an environment

An environment is the combination of:

• Running containers — One or more Docker containers serving your application
• A domain — An auto-assigned subdomain plus optional custom domains
• Environment variables — Configuration values specific to this environment (see Manage environment variables)
• A deployment config — CPU limits, memory limits, replica count, and exposed port (see Resources)
• Its own database — When linked to a managed service, each environment gets an isolated database (e.g. my_app_production vs my_app_staging)
• Security configuration — Attack mode and other security settings can be configured per environment, overriding the project-level default

Environments within the same project share the Git repository, the project settings, and the linked managed services. But each environment runs its own containers with its own configuration.

Environment types

Production environment

Every project has exactly one production environment. It is created when the project is created and cannot be deleted. The production environment:

• Receives deployments when the project's main branch (usually main) is pushed
• Is the default target for custom domains
• Has its own deployment config that can differ from other environments

Preview environments

When enable_preview_environments is turned on for a project, pushing to any non-main branch automatically creates a preview environment. The environment is named after the branch.

Preview environments:

• Are marked with is_preview: true
• Get a URL in the format {project}-{branch-slug}.{preview-domain}
• Respect the include_in_preview flag on environment variables
• Get their own isolated database within linked services
• Are soft-deleted when removed (and restored if the same branch is pushed again)

How isolation works

Each environment is fully isolated from the others:

Containers

Each environment runs its own set of Docker containers. A production deployment and a staging deployment are separate containers running different versions of the code (or the same code with different configuration).

Databases

When a managed PostgreSQL service is linked to a project, each environment gets a dedicated database:

postgres-my-db
  ├── my_app_production     (production environment)
  ├── my_app_staging         (staging environment)
  └── my_app_feature_login   (preview environment)

For Redis, each environment gets a dedicated database number (0-15). For S3/RustFS, each environment gets a dedicated bucket.

Environment variables

Variables can be scoped to specific environments. A variable set only for production is not visible in staging or previews. Auto-injected service variables (like POSTGRES_URL) use the environment-specific database name. See Manage environment variables for scoping and the include_in_preview flag.

Domains

Each environment has its own auto-assigned subdomain. Custom domains are added per environment. SSL certificates are provisioned independently.

Environment configuration

Each environment has its own deployment configuration:

Settings are updated at PUT /projects/{id}/environments/{id}/settings or via the dashboard under the environment's Settings tab.

Branch-to-environment mapping

Temps maps Git branches to environments:

Each branch can only be tracked by one active environment per project. If you create a staging environment tracking the develop branch, pushes to develop deploy to staging (not production).

Lifecycle

Creation

• Production: Created automatically when the project is created
• Manual environments: Created via the dashboard or API
• Preview environments: Created automatically on first push to a non-main branch

There is no default cap on the number of environments per project. You can create as many staging, QA, or preview environments as your workflow requires without hitting a hard limit.

If you need to restrict how many environments a project can have — for example to control resource usage — an admin can configure an optional environment count limit under the project's Settings page. This limit is disabled by default and only takes effect when explicitly set.

Soft deletion

When you delete an environment:

1. Running containers are stopped and removed
2. The environment record is marked with a deleted_at timestamp (soft delete)
3. Data in linked services (database, cache) is not deleted
4. If the same branch is pushed again, the environment is restored

Protection

The production environment cannot be deleted. This is enforced at the system level regardless of user role or permissions. Other environments can be deleted by users with the appropriate role.

Cleanup

Preview environments accumulate as branches are created. Clean them up manually from the Environments page or by using the Teardown action on individual deployments to free containers while keeping the environment record.

On-demand environments

On-demand mode (also called scale-to-zero) is an optional mode for non-production environments that have infrequent traffic. When enabled, the environment's containers are stopped after a configurable idle period and restarted automatically the first time a new request arrives.

When a request arrives for a sleeping environment, the proxy starts its containers, waits until the app answers HTTP on /, and then forwards the held request. If the wake is still pending or fails, the caller gets a 503 with a Retry-After header and a wake_pending or wake_failed status. The full wake sequence, timeouts and error responses are documented in Request flow — on-demand environments.

When to use on-demand mode

On-demand mode is suited for:

• Preview environments that are only accessed during active code review
• Staging environments with irregular or scheduled usage
• Internal tools and admin panels with low request frequency

On-demand mode is not recommended for production environments, where cold-start latency is unacceptable and containers must be ready at all times.

Related concepts

• Projects — the container for your environments, repository and linked services
• Deployments — how each push becomes a running version in an environment
• Resources — CPU, memory and replica settings per environment