dagger.toml

A workspace is configured by a dagger.toml file at its root. It records the modules installed in the workspace and their settings. dagger module install creates it on first install.

The machine-readable schema is published at dagger-workspace.schema.json.

Top level

Key	Type	Description
modules	table	Installed modules, keyed by install name. See [modules.<name>].
sdks	table	Installed SDK providers and their generation scopes. See [sdks.<name>].
ports	table	Host port mappings for services. See [ports.<name>].
ignore	array	Path patterns excluded when loading the workspace.
defaults_from_dotenv	bool	Read module constructor defaults from a .env file.
check-generated	bool	Run generators as checks during dagger check, failing when generated files are stale. Defaults to true; CLI flags override it.

Resolved image and Git lookups are pinned in dagger.lock alongside the config, and refreshed with dagger workspace update.

[modules.<name>]

[modules.eslint]
source = "dagger.io/js/eslint@v0.3.0"

[modules.eslint.settings]
packageManager = "yarn"

Key	Type	Description
source	string	Module address — a workspace-relative path, or a Git ref such as github.com/org/mod@version.
pin	string	Resolved version for source.
settings	table	Module settings. Keys are defined by the module; set them with dagger module settings.
entrypoint	bool	Marks this module as the workspace entrypoint.
legacy-default-path	bool	Compatibility flag recorded by workspace migration.
check	table	skip = [...] — check functions to exclude from dagger check.
generate	table	skip = [...] — generators to exclude from dagger generate.
up	table	skip = [...] — services to exclude from dagger up.

Settings can point at another module's output instead of a literal value — see Module wiring.

[sdks.<name>]

[modules.go-sdk]
source = "dagger.io/sdk/go"

[sdks.go]
module = "go-sdk"

[sdks.go.scopes.".dagger/modules/demo"]
is-module = true
name = "demo"
clients = ["github.com/acme/api"]

[sdks.go.scopes.".dagger/modules/demo".settings]
template = "default"

Key	Type	Description
module	string	Name of the installed module that provides this SDK.
scopes	table	Generation scopes, keyed by paths relative to dagger.toml.

Each scope can contain one module, module clients, or both. Client paths are relative to the directory containing dagger.toml. Use ./api, ../api, . or ..; a bare api is not a local path.

Scope key	Type	Description
is-module	bool	The scope contains a Dagger module.
name	string	Optional scope name. Overrides the inferred module name when is-module is true.
clients	array	Explicit local paths or module addresses for generated clients. Installed module names are not supported.
settings	table	SDK settings for this scope.

module init saves a scope name only when you set --name. It preserves an existing saved name. Before generation, an unnamed module scope uses the name of its local entrypoint installation, if one exists. Otherwise, it uses the scope directory name. A scope at the workspace root uses the config-parent or workspace name with -dev. Multiple matching entrypoint names require an explicit scope name. The inferred name is not written to this field.

Use dagger sdk scope name -u to remove an override. An unnamed scope that contains only clients passes an empty name to the SDK.

[ports.<name>]

Key	Type	Description
backendService	string	Service that backs this host port.
backendPort	int	Port on the backing service.

User-level file

The same module settings can be set per-user, outside the repository, in ~/.config/dagger/config.toml. See User configuration.