Environments

Run the same app id once per environment, each copy with its own configuration, secrets and workers, under one organization and one bill.

Introduction

An environment is a named place inside your organization where apps run. The same app id can run in several of them, and each copy keeps its own configuration, its own versions, its own workers and its own secrets.

Every organization has production, and a request that names no environment addresses it. Nothing you have deployed so far moved: it is already there.

GET /v1/apps                        # production
GET /v1/apps?environment=staging    # the staging copies

One id, one copy per environment

The app id is the name of the application. The environment chooses which copy a request reaches, and the two are separate apps from there on: separate versions, separate workers, separate environment variables, separate secret attachments.

A copy is created where you first deploy it and never moves. Promoting what you tested is deploying the same source into another environment, which builds there. Deleting one copy leaves the others untouched.

Because a copy is its own app, an app id that runs in two environments counts as two apps everywhere you see a tally, and a cursor from a page of one environment is not valid in another.

What an environment holds

Scoped to the environment	Shared by the organization
Apps, their versions, workers and environment variables	The API key you authenticate with
Secrets, and the attachments that expose them	The GPU types you can deploy on
Worker and GPU caps, and the monthly budget	The source archives a deploy builds from

A secret of the same name in another environment is a different secret. There is no copy operation, because the API never returns a stored value: creating the same name in a second environment means sending the value again.

Caps and the monthly budget

An environment carries a cap on the workers it holds and a cap on their GPUs. Both are checked whenever a request adds capacity, so creating an app, deploying, resuming a stopped one and raising a worker count all go through them. They do not bound autoscaling: what is already running keeps scaling inside its own maxWorkers.

The count an environment is judged against is what its other apps hold, each the larger of its live workers and its keep-warm floor, plus what the request starts. A request that would cross a cap is refused and changes nothing. Lowering a cap below what already runs refuses the next deploy rather than stopping anything.

The monthly budget is a pay-as-you-go cap for the calendar month, which resets on the 1st at 00:00 UTC. Percentages you choose send an email as the spend passes them, each at most once per month. Where pauseAtBudget is on, reaching the budget stops the environment's apps and refuses invocations until the budget is raised past the spend or the month turns.

Spend is read from settlement, so it trails live usage by a few minutes, and a worker's final adjustment by longer. A budget is a cap on what gets billed, not a switch that trips the instant a GPU starts.

Organization defaults

Every cap and the access setting have an organization default that an environment inherits while it sets nothing of its own. An environment reports both: the value set on it, and under resolved the value actually in force.

Changing a default reaches every environment that inherits that field at once, and it does not roll what is already running.

GET /v1/environment-defaults
PUT /v1/environment-defaults

Creating and deleting

A name is 1 to 63 characters: lowercase letters, digits, hyphens, underscores and periods, starting with a letter or a digit. A name no live environment holds is free, including the name of one you deleted.

An environment is deleted only once it is empty, with no live app and no secret left in it. production is never deleted, and a deleted app's history still names the environment it ran in.

Where to go next

Core concepts for the nouns an environment holds
Secrets for what changes when the same name lives in two places
Compute and scaling for the worker settings a cap is checked against
Errors for the answers a cap and a pause give