Environments

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

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 for finer slicing — for example, environment production plus tag payments.

Managing environments

Dashboard
CLI
YAML
Terraform

Open Settings → Environments.
Click Create Environment, choose a slug + display name, and optionally mark it as the default.
Add variables for any per-stage values you want to template into monitors and channels.

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.

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.

resource "devhelm_environment" "production" {
  name       = "Production"
  slug       = "production"
  is_default = true
  variables  = {
    BASE_URL = "https://api.example.com"
  }
}

See the 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

Multi-environment guide

End-to-end setup for prod / staging / dev YAML files.

Secrets

Store credentials for authenticated monitor checks.

environments CLI

Manage from the command line.

Getting Started

Monitoring as Code

Monitoring

Incidents

Alerting

Status Data

Platform

Common Patterns

Model

Common patterns

Per-stage URLs

Dashboard filtering

Managing environments

Lifecycle and constraints

Next steps

Multi-environment guide

Secrets

Tags

environments CLI

​Model

​Common patterns

​Per-stage URLs

​Dashboard filtering

​Managing environments

​Lifecycle and constraints

​Next steps

Multi-environment guide

Secrets

Tags

environments CLI

Model

Common patterns

Per-stage URLs

Dashboard filtering

Managing environments

Lifecycle and constraints

Next steps