Skip to main content
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.

​
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

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

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.
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 an environment as protected to put deploys and moves behind approval:
Turning protection on or off works without the experimental flag. Deploys to a protected environment already needed confirmation and approval, and that has not changed.

​
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:
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

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.
Last modified on October 12, 2026