> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Environments
> Organize DevHelm monitors and resources by environment — production, staging, development
Environments separate monitors and configuration by deployment stage so that a probe targeting `staging.example.com` lives alongside — but never collides with — its `production` counterpart. Environments power filtered dashboards and per-stage variable substitution at check time.
**Define this in code.** Environments live in `devhelm.yml` alongside monitors and tags. See [Tags & Secrets](/mac/yaml/tags-and-secrets#environments) for the YAML schema.
## Model
| Property | Notes |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`slug`** | URL-safe identifier (lowercase, hyphens). This is the stable reference used in monitor configs and CLI commands. Cannot be changed after creation. |
| **`name`** | Human-readable label shown in the dashboard. Safe to rename without breaking references. |
| **`isDefault`** | At most one environment per organization is marked default. Marking an environment as default clears the flag from the previous default. |
| **`variables`** | Map of string key/value pairs. Monitor configs reference them as `${ENV.VAR}` tokens, resolved by the probe **at check execution time** from the monitor's linked environment. |
## Common patterns
### Per-stage URLs
Define environments with a `BASE_URL` variable, then reference it from the monitor config with an `${ENV.VAR}` token. The probe substitutes the value from the monitor's linked environment on every check:
```yaml theme={null}
environments:
- name: Production
slug: production
isDefault: true
variables:
BASE_URL: https://api.example.com
- name: Staging
slug: staging
variables:
BASE_URL: https://staging-api.example.com
monitors:
- name: Health (production)
type: HTTP
environment: production
config:
url: $${ENV.BASE_URL}/health
method: GET
- name: Health (staging)
type: HTTP
environment: staging
config:
url: $${ENV.BASE_URL}/health
method: GET
```
Two things to note:
* In `devhelm.yml`, a plain `${...}` is CLI **shell-environment interpolation** applied at deploy time. To write a literal `${ENV.BASE_URL}` token into the deployed monitor config, escape the dollar sign as `$$` — the CLI turns `$${ENV.BASE_URL}` into `${ENV.BASE_URL}`.
* `${ENV.VAR}` tokens work in any string field of the monitor config (URL, custom header values, request body). Tokens referencing an unknown variable are left as-is.
Each monitor is pinned to one environment via its `environment` field — there is no deploy-time flag that re-targets a whole file at a different environment. To promote a config across stages, define one monitor entry per stage (as above) or maintain per-stage YAML files.
### Dashboard filtering
The monitor list (dashboard and `GET /api/v1/monitors?environmentId=...`) supports filtering by environment. Combine with [tags](/platform/tags) for finer slicing — for example, environment `production` plus tag `payments`.
## Managing environments
1. Open **Settings → Environments**.
2. Click **Create Environment**, choose a slug + display name, and optionally mark it as the default.
3. Add `variables` for any per-stage values you want to template into monitors and channels.
```bash theme={null}
devhelm environments list
devhelm environments create --name "Production" --slug production
devhelm environments update staging --name "Staging (US-East)"
devhelm environments delete legacy
```
Full reference: [`devhelm environments`](/cli/commands/environments).
```yaml theme={null}
environments:
- name: Production
slug: production
isDefault: true
variables:
BASE_URL: https://api.example.com
REGION: us-east
- name: Staging
slug: staging
variables:
BASE_URL: https://staging-api.example.com
REGION: eu-west
```
Deploy with `devhelm deploy -f devhelm.yml --yes`.
```hcl theme={null}
resource "devhelm_environment" "production" {
name = "Production"
slug = "production"
is_default = true
variables = {
BASE_URL = "https://api.example.com"
}
}
```
See the [Terraform overview](/mac/terraform/overview) for provider setup.
## Lifecycle and constraints
* **Slugs are immutable.** Updates can change `name`, `variables`, and `isDefault`, but never the slug. Renaming a slug requires creating a new environment, repointing monitors, then deleting the old one.
* **Deleting an environment is rejected** while active monitors still reference it (`ENVIRONMENT_DELETE_BLOCKED`). Repoint or delete those monitors first.
* **Environment count is plan-limited.** Exceeding the plan's maximum returns `ENVIRONMENT_LIMIT_REACHED`.
* **Variables are resolved at check execution time** by the probe, not baked into the config at deploy time. Updating a variable takes effect from the next check — no redeploy needed.
## Next steps
End-to-end setup for prod / staging / dev YAML files.
Store credentials for authenticated monitor checks.
Slice resources orthogonally to environments.
Manage from the command line.