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, such as a base image or 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>

Personal overrides

Values that shouldn't be committed, such as private profiles, local paths, and personal clusters, belong in your user configuration, which can also define environments of its own on top of the repository's.