Skip to main content

User configuration

Some values shouldn't be committed: private account profiles, local paths, personal development clusters. Those live in your user-level Dagger config file, config.toml in the dagger directory under the user config directory, or the file named by $DAGGER_CONFIG. The user config directory is $XDG_CONFIG_HOME when it is set. Otherwise it is ~/.config on Linux, ~/Library/Application Support on macOS, and %LOCALAPPDATA% on Windows.

The file is shared with other Dagger subsystems (such as [llm]). Workspace overrides sit in a [workspaces.*] section, keyed by the workspace's Git remote:

# Always applied when working in the github.com/acme/api workspace:
[workspaces."github.com/acme/api".modules.aws.settings]
profile = "alice-dev"

Merge order​

Dagger merges your user-level overrides on top of the repository's dagger.toml, which in turn sits on top of any config the repository includes. User-level values shadow repository values key by key, without modifying dagger.toml.

Writing values​

You don't have to edit the file by hand. Pass -g/--global to dagger module settings or dagger workspace config to store a value user-level instead of in the repository:

dagger module settings -g aws profile alice-dev             # always applied here
dagger module settings -g -u aws profile                    # remove the override
dagger workspace config -g modules.aws.settings.profile alice-dev

--global selects where a write is stored; reads always show the effective merged view. Unsetting with -g removes only the user-level value. The repository value underneath is untouched.

-g also composes with -W. A remote workspace is readable but its repository config can't be written, while its user-level overrides live in your local file:

dagger -W https://github.com/acme/api settings -g aws profile alice-dev

What can be stored​

Workspace overrides hold module settings, always applied (modules.<name>.settings.*) or scoped to an environment (env.<env>.modules.<name>.settings.*). These are the keys -g writes. A hand-written source, with an optional pin, adds or replaces a module, and a user environment is merged over a repository environment of the same name.

Because one key spans every branch and clone of a repository, an entry for a module that doesn't exist in the current checkout, and has no source, is ignored there rather than being an error.

Workspace key​

The key is the normalized origin remote: host and path, with no scheme, no user, and no .git suffix. Equivalent spellings all match: git@github.com:acme/api.git, https://github.com/acme/api, and github.com/acme/api identify the same workspace, both as the config key and in the repository's git config.

A repository with multiple remotes is keyed by origin only; a repository with no remote matches no user-level overrides. Remote workspaces selected with -W are keyed by their clone address.

Old engines​

A Dagger CLI that starts its engine container removes engine containers of other Dagger versions. To keep them, for example when several CLI versions share one host, set:

[engine]
leave_old_engines = true

The DAGGER_LEAVE_OLD_ENGINE environment variable, when set, takes precedence over this setting. The setting takes precedence over the cleanup parameter of an image:// engine URL.