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.
include	array of tables	Another config file whose contents are merged underneath this one. See [[include]].

dagger.lock

Resolved image, Git, and vanity URL lookups are pinned in dagger.lock alongside the config. A workspace with multiple dagger.toml files can therefore contain multiple lockfiles.

Run dagger lock update without selectors to refresh every supported entry in the selected lockfile. Selectors refresh matching resources:

dagger lock update node
dagger lock update 'node:lts*'
dagger lock update 'dagger@m*'
dagger lock update github.com/dagger/dagger@refs/heads/main

The node selector matches OCI references whose repository name is node, including docker.io/library/node:lts-alpine. The node:lts* pattern also matches the tag without requiring the registry path. Git identities omit the transport scheme and .git suffix. The dagger@m* pattern matches both refs/heads/main and refs/tags/main in repositories named dagger. A fully qualified ref selects only that branch or tag.

Shell-style patterns can match the full resource identity, and * spans /. Multiple selectors are ORed together, but each selector must match at least one entry. Quote patterns to keep the shell from expanding them:

dagger lock update '*node*' '*python*'

Use dagger lock list to print matching canonical identities without resolving or changing the lockfile. dagger lock update --list produces the same output, so an update can be checked and then applied by removing --list:

dagger lock list dagger
dagger lock update --list dagger
dagger lock update dagger

[[include]]

[[include]]
source = "../common"

Key	Type	Description
source	string	Config file to inherit from — a workspace-relative path, or a Git ref such as github.com/org/base@version. A source with no file extension names a directory and reaches the dagger.toml inside it.

The included config is merged underneath this one, so this workspace wins every conflict, and its own modules come with it. Only one [[include]] is resolved for now. See Includes.

[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.
main	bool	Marks this module as the workspace main.
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 start.

The deprecated entrypoint key remains accepted as an alias for main. Dagger rewrites it to main the next time it edits the configuration.

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 main 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 main 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.