Workspace
API reference
A Dagger workspace detected from the current working directory or constructed from a Directory.
Implements Node
address- Canonical Dagger address of the workspace location, or an opaque identity for synthetic workspaces.
configFile- Selected native workspace config file relative to the workspace cwd, if any.
configRead- Read a configuration value from dagger.toml.
cwd- Current location within the workspace root.
detectScope- Return the selected SDK module's current scope at this workspace location.
entrypoint- Installed name of the module selected as the workspace entrypoint, or an empty string when none is selected.
envList- List named environments defined in the workspace configuration.
export- Write this workspace's pending changes to its local Git workspace on the current client's host.
findRoots- Find project roots marked by any of the given filenames, starting from a path relative to the workspace cwd.
findUp- Search for a file or directory by walking up from the start path within the workspace.
glob- Returns a list of files and directories that match the given pattern.
id- A unique identifier for this Workspace.
agents- Return all agent middlewares from modules loaded in the workspace.
changes- Return this workspace's changes, with paths relative to its working directory.
checks- Return all checks from modules loaded in the workspace.
directory- Returns a Directory from the workspace.
file- Returns a File from the workspace.
generators- Return all generators from modules loaded in the workspace.
git- Git state for this workspace. Errors if the workspace is not in a git repository.
migrate- Plan the explicit migration needed for the current workspace.
migrateModule- Plan migration of one local module without migrating its dependencies or creating a workspace configuration.
module- Return a module defined in the workspace configuration.
modules- List modules defined in the workspace configuration.
moduleSource- Load a module source from a path within the workspace.
reloaded- Return this workspace with its cached host reads invalidated, so subsequent file and directory reads re-read the live host instead of a snapshot cached earlier in the session.
sdk- An installed SDK, by name.
sdks- Installed SDKs.
search- Searches for content matching the given regular expression or literal string.
services- Return all services from modules loaded in the workspace.
terminals- Return all terminal targets from modules loaded in the workspace.
withChanges- Return this workspace with a changeset applied, without mutating the source.
withClient- Return this workspace with a generated module client added to one SDK scope.
withConfigEnv- Return this workspace with a named config environment created.
withConfigValue- Return this workspace with a configuration value written.
withDirectory- Return this workspace with a directory merged into the given path, without mutating the source.
withEntrypoint- Return this workspace with an installed module selected as its entrypoint.
withFile- Return this workspace with a file added or replaced, without mutating the source.
withInitialized- Return this workspace with a native configuration, without changing an existing configuration.
withInitModule- Return this workspace with a location initialized as a module scope.
withModule- Return this workspace with a module installed in its config.
withMountedDirectory- Return this workspace with a directory mounted read-only at the given path, without mutating the source.
withMountedFile- Return this workspace with a file mounted read-only at the given path, without mutating the source.
withNewDirectory- Return this workspace with the given path replaced by a directory, without mutating the source.
withNewFile- Return this workspace with a new or replaced file, without mutating the source.
withoutClient- Return this workspace with a module client removed from the deepest matching recorded scope.
withoutConfigEnv- Return this workspace with a named config environment removed.
withoutConfigValue- Return this workspace with a configuration value removed.
withoutDirectory- Return this workspace with a directory removed, without mutating the source.
withoutEntrypoint- Return this workspace with no module selected as its entrypoint.
withoutFile- Return this workspace with a file removed, without mutating the source.
withoutModule- Return this workspace with a module removed from its config.
withoutSDK- Return this workspace with an SDK removed from its config.
withSDK- Return this workspace with an SDK installed in its config.
withUpdatedClients- Return this workspace with the selected module clients updated.
withUpdatedLock- Return this workspace with refreshed lockfile state.
withUpdatedModules- Return this workspace with updated module versions and lockfile state.
withWorkdir- Return this workspace with its working directory pointed at the given workspace-relative path.
address: String!
Canonical Dagger address of the workspace location, or an opaque identity for synthetic workspaces.
configFile: String!
Selected native workspace config file relative to the workspace cwd, if any.
configRead(key: String = ""): String!
Read a configuration value from dagger.toml.
If key is empty, returns the full config.
If key points to a scalar, returns the value.
If key points to a table, returns flattened dotted-key output.
key: String = ""Dotted key path (e.g. modules.greeter.source). Empty for full config.
cwd: String!
Current location within the workspace root.
The workspace root is returned as "/".
Relative paths in workspace APIs resolve from here.
detectScope(sdk: String!): String!
Return the selected SDK module's current scope at this workspace location.
sdk: String!SDK name to probe. Required.
entrypoint: String!
Installed name of the module selected as the workspace entrypoint, or an empty string when none is selected.
Reflects the selected env's effective view. Fails if several modules are selected.
envList: [String!]!
List named environments defined in the workspace configuration.
export: Void!
Write this workspace's pending changes to its local Git workspace on the current client's host.
Like Directory.export, the write is a side effect on the client that makes the call — never on the client that created the workspace. Inside a module, this cannot reach the caller's host.
findRoots(start: String = ".",markers: [String!]!,exclude: [String!] = []): [String!]!
Find project roots marked by any of the given filenames, starting from a path relative to the workspace cwd.
Returns cwd-relative directory paths for every marked directory at or below start, plus the nearest marked ancestor when start itself is not marked.
Each returned path is usable as-is with other workspace APIs, e.g. directory(path).
start: String = "."Directory to start from. Relative paths resolve from the workspace cwd.
markers: [String!]!File basenames that mark a project root (e.g. ["go.mod"] or ["deno.json", "deno.jsonc"]).
exclude: [String!] = []Glob patterns pruning the walk below start (e.g. ["/node_modules/"]).
findUp(name: String!, from: String = "."): String
Search for a file or directory by walking up from the start path within the workspace.
Returns the absolute workspace path if found, or null if not found.
Relative start paths resolve from the workspace cwd.
The search stops at the workspace root and will not traverse above it.
name: String!The name of the file or directory to search for.
from: String = "."Path to start the search from. Relative paths resolve from the workspace cwd; absolute paths resolve from the workspace root.
glob(pattern: String!): [String!]!
Returns a list of files and directories that match the given pattern.
Patterns match paths relative to the workspace root.
pattern: String!Pattern to match (e.g., "*.md").
id: ID!
A unique identifier for this Workspace.
agents(include: [String!]): AgentGroup!
Return all agent middlewares from modules loaded in the workspace.
include: [String!]Only include agents matching the specified patterns
changes(from: Workspace): Changeset!
Return this workspace's changes, with paths relative to its working directory.
Pass from to compare against an earlier workspace state. Omitting it preserves the cumulative behavior used by clients from before this argument was added.
from: WorkspaceAn earlier workspace state to compare against.
checks(include: [String!],skip: [String!],noGenerate: Boolean,onlyGenerate: Boolean): CheckGroup!
Return all checks from modules loaded in the workspace.
include: [String!]Only include checks matching the specified patterns
skip: [String!]Skip checks matching the specified patterns
noGenerate: BooleanWhen true, only return annotated check functions; exclude generate-as-checks
onlyGenerate: BooleanWhen true, only return generate-as-checks; exclude annotated check functions
directory(path: String!,exclude: [String!] = [],include: [String!] = [],gitignore: Boolean = false): Directory!
Returns a Directory from the workspace.
Relative paths resolve from the workspace cwd. Absolute paths resolve from the workspace root.
path: String!Location of the directory to retrieve. Relative paths (e.g., "src") resolve from the workspace cwd; absolute paths (e.g., "/src") resolve from the workspace root.
exclude: [String!] = []Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).
include: [String!] = []Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).
gitignore: Boolean = falseApply .gitignore filter rules inside the directory.
file(path: String!): File!
Returns a File from the workspace.
Relative paths resolve from the workspace cwd. Absolute paths resolve from the workspace root.
path: String!Location of the file to retrieve. Relative paths (e.g., "go.mod") resolve from the workspace cwd; absolute paths (e.g., "/go.mod") resolve from the workspace root.
generators(include: [String!]): GeneratorGroup!
Return all generators from modules loaded in the workspace.
include: [String!]Only include generators matching the specified patterns
git: WorkspaceGit!
Git state for this workspace. Errors if the workspace is not in a git repository.
migrate(modules: [String!] = []): WorkspaceMigration!
Plan the explicit migration needed for the current workspace.
Include installed local modules and their local dependencies. Other module candidates remain unchanged unless selected.
The returned plan has an empty changeset and no steps when no migration is needed.
modules: [String!] = []Additional local modules to migrate. Relative paths start at the workspace cwd; absolute paths start at the workspace root.
migrateModule(path: String = "."): WorkspaceMigration!
Plan migration of one local module without migrating its dependencies or creating a workspace configuration.
Include SDK registration when a workspace configuration exists and remove obsolete generated-file ignore rules.
path: String = "."Module directory. Relative paths start at the workspace cwd; absolute paths start at the workspace root.
module(name: String!): WorkspaceModule!
Return a module defined in the workspace configuration.
Reflects the selected env's effective view.
name: String!Module name to inspect.
modules: [WorkspaceModule!]!
List modules defined in the workspace configuration.
Reflects the selected env's effective view.
moduleSource(path: String!): ModuleSource!
Load a module source from a path within the workspace.
Relative paths (e.g., "foo") resolve from the workspace cwd; absolute paths (e.g., "/foo") resolve from the workspace root.
Fails if the path does not point to an initialized module.
path: String!Location of the module source to load, relative to the workspace cwd or absolute from the workspace root.
reloaded: Workspace!
Return this workspace with its cached host reads invalidated, so subsequent file and directory reads re-read the live host instead of a snapshot cached earlier in the session.
sdk(name: String!): WorkspaceSDK!
An installed SDK, by name.
name: String!SDK name to look up.
sdks: [WorkspaceSDK!]!
Installed SDKs.
search(paths: [String!] = [],globs: [String!] = [],pattern: String!,literal: Boolean = false,multiline: Boolean = false,dotall: Boolean = false,insensitive: Boolean = false,skipIgnored: Boolean = false,skipHidden: Boolean = false,filesOnly: Boolean = false,limit: Int): [SearchResult!]!
Searches for content matching the given regular expression or literal string.
Uses Rust regex syntax; escape literal ., [, ], {, }, | with backslashes.
Runs ripgrep on the client host, falling back to grep if unavailable.
paths: [String!] = []Directory or file paths to search
globs: [String!] = []Glob patterns to match (e.g., "*.md")
pattern: String!The text to match.
literal: Boolean = falseInterpret the pattern as a literal string instead of a regular expression.
multiline: Boolean = falseEnable searching across multiple lines.
dotall: Boolean = falseAllow the . pattern to match newlines in multiline mode.
insensitive: Boolean = falseEnable case-insensitive matching.
skipIgnored: Boolean = falseHonor .gitignore, .ignore, and .rgignore files.
skipHidden: Boolean = falseSkip hidden files (files starting with .).
filesOnly: Boolean = falseOnly return matching files, not lines and content
limit: IntLimit the number of results to return
services(include: [String!]): UpGroup!
Return all services from modules loaded in the workspace.
include: [String!]Only include services matching the specified patterns
terminals(include: [String!]): TerminalGroup!
Return all terminal targets from modules loaded in the workspace.
include: [String!]Only include terminal targets matching the specified patterns
withChanges(changes: Changeset!): Workspace!
Return this workspace with a changeset applied, without mutating the source.
changes: Changeset!Changes to apply.
withClient(module: String!,sdk: String = "",settings: JSON): Workspace!
Return this workspace with a generated module client added to one SDK scope.
Select the deepest detected or registered scope. Fail if several SDKs have that deepest scope.
module: String!Explicit local path or module address to generate a client for. Installed module names are not supported.
sdk: String = ""Optional SDK name. Inspect all installed SDKs when omitted.
settings: JSONExplicit SDK-module constructor setting overrides for this scope. Requires an explicit SDK name.
withConfigEnv(name: String!, here: Boolean = false): Workspace!
Return this workspace with a named config environment created.
name: String!Environment name.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
withConfigValue(key: String!,value: String!,values: [String!],here: Boolean = false): Workspace!
Return this workspace with a configuration value written.
When the session selects an env, the key is scoped to that env's overlay and the env is created if missing.
key: String!Dotted key path.
value: String!Value to set. Bools, integers, and comma-separated arrays are auto-detected.
values: [String!]List value to set. Elements are stored verbatim, with no auto-detection. Mutually exclusive with value.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
withDirectory(path: String!, source: Directory!): Workspace!
Return this workspace with a directory merged into the given path, without mutating the source.
Anything already at the path stays, and files the source carries win, as with Directory.withDirectory. Use withNewDirectory to replace the path instead.
path: String!Path to merge into. Relative paths resolve from the workspace cwd.
source: Directory!Directory to merge there.
withEntrypoint(name: String!): Workspace!
Return this workspace with an installed module selected as its entrypoint.
Every other entrypoint selection is cleared. Entrypoints live in the base workspace config.
name: String!Exact installed module name.
withFile(path: String!,source: File!,permissions: Int): Workspace!
Return this workspace with a file added or replaced, without mutating the source.
path: String!Destination path. Relative paths resolve from the workspace cwd.
source: File!File to add.
permissions: IntPermissions of the added file. Defaults to the source file permissions.
withInitialized: Workspace!
Return this workspace with a native configuration, without changing an existing configuration.
Fail if legacy configuration needs workspace migration.
withInitModule(sdk: String!,name: String = "",path: String = "",install: Boolean,entrypoint: Boolean,settings: JSON): Workspace!
Return this workspace with a location initialized as a module scope.
The selected SDK module records the scope and generates the module source.
sdk: String!Workspace SDK name or module entry name to use. Required.
name: String = ""Module name. The engine infers it from path, the active config file, or the workspace root when omitted.
path: String = ""Module path relative to the workspace cwd, or an absolute workspace path. Defaults to .dagger/modules/<name> beside the active workspace config.
install: BooleanInstall the module. When omitted, install only if path is omitted.
entrypoint: BooleanSelect this module as the entrypoint and install it. False prevents automatic selection. When omitted, select only if both path and name are omitted and the module is installed.
settings: JSONExplicit SDK-module constructor setting overrides for this scope.
withModule(ref: String!,name: String = "",here: Boolean = false): Workspace!
Return this workspace with a module installed in its config.
When the session selects an env, the module is recorded in that env's overlay and the env is created if missing.
ref: String!Module reference to install.
name: String = ""Override name for the installed module entry.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
withMountedDirectory(path: String!, source: Directory!): Workspace!
Return this workspace with a directory mounted read-only at the given path, without mutating the source.
Mounted content is readable through the normal workspace file tools but shadows the source at the mount path and stays out of the pending changeset: it never appears in changes, is never exported, and cannot be modified.
path: String!Location of the mounted directory. Relative paths resolve from the workspace cwd.
source: Directory!Directory to mount.
withMountedFile(path: String!, source: File!): Workspace!
Return this workspace with a file mounted read-only at the given path, without mutating the source.
Mounted content is readable through the normal workspace file tools but shadows the source at the mount path and stays out of the pending changeset: it never appears in changes, is never exported, and cannot be modified.
path: String!Location of the mounted file. Relative paths resolve from the workspace cwd.
source: File!File to mount.
withNewDirectory(path: String!, source: Directory!): Workspace!
Return this workspace with the given path replaced by a directory, without mutating the source.
The source becomes the entire contents of the path: anything already there that the source does not carry is removed. Use withDirectory to keep it instead.
path: String!Path to replace. Relative paths resolve from the workspace cwd.
source: Directory!Directory to write there.
withNewFile(path: String!,contents: String!,permissions: Int = 420): Workspace!
Return this workspace with a new or replaced file, without mutating the source.
path: String!Path of the new file. Relative paths resolve from the workspace cwd.
contents: String!Contents of the new file.
permissions: Int = 420Permissions of the new file.
withoutClient(module: String!, sdk: String = ""): Workspace!
Return this workspace with a module client removed from the deepest matching recorded scope.
Fail if several SDKs have that deepest scope. The selected SDK module regenerates the complete scope.
If invalid client targets remain, save the removal and skip generation until those targets are corrected or removed.
module: String!The recorded target to remove.
sdk: String = ""Optional SDK name. Search all installed SDKs when omitted.
withoutConfigEnv(name: String!, here: Boolean = false): Workspace!
Return this workspace with a named config environment removed.
name: String!Environment name.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
withoutConfigValue(key: String!, here: Boolean = false): Workspace!
Return this workspace with a configuration value removed.
Errors when the key is not currently set.
When the session selects an env, the key is scoped to that env's overlay.
key: String!Dotted key path (e.g. modules.greeter.settings.greeting).
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
withoutDirectory(path: String!): Workspace!
Return this workspace with a directory removed, without mutating the source.
path: String!Path of the directory to remove. Relative paths resolve from the workspace cwd.
withoutEntrypoint: Workspace!
Return this workspace with no module selected as its entrypoint.
withoutFile(path: String!): Workspace!
Return this workspace with a file removed, without mutating the source.
path: String!Path of the file to remove. Relative paths resolve from the workspace cwd.
withoutModule(name: String!, here: Boolean = false): Workspace!
Return this workspace with a module removed from its config.
When the session selects an env, only that env's overlay entry is removed.
name: String!Installed module name or source to remove. Version selectors are not accepted.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
withoutSDK(name: String!, here: Boolean = false): Workspace!
Return this workspace with an SDK removed from its config.
name: String!Name of the installed SDK entry to remove.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
withSDK(ref: String!,name: String = "",here: Boolean = false,asSdkName: String = ""): Workspace!
Return this workspace with an SDK installed in its config.
ref: String!SDK module reference to install.
name: String = ""Override name for the installed SDK entry.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
asSdkName: String = ""Optional override for the SDK name conventionally derived from the installed module name.
withUpdatedClients(modules: [String!] = [],all: Boolean = false,sdk: String = ""): Workspace!
Return this workspace with the selected module clients updated.
The engine re-reads the source of each selected client target and writes the lock entries that those targets reach.
The selected SDK module then regenerates every scope that owns one of the targets.
modules: [String!] = []Recorded client targets to update. All targets in the selected scopes are updated when omitted.
all: Boolean = falseSelect clients in every scope instead of only the scopes containing the workspace cwd.
sdk: String = ""Optional SDK name. All installed SDK modules are selected when omitted.
withUpdatedLock(noGenerate: Boolean = false): Workspace!
Return this workspace with refreshed lockfile state.
SDK client scopes are regenerated unless noGenerate is true.
noGenerate: Boolean = falseDo not regenerate SDK client scopes.
withUpdatedModules(names: [String!] = [], version: String = ""): Workspace!
Return this workspace with updated module versions and lockfile state.
An SDK client scope is regenerated when it targets an updated module.
names: [String!] = []Installed module names or sources. A version suffix sets a new request. An empty list refreshes all installed modules.
version: String = ""New version request for exactly one selected module. Cannot be combined with a version suffix.
withWorkdir(path: String!): Workspace!
Return this workspace with its working directory pointed at the given workspace-relative path.
path: String!Workspace-relative path to use as the working directory.
References
Returned by
Address.workspaceDirectory.asWorkspaceGeneratorGroup.workspaceGitRef.asWorkspaceGitRepository.asWorkspaceLLM.workspaceModuleSource.generateQuery.currentWorkspace