Environments

An environment is a named overlay on top of your workspace configuration. Use environments when the same checks, generators, or services need different settings in different contexts — for example a different base image in staging than in production.

Environments are path prefixes in your workspace configuration (env.<name>.* in dagger.toml). They aren't first-class commands; you create one implicitly by writing to its overlay, list them by inspecting workspace config, and remove one by deleting the keys.

Apply an environment

Pass --env to any command to apply an overlay for that run:

dagger --env staging check
dagger --env staging api call deploy

Configure an environment

Most per-environment differences are module settings — a base image, a package manager. Set them with dagger settings and --env, which targets that environment's overlay instead of the base configuration:

dagger settings --env staging eslint baseImageAddress node:22-alpine

Writing to a setting under --env=<name> is also how the environment gets created. The first write creates the overlay; subsequent writes update it.

Reads with --env show the effective view — the base settings with the overlay applied:

dagger settings --env staging eslint

Without --env, you read and write the base configuration, which every environment inherits.

Lower-level access

dagger workspace config is the lower-level key/value interface to dagger.toml, and it follows the same --env overlay rules. Environment overlays only carry module settings, so the raw key form is:

dagger workspace config env.staging.modules.<module>.settings.<key> <value>