Environments

An environment labels where an app or database runs: development, test, UAT, production, or one you define. Environments are instance-wide, so the same four are available to every project. Tagging resources with an environment lets you filter the dashboard, protect production, and write access rules per environment.

Creating and renaming environments, the switcher and the database move route are behind the global-environments experimental flag: set APP_EXPERIMENTAL=global-environments on the control plane (see Experimental features). Existing per-project environments keep working with or without it.

Built-in environments

Four environments exist on every instance and cannot be deleted.

Name	Kind	Protected
Development	dev	No
Test	test	No
UAT	uat	No
Production	production	Yes

Kinds

Every environment has a kind: dev, test, uat, production, preview or custom. Kinds are what IAM policies and AI control match on, so a rule like "deny deploys on environment-kind:production" covers every production-kind environment, whatever its name.

preview is reserved for the environments Levelrail creates for pull request previews. You cannot create one, and you cannot change an environment to or from that kind.

Create and manage

levelrail-cli environments list
levelrail-cli environments create --name Staging --kind custom --sort-order 25
levelrail-cli environments update env_abc --name "Pre-prod" --kind uat --protected
levelrail-cli environments update env_abc --protected=false
levelrail-cli environments delete env_abc --move-to env_dev

In the dashboard, open Settings, Environments. The list shows each environment's kind, whether it is protected, and how many apps and databases it holds.

Deleting:

• A built-in environment cannot be deleted (403).
• An environment that still has apps or databases cannot be deleted (409) unless you pass --move-to, which moves them to another environment first.
• A bulk move with --move-to is refused if the source or the destination is protected. Move those one at a time so each gets its approval.

Move an app or database

levelrail-cli apps move-env myapp env_dev
levelrail-cli databases move-env mydb env_dev

Pass an empty id ("") to remove the tag. In the dashboard, use the Change button next to the environment on the app's Overview.

A move into or out of a protected environment works differently:

1. Without --confirm the request is refused with 409 and nothing changes.
2. With --confirm it becomes a pending approval instead of moving right away.
3. A different person with the deploy ability approves it (Deploy approvals, or levelrail-cli deploy-approvals). The person who asked cannot approve their own request.
4. Only then does the app or database move.

levelrail-cli apps move-env myapp env_production --confirm

A move during a deploy freeze is refused with 423 unless you pass the freeze override. If the environment an app is leaving cannot be read, the move is refused rather than assumed unprotected.

Protection

Mark any environment as protected to put deploys and moves behind approval:

levelrail-cli environments update env_abc --protected

Turning protection on or off works without the experimental flag. Deploys to a protected environment already needed confirmation and approval before this release, and that is unchanged.

Switcher and filters

With the flag on, the dashboard header has an environment switcher. Choosing an environment filters the apps, databases, deployments and approvals lists, and the choice is remembered in your browser and reflected in the URL as ?environment=.

The same filter works on the API and CLI. It accepts an environment id or name:

curl -H "Authorization: Bearer $TOKEN" "https://<control-plane>/api/v1/apps?environment=production"
levelrail-cli apps list --environment production
levelrail-cli databases list --environment production

The approvals list filters by environment id only.

Environment variables

Per-environment variables and secrets work for these environments the same way they do for project environments. See Projects and organizations if you use per-project environments too.

API

Method	Path	Ability
GET	/api/v1/environments	read
POST	/api/v1/environments	write
PATCH	/api/v1/environments/{id}	write
DELETE	/api/v1/environments/{id}	write
PUT	/api/v1/apps/{name}/environment	write
PUT	/api/v1/databases/{name}/environment	write

Create takes {"name", "kind", "protected", "sort_order"}. A move takes {"environment_id", "confirm", "override_freeze", "override_reason"} and answers 409 (needs confirmation), 202 with a pending approval, 423 (freeze) or 200.

Next steps

Access control

Roles, guest visibility and policies per environment.

AI control

Limit agents to chosen environment kinds.