Artifacts

DAG run artifacts are arbitrary files written by a DAG run. They are separate from logs, step outputs, and managed documents.

Dagu stores artifacts only when the DAG enables artifact storage.

DAG Configuration

Use the artifacts block at the root of a DAG:

name: daily-report

artifacts:
  enabled: true

steps:
  - id: generate-report
    command: |
      mkdir -p "${DAG_RUN_ARTIFACTS_DIR}/reports"
      cat > "${DAG_RUN_ARTIFACTS_DIR}/reports/summary.md" <<'EOF'
      # Daily Report

      Generated by Dagu.
      EOF

Supported fields:

Field	Type	Description
artifacts.enabled	boolean	Enables per-run artifact storage. Artifact storage stays disabled unless this is true.
artifacts.dir	string	Optional base directory for this DAG's artifacts. When omitted, Dagu uses the global paths.artifact_dir.

artifacts.dir alone does not enable artifact storage. Set artifacts.enabled: true.

Global Configuration

The global base directory is configured in config.yaml:

paths:
  artifact_dir: /var/lib/dagu/artifacts

Environment variable:

export DAGU_ARTIFACT_DIR=/var/lib/dagu/artifacts

Default:

<paths.data_dir>/artifacts

If a DAG sets artifacts.dir, that DAG-specific base directory is used instead of paths.artifact_dir.

Directory Layout

Artifact directories use the same per-run layout as log_dir:

<base>/<safe dag name>/dag-run_<YYYYMMDD_HHMMSSZ>_<dag-run-id>/

Example:

/var/lib/dagu/artifacts/daily-report/dag-run_20260412_031500Z_run-123/

The resolved path for the current run is also stored in DAG run status as archiveDir.

Runtime Variable

When artifact storage is enabled, Dagu sets DAG_RUN_ARTIFACTS_DIR for steps and lifecycle handlers.

steps:
  - id: write-files
    command: |
      test -n "${DAG_RUN_ARTIFACTS_DIR}"
      mkdir -p "${DAG_RUN_ARTIFACTS_DIR}/images"
      printf 'hello\n' > "${DAG_RUN_ARTIFACTS_DIR}/hello.txt"
      cp ./chart.png "${DAG_RUN_ARTIFACTS_DIR}/images/chart.png"

Execution mode behavior:

• Local execution writes directly into the final artifact directory.
• Distributed execution with a shared filesystem also writes directly into the final artifact directory.
• Distributed shared-nothing workers write into a worker-local staging directory first. Dagu uploads those files back to the coordinator, and the run's archiveDir points at the coordinator-side directory.

Web UI

The DAG run details page shows an Artifacts tab when the DAG enables artifact storage or the run already has an archiveDir. The tab uses a file tree on the left and a preview pane on the right.

Supported actions:

• Browse directories and files
• Download any file
• Preview markdown
• Preview text files
• Preview image files

Preview behavior:

• Markdown and text preview up to 2 MiB
• Image preview up to 5 MiB
• Binary files are download-only
• Files over the inline preview limit show metadata only and must be downloaded

The artifact browser ignores symlink entries.

API

Root DAG run endpoints:

• GET /api/v1/dag-runs/{name}/{dagRunId}/artifacts
• GET /api/v1/dag-runs/{name}/{dagRunId}/artifacts/preview?path=...
• GET /api/v1/dag-runs/{name}/{dagRunId}/artifacts/download?path=...

Sub DAG run endpoints:

• GET /api/v1/dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}/artifacts
• GET /api/v1/dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}/artifacts/preview?path=...
• GET /api/v1/dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}/artifacts/download?path=...

Example:

curl "http://localhost:8080/api/v1/dag-runs/daily-report/run-123/artifacts"

curl "http://localhost:8080/api/v1/dag-runs/daily-report/run-123/artifacts/preview?path=reports/summary.md"

curl -OJ "http://localhost:8080/api/v1/dag-runs/daily-report/run-123/artifacts/download?path=reports/summary.md"

The preview response reports:

Field	Description
kind	One of markdown, text, image, or binary
mimeType	Detected MIME type
size	File size in bytes
tooLarge	true when the file exceeds the inline preview limit for its kind
content	Inline content for markdown and text previews only

Cleanup

Artifact directories are deleted together with the corresponding DAG run during DAG run cleanup, including history-retention cleanup for root and sub-DAG runs.

Artifacts vs Outputs vs Documents

Feature	Stored As	Scope	UI
Artifacts	Arbitrary files	Per DAG run	DAG run Artifacts tab
Outputs	Key/value strings in outputs.json	Per DAG run	DAG run Outputs tab
Documents	Markdown files under DAG_DOCS_DIR	Persistent across runs	Documents page