Overview
Both dbt flow types and the Materialize Git Repository flow can be assigned to a compatible Integration Agent — no agent-specific flow type is needed. Running dbt on an agent places execution next to a private warehouse: credentials and warehouse traffic never leave your network.
Requires Etlworks 9.9.9 and Integration Agent 9.9.9 or later.
What runs where
- Execute dbt Project (local dbt Core): everything stays on the agent — the dbt process, project directory, Git materialization, package cache, generated profile, credentials, environment, state files, temporary work, and all warehouse network traffic. There is no fallback to the Etlworks host: if the agent cannot run the work, the execution fails with a clear error instead of silently running elsewhere.
- Execute dbt Platform Job: the agent invokes and monitors the dbt Platform API. A local dbt installation is not required on the agent for Platform jobs.
Results, logs, artifacts, cancellation, and provenance keep the same contract as host execution — the dbt Results tab looks identical regardless of where the flow ran. All integration capabilities work on capable agents: local and Git projects, private Git, packages and cache, Dynamic connections, variables, environment values, secrets, state and defer, native retry, run-operation, nesting, Composer, loops, schedules, API, CLI, multiple invocations, lineage, and cancellation.
Prerequisites on the agent host
For local dbt Core, install on the agent machine (Etlworks does not install these automatically): dbt Core 1.12.3, the dbt adapter for your warehouse, Git (for Git-backed projects), and — for SQL Server, Synapse, or Fabric — unixODBC and Microsoft ODBC Driver 18. See Get started with dbt in Etlworks.
Agent parameters
Physical locations are configured per agent in the agent's parameters, dbt section:
| Parameter | Default | Purpose |
|---|---|---|
| dbt Executable (dbt.executable) | dbt | Executable name or absolute path to dbt on this agent |
| dbt Project Root (dbt.project.root) | {app.data}/dbt | Root directory for local dbt projects on this agent |
| dbt Package Cache Root (dbt.package.cache.root) | {app.data}/dbt_cache/packages | Shared dbt package cache on this agent |
| Git Executable (git.executable) | git | Git executable for Git-backed dbt projects and Git flows |
| Git Work Root (git.work.root) | {app.data}/git | Root directory for Git materializations on this agent |
{app.data} resolves on the agent, including for the root account. The dbt work directory is created below the agent's temporary folder and is not a setting.
Host global and tenant settings remain the policy inputs — quotas, size limits, retention, dependency timeout, lock policy, and network policy. They do not replace the agent-local executable and filesystem roots above.
Capability negotiation and upgrades
A dbt-capable agent advertises its capabilities to the host. The compatibility contract:
- A new host keeps sending non-dbt work to older agents — nothing breaks by upgrading the host first.
- The host never sends an older agent unknown dbt or Git tasks, dbt-only parameters, state files, or artifact messages.
- An incompatible agent is rejected before dbt dispatch, with an error that includes upgrade guidance.
- Upgrade order: deploy the new host first, then upgrade the agent. Before rolling an agent back, remove or disable its dbt flow assignments.
State and artifact transfer
State, defer, and retry files travel to the agent — and structured results and raw artifacts travel back — over an authenticated, execution-bound transfer channel. Every file is validated for identity, size, and SHA-256 checksum, published atomically, and cleaned up afterward; identical replays are acknowledged, conflicts are rejected, and partial or corrupt files are never published. Failed uploads are retried from a bounded spool. None of this requires configuration — it is the built-in contract.
Cancellation
Cancelling a local dbt execution terminates the dbt process tree on the agent and cleans up temporary profiles, credentials, workspaces, and transfer directories. For Platform jobs, the agent requests remote cancellation with the same confirmed/requested/uncertain outcomes as host execution.