dagu

by dagucloudVerified

Self-hostable workflow orchestrator for teams whose main work isn't orchestration. Declarative YAML over your scripts, SSH commands, containers, etc; keep workflows separate from business logic. One binary, no database, runs on limited H/W resources. Alternative to Airflow / Cron / Job Scheduler.

3,788
Stars
313
Forks
Go
Language
8/23/2026
Added
View on GitHubDownload ZIP

⚠️ Third-Party Software Notice

This skill is third-party open-source software developed and hosted independently on GitHub. SkillTip is an informational directory and does not control or maintain the underlying repository. Any security checks displayed are automated and limited in scope. Review the source code before installing.

Read the Terms of Service

Installation

Add to your Claude Code skills directory:

# Add to your Claude Code skills
git clone https://github.com/dagucloud/dagu

Getting Started

Guides for using skills like dagu.

Security Report

Verified

Last scanned: —

{
  "status": "PASSED",
  "issues": []
}

README.md

Dagu: built for teams whose main work is not orchestration

Docs · CLI · API · Examples · Live demo (username/password: demouser) · Discord

Dagu

Dagu is a local-first workflow engine for operations and internal automation. It is open source and self-hostable: a single binary with a built-in Web UI, no external database or message broker, running on Linux / Mac / Windows. Define DAGs in a declarative YAML format. It natively supports shell commands, Docker containers, Kubernetes Jobs, remote commands via SSH, and more through Dagu Actions.

Dagu turns existing scripts and runbooks into production workflows with scheduling, retries, human tasks, and run history. It runs where your data and credentials live: on-prem, air-gapped, edge, or cloud, and scales from a single node to a fleet of workers.

Highlights:

  • Single binary file installation.
  • Self-contained, with no need for a DBMS or message broker.
  • Runs on Linux, macOS, and Windows.
  • Declarative YAML format for defining DAGs.
  • Run existing shell commands, Docker containers, Kubernetes Jobs, and remote commands over SSH without modifications.
  • Compose reusable Sub-DAGs and run work in parallel with concurrency controls.
  • Schedule workflows with cron syntax, timezones, overlap policies, and catch-up windows.
  • Keep logs, run history, retries, notifications, and webhook triggers in one place.
  • Built-in MCP server for inspecting workflows and runs, maintaining Wiki pages, applying changes, and controlling runs.

Quick Look

For a quick look at how workflows are defined, see the examples.

Run DetailsStep LogsWiki
Run details in dark modeWorkflow logs in dark modeWorkflow Wiki in dark mode

Try it live: Live Demo (credentials: demouser / demouser)

Why Dagu?

Orchestration is not your main work. You have scripts and containers that already work. You want a schedule, retries, dependencies, and a place to see logs. The usual options each have a cost:

  • cron runs commands, but gives you no dependencies, no retries, no history.
  • Airflow orchestrates, but you operate a platform for it (scheduler, metadata database, workers, a Python environment), and your jobs get rewritten as @dag/@task framework code.
  • Temporal gives durable execution, but your business logic moves into its SDK and programming model.

You wanted to schedule some jobs. Now you operate a second system, and the orchestrator lives inside the code it was supposed to serve.

Dagu treats workflow structure as configuration, not code. Order, dependencies, retries, schedules, and human tasks go in one YAML file next to your scripts; the engine that runs them is a single process:

  Traditional Orchestrator          Dagu
  ┌────────────────────────┐        ┌──────────────────┐
  │  Web Server            │        │                  │
  │  Scheduler             │        │  dagu start-all  │
  │  Worker(s)             │        │                  │
  │  PostgreSQL            │        └──────────────────┘
  │  Redis / RabbitMQ      │         Single binary.
  │  Python Runtime        │         Self-hosted.
  └────────────────────────┘         Adds scheduling, retries, and human tasks around existing automation.
    6+ services to manage

Your scripts never import the orchestrator. Delete the YAML and they run exactly as before. Keep it, and every run gets a dependency graph, retries, per-step logs, history, and a Web UI.

Performance

Dagu stores state in local files and reaches production throughput without external services.

  • Throughput: A single machine can run thousands of workflow runs per day. Actual capacity depends on CPU, memory, disk, and workflow shape.
  • Load control: Queues, concurrency limits, and resource limits control how many runs execute at once and where they run.
  • Scale out: Workers spread execution across machines when one node is not enough.

Real-World Use Cases

Use CaseHow Dagu Helps
ETL and data operationsTurn data extraction scripts, SQL queries, dbt commands, and data-processing runbooks into observable pipelines with durable execution.
Legacy scripts and scheduled jobsTurn complex jobs with interdependencies into maintainable DAGs with a UI, automatic logging, retries, and notifications instead of opaque cron jobs and bash scripts.
Media conversionRun ffmpeg for video transcoding and format conversion. Thanks to Dagu's file-backed nature, workers can run heavy conversions in parallel without single machine bottlenecks or external databases.
Infrastructure and server automationRun any command or script over SSH on remote servers, keeping logs, results, and notifications in one place.
GitHub-driven workflowsTrigger workflows from GitHub events. This is useful for running automation on private infrastructure without exposing your servers to the public internet.
Container and Kubernetes workflowsRun Docker containers and Kubernetes Jobs as steps in your workflows without building a custom control plane around containers.
Customer support automationRun self-service support tools that non-engineering teams can use to run approved workflows for running diagnostics, querying databases, and performing common support tasks without escalating to engineering.
IoT and edge workflowsRun sensor polling, local ML inference, data preprocessing, backups, offline sync, health checks, etc. Dagu keeps these jobs close to the data source while still providing Web UI visibility.

Quick Start

Install

macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/dagucloud/dagu/main/scripts/installer.sh | bash

Homebrew:

brew install dagu

npm:

npm install -g --ignore-scripts=false @dagucloud/dagu

Windows (PowerShell):

irm https://raw.githubusercontent.com/dagucloud/dagu/main/scripts/installer.ps1 | iex

Docker:

docker run --rm -v ~/.dagu:/var/lib/dagu -p 8080:8080 ghcr.io/dagucloud/dagu:latest dagu start-all

Kubernetes (Helm):

helm repo add dagu https://dagucloud.github.io/dagu
helm repo update
helm install dagu dagu/dagu --set persistence.storageClass=<your-rwx-storage-class>

Replace <your-rwx-storage-class> with a StorageClass that supports ReadWriteMany. See charts/dagu/README.md for chart configuration.

The script installers run a guided wizard that can add Dagu to your PATH, set it up as a background service, and create the initial admin account. Homebrew, npm, Docker, and Helm install without the wizard. See the Installation documentation for all options.

Create and run a workflow

Create hello.yaml:

steps:
  - id: hello
    run: echo "hello from Dagu"

Run the workflow with:

dagu start hello.yaml

Start the server

dagu start-all --dags .

Visit http://localhost:8080

How You Run Dagu?

Dagu runs on one machine, on temporary workers your platform creates for each run, or on workers you keep running. All three are self-hosted, and the same workflow YAML runs on any of them. See the Deployment Models guide.

Single server
Single-server deployment model with one Dagu server handling scheduling and execution.
Temporary workers
Deployment model where a launcher provisions a temporary worker per run, the worker writes state to a shared volume and is destroyed, and an always-on Dagu server reads that state.
Distributed workers
Distributed-worker deployment where the Dagu server dispatches tasks into a coordinator and workers on separate hosts poll it over gRPC, reporting status and logs back, with the server and persistent volume sharing the same data.
TopologyExecutionBest for
Single serverdagu start-all runs the server, scheduler, and steps in one process on one machine.Development, single-machine scheduled workloads, edge jobs, and internal automation.
Temporary workersCloud Run Jobs, Kubernetes Jobs, or CI provision a worker per run that invokes the binary and is destroyed when the run ends. The server reads run state from a shared volume.Ephemeral compute, capacity that falls to zero between jobs, and launchers you already operate.
Distributed workersWorkers you keep running poll a coordinator over gRPC and are routed work by label.Docker and private-network steps, warm toolchains, and multiple execution hosts.

Licensing

  • Community self-host: No license key required. You operate the server, storage, upgrades, networking, and workers. Start with the installation guide.
  • Self-host license: Adds SSO, RBAC, audit logging, and incident SaaS integration to Dagu. See self-host licensing.

Key Features

  • Observability: Shared workflows and scheduling with clear visualizations, status tracking, and logs in the Web UI.
  • Language-agnostic: No framework required. Define workflow steps using shell commands, Docker containers, Kubernetes Jobs, SQL queries, HTTP requests, and any other tool via official and third-party Dagu Actions.
  • Build workflows: Reuse a step's result when its command and files have not changed. Dagu can also infer dependencies from matching file paths.
  • Reproducibility: Reproducible runs with pinned tools, plus automatic installation and caching on workers—eliminating the need to manually install dependencies on the server or workers.
  • Human Tasks: Pause a workflow for acknowledgement or typed operator input, then expose the response to downstream steps.
  • Secret management: Built-in secret management with secure log masking, preventing credentials from leaking into logs or the Web UI.
  • Self-hosted: A single binary that runs on Linux, macOS, and Windows. Execution scales out to a fleet of workers.
  • Permission Control: RBAC and SSO support for team environments, controlling who can view, run, and edit workflows through granular permissions and audit logging.
  • MCP Server: Authenticated MCP clients can inspect workflows and runs, maintain Wiki pages, apply changes, and control runs.

Architecture

One binary carries every role. Which roles you start, and where, is what the deployment models differ on.

  • Server serves the Web UI and REST API.
  • Scheduler owns schedule: and drains the queue.
  • Coordinator is the gRPC endpoint workers poll. It also persists what they report: run status, streamed logs, and artifacts.
  • Worker polls a coordinator, executes dispatched runs locally, and reports back. Routed by labels.
  • dagu start-all runs the server, scheduler, and coordinator in one process.

Set DAGU_HEADLESS=true to run without the Web UI, which applies to any of the topologies and suits CI or CLI-only environments.

Single server:

  ┌─────────────────────────────────────────┐
  │  dagu start-all                         │
  │  ┌───────────┐ ┌───────────┐ ┌────────┐ │
  │  │ HTTP / UI │ │ Scheduler │ │Executor│ │
  │  └───────────┘ └───────────┘ └────────┘ │
  │  File-based storage (logs, state, queue)│
  └─────────────────────────────────────────┘

Distributed workers:

  ┌────────────┐                   ┌────────────┐
  │ Scheduler  │                   │ HTTP / UI  │
  │            │                   │            │
  │ ┌────────┐ │                   └─────┬──────┘
  │ │ Queue  │ │  Dispatch (gRPC)        │ Dispatch / GetWorkers
  │ │(file)  │ │─────────┐               │ (gRPC)
  │ └────────┘ │         │               │
  └────────────┘         ▼               ▼
                    ┌─────────────────────────┐
                    │      Coordinator        │
                    │  ┌───────────────────┐  │
                    │  │ Dispatch Task     │  │
                    │  │ Store (pending/   │  │
                    │  │ claimed)          │  │
                    │  └───────────────────┘  │
                    └────────▲────────────────┘
                             │
                   Worker poll / task response
                   Heartbeat / ReportStatus /
                   StreamLogs (gRPC)
                             │
               ┌─────────────┴─────────────┐
               │             │             │
          ┌────┴───┐    ┌────┴───┐    ┌────┴───┐
          │Worker 1│    │Worker 2│    │Worker N│ Sandbox execution of DAGs
          │        │    │        │    │        │
          └────────┘    └────────┘    └────────┘

Temporary workers:

  ┌────────────┐   provisions   ┌──────────────┐
  │  Launcher  │───────────────▶│  dagu start  │
  │ Cloud Run  │                │  exits when  │
  │ K8s Job/CI │                │ the run ends │
  └────────────┘                └──────┬───────┘
                                       │ writes
                                       ▼
  ┌────────────┐     reads      ┌──────────────────┐
  │ Dagu server│◀───────────────│  Shared volume   │
  │  UI / API  │                │ dags/state/logs  │
  └────────────┘                └──────────────────┘

  No coordinator, and no network path between the two.

Parameter Definition

Workflows can define parameters that render as typed input forms in the Web UI and can be referenced by steps.

params:
  - name: customer_id
    type: string
    description: Customer or account identifier
  - name: change_scope
    type: string
    description: What the repair is allowed to change
    enum:
      - metadata_only
      - permissions
      - full_account
    default: metadata_only
  - name: dry_run
    type: boolean
    default: true

steps:
  - id: extract
    run: >-
      ./scripts/extract.sh
      --customer "${params.customer_id}"
      --scope "${params.change_scope}"
      --dry-run="${params.dry_run}"
    retry_policy:
      limit: 3
      interval_sec: 30
Generated parameter input form in the Dagu Web UI

Workflow Examples

Docker step

steps:
  - name: build
    container:
      image: node:20-alpine
    run: npm run build

Parallel Sub-DAG execution

The parent invokes the same child DAG for multiple targets and limits concurrent child runs:

steps:
  - id: patch
    action: dag.run
    with:
      dag: patch-host
      params:
        host: ${ITEM}
    parallel:
      items:
        - web-1.internal
        - web-2.internal
        - db-1.internal
      max_concurrent: 2

---

name: patch-host
params:
  - name: host
    type: string
ssh:
  user: deploy
  host: ${params.host}
steps:
  - id: apply
    run: apt-get update -q && apt-get upgrade -y

SSH remote execution

ssh:
  user: deploy
  host: web-1.internal
  key: ~/.ssh/deploy_key

steps:
  - id: health
    run: curl -f http://localhost:8080/health
    retry_policy:
      limit: 3
      interval_sec: 10

  - id: restart
    run: systemctl restart myapp
    depends: health

Scheduling with overlap control and catch-up

schedule:
  - "0 */6 * * *"          # Every 6 hours
overlap_policy: skip       # Skip if previous run is still active
catchup_window: "5h"       # Catch up missed runs when scheduler is down for up to 5 hours

timeout_sec: 3600
handler_on:
  failure:
    run: notify-team.sh
  exit:
    run: cleanup.sh

Retry and error handling

steps:
  - name: flaky-api-call
    run: curl -f https://api.example.com/data
    retry_policy:
      limit: 3
      interval_sec: 10
    continue_on:
      failure: true

See the Sub-DAG, SSH, scheduling, and notification documentation for complete configuration details.

More Workflow Examples

Parallel executions

steps:
  - id: extract
    run: ./extract.sh

  - id: transform_a
    run: ./transform_a.sh
    depends: extract

  - id: transform_b
    run: ./transform_b.sh
    depends: extract

  - id: load
    run: ./load.sh
    depends: [transform_a, transform_b]
%%{init: {'theme': 'base', 'themeVariables': {'background': '#18181B', 'primaryTextColor': '#fff', 'lineColor': '#888'}}}%%
graph LR
    A[extract] --> B[transform_a]
    A --> C[transform_b]
    B --> D[load]
    C --> D
    style A fill:#18181B,stroke:#22C55E,stroke-width:1.6px,color:#fff
    style B fill:#18181B,stroke:#22C55E,stroke-width:1.6px,color:#fff
    style C fill:#18181B,stroke:#22C55E,stroke-width:1.6px,color:#fff
    style D fill:#18181B,stroke:#3B82F6,stroke-width:1.6px,color:#fff

Reuse unchanged results

Save this as workflow.yaml:

type: build
working_dir: .

steps:
  - id: uppercase
    inputs:
      - name: source
        path: source.txt
    outputs:
      - name: result
        path: uppercase.txt
    run: |
      #!/bin/sh
      tr '[:lower:]' '[:upper:]' < "${inputs.source}" > "${outputs.result}"

Run it:

printf 'alpha\n' > source.txt
dagu start workflow.yaml

Run dagu start workflow.yaml again and Dagu reuses uppercase.txt. Change source.txt and the step runs again. ${outputs.result} is a temporary path that Dagu publishes as uppercase.txt after the command succeeds.

Build workflows currently run locally. See Build Workflows for dependency inference and reuse rules.

External tools with pinning and caching

tools:
  - jqlang/jq@jq-1.7.1

steps:
  - id: inspect
    run: jq --version

  - id: summarize
    action: python-script@v1
    with:
      input:
        rows: [42, 8]
      script: |
        return {"total": sum(input["rows"])}

Dagu installs declared portable CLIs before the DAG run, exposes them on PATH for host command steps, and caches them on each worker. Tool provisioning uses aqua as the default provider; the standard registry resolves to the latest aqua-registry release automatically. Pin a specific artifact with package@version#sha256:<hex> when the release tag alone is not a strong enough guarantee. See the Tools documentation and Dagu Actions for more details.

Third-party Dagu Actions

params:
  - BUILD_ID

steps:
  - id: notify
    action: acme/dagu-action-notify@v1.2.0
    with:
      text: "Build ${params.BUILD_ID} finished"

  - id: audit
    depends: notify
    run: 'echo "Notification result: ${steps.notify.outputs.messageId}"'

A third-party Dagu Action package contains a DAG, manifest, schemas, and helper files behind an action: reference. See the Dagu Actions and Third-Party Actions documentation for details.

Kubernetes Pod execution

steps:
  - name: batch-job
    action: kubernetes.run
    with:
      namespace: production
      image: my-registry/batch-processor:latest
      resources:
        requests:
          cpu: "2"
          memory: "4Gi"
      command: ./process.sh

For more examples, see the Examples documentation.

MCP

Dagu includes a built-in MCP server at http://localhost:8080/mcp. MCP clients can inspect workflows and run state, maintain Dagu's built-in Wiki pages, preview and apply DAG or Wiki page changes, and control runs through the same authenticated server boundary as the REST API.

See the MCP overview and quickstart.

Built-in Actions

Dagu includes built-in actions that run within the Dagu process or on the selected worker. Local shell commands use the run: field; structured work uses action:.

ActionPurpose
run: fieldLocal shell commands and scripts (bash, sh, PowerShell, custom shells)
execDirect process execution without shell parsing
noopOutput-only or approval-only placeholder step
log.writeWrite structured log messages
docker.run / container.runRun containers with registry auth, volume mounts, and resource limits
kubernetes.run / k8s.runExecute Kubernetes Jobs with namespace, image, and resource settings
ssh.runRemote command execution over SSH
sftp.upload / sftp.downloadFile transfer over SFTP
http.requestHTTP requests with headers, auth, and request bodies
chat.completionRun an LLM chat completion step
harness.runRun external coding-agent CLIs such as Claude Code, Codex, Gemini CLI, Cursor, and DeepSeek Harness
postgres.query / postgres.importPostgreSQL queries and imports
sqlite.query / sqlite.importSQLite queries and imports
redis.<operation>Redis commands, pipelines, and Lua scripts
s3.upload / s3.download / s3.list / s3.deleteUpload, download, list, and delete S3 objects
file.stat / file.read / file.write / file.copy / file.move / file.delete / file.mkdir / file.listLocal file operations without shell commands
artifact.write / artifact.read / artifact.listWrite, read, and list DAG-run artifacts
state.get / state.set / state.delete / state.list / state.diffPersistent JSON state across DAG runs
data.convert / data.pickConvert and select structured data
jq.filterJSON transformation using jq expressions
archive.create / archive.extract / archive.listCreate, extract, and list zip/tar archives
wait.duration / wait.until / wait.file / wait.httpWait for time, file state, or HTTP readiness
human.taskWait for acknowledgement or typed operator input before downstream steps continue
mail.sendSend email via SMTP
template.renderText generation with template rendering
router.routeConditional step routing based on values and patterns
dag.runInvoke another DAG as a sub-workflow with params and dependencies
dag.enqueueQueue another DAG asynchronously and continue after enqueue
git.checkoutClone or update Git repositories
outputs.writePublish DAG or Dagu Action outputs for callers

Custom Actions

Custom Actions are inline reusable wrappers defined with the top-level actions field. They expand to built-in actions during DAG load, so you can wrap a common shell, HTTP, SQL, or other pattern behind a typed interface with validated input.

actions:
  webhook.send:
    input_schema:
      type: object
      additionalProperties: false
      required: [url, text]
      properties:
        url:
          type: string
        text:
          type: string
    template:
      action: http.request
      with:
        method: POST
        url: '{{ .input.url }}'
        headers:
          Content-Type: application/json
        body: |
          {"text": {{ json .input.text }}}

steps:
  - action: webhook.send
    with:
      url: https://hooks.example.com/ops
      text: deploy complete

See Custom Actions and the YAML Specification for the exact actions, action, and run field behavior.

Official Dagu Actions

Dagu Actions are official action packages maintained in the dagucloud GitHub organization. They use the same action package runtime as third-party action packages, but callers use the short form action: name@version.

Dagu ActionPurpose
node-script@v1Run small JavaScript transforms or glue code with action-owned Node.js
python-script@v1Run small Python transforms or glue code with action-owned Python and optional requirements
dbt@v1Run dbt Core commands with action-owned Python and adapter requirements
duckdb@v1Run DuckDB SQL through the DuckDB CLI without adding DuckDB to the core binary
ffmpeg@v1Run FFmpeg conversion, transcoding, probing, and stream-processing tasks
github-cli@v1Run GitHub issue, pull request, release, repository, and API automation through gh
rclone@v1Run portable copy, sync, check, list, and storage-management workflows through rclone

Versions are required. Pin production workflows to a version tag or commit SHA. See Official Dagu Actions for the current Dagu Action list and exact input/output contracts.

For non-official packages, use Third-Party Actions such as action: owner/repo@version. They contain a dagu-action.yaml manifest and a DAG entrypoint, run as sub-DAGs, and are transferred to distributed workers as workspace bundles after the reference is resolved. See the documentation for package layout and reference formats.

Security and Access Control

Authentication

Dagu supports three top-level authentication modes, configured via DAGU_AUTH_MODE:

  • none — No authentication
  • basic — HTTP Basic authentication
  • builtin — JWT-based authentication with user management, API keys, per-DAG webhook tokens, and optional OIDC/SSO integration

Role-Based Access Control

When using builtin auth, five roles control access:

RoleCapabilities
adminFull access including user management
managerCreate, edit, delete, run, stop DAGs; view audit logs
developerCreate, edit, delete, run, stop DAGs
operatorRun and stop DAGs only (no editing)
viewerRead-only access

API keys can be created with independent role assignments. Audit logging tracks all actions.

TLS and Secrets

  • TLS for the HTTP server (DAGU_CERT_FILE, DAGU_KEY_FILE)
  • Mutual TLS for gRPC coordinator/worker communication (DAGU_PEER_CERT_FILE, DAGU_PEER_KEY_FILE, DAGU_PEER_CLIENT_CA_FILE)
  • Secret management with environment variables, files, Kubernetes Secrets, HashiCorp Vault, and cloud-provider secret stores

Production Hardening

For self-hosted production deployments, treat network exposure and execution boundaries as the primary controls:

  • Prefer auth.mode: builtin for any shared or network-exposed instance. Use basic only for simple private setups, and avoid none outside isolated local development.
  • Keep metrics: private unless the metrics endpoint is reachable only on a trusted private network.
  • Bind Dagu to loopback or a private interface when possible. If you must use 0.0.0.0, place it behind a trusted reverse proxy, TLS, and network-level access controls.
  • Leave terminal.enabled: false unless the instance is admin-only and tightly scoped.
  • In distributed deployments, set peer.insecure=false and configure peer TLS when coordinator and workers communicate across host or network boundaries.
  • Treat Docker socket mounts, root containers, and host-level executors as privileged access to the underlying machine.

See Server Configuration, Docker deployment, and Distributed execution for operator-focused guidance.

Observability

Prometheus Metrics

Dagu exposes Prometheus-compatible metrics:

  • dagu_info — Build information (version, Go version)
  • dagu_uptime_seconds — Server uptime
  • dagu_dag_runs_total — Total DAG runs by status
  • dagu_dag_runs_total_by_dag — Per-DAG run counts
  • dagu_dag_run_duration_seconds — Histogram of run durations
  • dagu_dag_runs_currently_running — Active DAG runs
  • dagu_dag_runs_queued_total — Queued runs
  • dagu_workers_registered — Registered distributed workers
  • dagu_worker_info — Worker heartbeat labels as key/value metadata
  • dagu_worker_heartbeat_timestamp_seconds — Last worker heartbeat timestamp
  • dagu_worker_health_status — Worker health by heartbeat freshness
  • dagu_worker_pollers — Worker poller capacity by state
  • dagu_worker_running_tasks — Running tasks per worker
  • dagu_worker_oldest_running_task_age_seconds — Age of the oldest running task per worker

Structured Logging

JSON or text format logging (DAGU_LOG_FORMAT). Logs are stored per-run with separate stdout/stderr capture per step.

Notifications

  • Email notifications on DAG success, failure, or wait status via SMTP
  • Per-DAG webhook endpoints with token authentication

Artifacts

Artifact browser in dark mode

Dagu runs can write arbitrary files under ${context.paths.artifacts_dir} in value-resolved fields, with DAG_RUN_ARTIFACTS_DIR also exposed to step processes. Dagu stores those files per run as Artifacts. In the Web UI, operators can browse the file tree, preview Markdown, text, and image files inline, and download any artifact when they need the raw file.

This is useful for generated reports, screenshots, charts, exported JSON or CSV files, and other outputs that do not fit simple key/value outputs.

See the Artifacts documentation and the Web UI guide for the full artifact browser workflow and screenshots.

Scheduling and Reliability

  • Cron scheduling with timezone support and multiple schedule entries per DAG
  • Overlap policies: skip (default — skip if previous run is still active), all (queue all), latest (keep only the most recent)
  • Catch-up scheduling: Automatically runs missed intervals when the scheduler was down
  • Zombie detection: Identifies and handles stalled DAG runs (configurable interval, default 45s)
  • Retry policies: Per-step retry with configurable limits, intervals, and exit code filtering
  • Human tasks: Pause root DAG runs for acknowledgement or schema-validated operator input, locally or on distributed workers, then expose form values to downstream steps
  • Lifecycle hooks: onInit, onSuccess, onFailure, onAbort, onExit, onWait
  • Preconditions: Gate DAG or step execution on shell command results
  • High availability: Scheduler lock with stale detection for failover

Distributed Execution

Operational detail for the distributed workers topology:

  • Coordinator: gRPC server that manages task distribution, worker registry, and health monitoring
  • Workers: Poll the coordinator outbound, execute DAGs locally, and report status, logs, and artifacts back. No inbound port required
  • Worker labels: Route DAGs to specific workers based on labels (e.g., gpu=true, region=us-east-1)
  • Health checks: HTTP health endpoints on coordinator and workers for load balancer integration
  • Queue system: File-based persistent queue with configurable concurrency limits
# Start coordinator
dagu coordinator

# Start workers (on separate machines)
DAGU_WORKER_LABELS=gpu=true,memory=64G dagu worker

See the distributed execution documentation for setup details.

CLI Reference

CommandDescription
dagu start <dag>Execute a DAG
dagu start-allStart HTTP server + scheduler + coordinator
dagu serverStart HTTP server only
dagu schedulerStart scheduler only
dagu coordinatorStart coordinator (distributed mode)
dagu workerStart worker (distributed mode)
dagu stop <dag>Stop a running DAG
dagu restart <dag>Restart a DAG
dagu retry --run-id=<run-id> <dag>Retry a failed run
dagu human-task complete --run-id=<run-id> --step=<id> <dag>Complete a waiting human task
dagu dry <dag>Dry run — show what would execute
dagu status <dag>Show DAG run status
dagu history <dag>Show execution history
dagu validate <dag>Validate DAG YAML
dagu enqueue <dag>Add DAG to the execution queue
dagu dequeue <queue-name> [--dag-run=<dag>:<run-id>]Remove a DAG-run from the queue
dagu cleanup <dag>Clean up old run data
dagu versionShow version

The table lists the most common commands. The binary ships 31 in total, including exec, ls, ps, rm, sync, schema, example, config, profile, context, license, upgrade, and completion; run dagu --help or see the CLI reference for all of them.

Environment Variables

Precedence: Command-line flags > Environment variables > Configuration file (~/.config/dagu/config.yaml)

Server

VariableDefaultDescription
DAGU_HOST127.0.0.1Bind address
DAGU_PORT8080HTTP port
DAGU_BASE_PATHBase path for reverse proxy
DAGU_HEADLESSfalseRun without web UI
DAGU_TZTimezone (e.g., Asia/Tokyo)
DAGU_LOG_FORMATtexttext or json
DAGU_CERT_FILETLS certificate
DAGU_KEY_FILETLS private key
DAGU_CORS_ALLOWED_ORIGINSComma-separated list of allowed CORS origins (e.g. https://app.example.com). When unset, cross-origin browser access is disabled. Exact origins enable credentials. An explicit * allows every origin without credentials and emits a security warning.
DAGU_IP_ACCESS_ALLOWED_IPSComma-separated IPv4/IPv6 addresses and CIDR ranges allowed to access the HTTP server. Empty disables filtering.
DAGU_IP_ACCESS_TRUSTED_PROXIESComma-separated proxy addresses and CIDR ranges permitted to supply forwarded client IP headers.
DAGU_PUBLIC_URLExternal Web UI URL used in generated links, including notification and incident DAG-run links
DAGU_SERVER_METRICSprivateMetrics endpoint access: private or public
DAGU_TERMINAL_ENABLEDfalseEnable the web-based terminal
DAGU_DEFAULT_SHELL$SHELL, then shDefault shell for command steps
DAGU_ENV_PASSTHROUGH_PREFIXESComma-separated env var prefixes forwarded to step execution
DAGU_DEBUGEnable debug mode

The equivalent YAML protects every HTTP route, including health, metrics, webhooks, SSE, terminal, and MCP:

ip_access:
  allowed_ips:
    - 203.0.113.10
    - 10.0.0.0/8
  trusted_proxies:
    - 127.0.0.1
    - 10.42.0.0/16

Forwarded addresses are used only when the direct peer matches trusted_proxies. The proxy must remove client-supplied forwarding headers and set or append the verified client address. Keep trusted proxy ranges narrow.

Paths

VariableDefaultDescription
DAGU_HOMEOverrides all path defaults
DAGU_DAGS_DIR~/.config/dagu/dagsDAG definitions directory
DAGU_DAG_DISCOVERY_RECURSIVEfalseDiscover DAGs in subdirectories
DAGU_DAG_DISCOVERY_SYMLINKSfalseInclude recursive file symlinks and allow external targets
DAGU_LOG_DIR~/.local/share/dagu/logsLog files
DAGU_DATA_DIR~/.local/share/dagu/dataApplication state
DAGU_TOOLS_DIR{DAGU_DATA_DIR}/toolsManaged DAG tool cache
DAGU_DAG_STATE_DIR{DAGU_DATA_DIR}/dag-statePersistent DAG state files
DAGU_DAG_RUN_WORK_DIR{DAGU_DATA_DIR}/dag-run-workPer-run working directories
DAGU_BASE_CONFIGShared base configuration applied to all DAGs

Set the per-run work root in config.yaml, or use the corresponding environment variable above:

paths:
  dag_run_work_dir: /mnt/dagu/dag-run-work

DAGU_DAG_RUN_WORK_DIR configures this root for Dagu processes. Workflow code should use the runtime DAG_RUN_WORK_DIR variable for its assigned per-run directory instead of constructing paths under DAG-run history.

Processes sharing DAG runs must use the same work root.

Backups that select individual data subdirectories must include both paths.dag_runs_dir and paths.dag_run_work_dir. A backup of the complete paths.data_dir includes both default locations. The Helm chart's default /data/dag-run-work path uses its existing /data volume and does not need an additional volume.

When upgrading a deployment whose processes share a durable work root, do not let old and new Dagu versions execute the same run concurrently: drain or stop the processes, upgrade them together, and then resume execution. Mixed-version processes can otherwise choose the old nested directory and the new separate directory for one run.

Recursive discovery can also be enabled in config.yaml:

dag_discovery:
  recursive: true

It scans paths.dags_dir, excluding workspaces/, dot-directories, and symlinks. File stems and effective DAG names must each be unique, using case-sensitive comparison; conflicting files are excluded until the conflict is resolved. paths.alt_dags_dir remains lookup-only.

Set dag_discovery.symlinks: true (or DAGU_DAG_DISCOVERY_SYMLINKS=true) to include YAML file symlinks in recursive discovery and to allow YAML file symlinks whose targets are outside paths.dags_dir. Symlinked directories are never traversed. External targets can be viewed, scheduled, and run, but cannot be updated, deleted, or renamed through Dagu. Without the opt-in, top-level YAML file symlinks whose targets remain inside paths.dags_dir continue to work. A symlink configured as paths.dags_dir itself is also supported.

Authentication

VariableDefaultDescription
DAGU_AUTH_MODEbuiltinnone, basic, or builtin
DAGU_AUTH_BASIC_USERNAMEBasic auth username
DAGU_AUTH_BASIC_PASSWORDBasic auth password
DAGU_AUTH_TOKEN_SECRET(auto)JWT signing secret
DAGU_AUTH_TOKEN_TTL24hJWT token lifetime (maximum: 8760h / 365 days)
DAGU_AUTH_BUILTIN_INITIAL_ADMIN_USERNAMEAuto-provision the first admin on startup (requires the password variable)
DAGU_AUTH_BUILTIN_INITIAL_ADMIN_PASSWORDPassword for the auto-provisioned admin (minimum 8 characters)
DAGU_LICENSE_KEYLicense key for licensed self-host features

OIDC variables: DAGU_AUTH_OIDC_CLIENT_ID, DAGU_AUTH_OIDC_CLIENT_SECRET, DAGU_AUTH_OIDC_ISSUER, DAGU_AUTH_OIDC_SCOPES, DAGU_AUTH_OIDC_WHITELIST, DAGU_AUTH_OIDC_AUTO_SIGNUP, DAGU_AUTH_OIDC_DEFAULT_ROLE, DAGU_AUTH_OIDC_ALLOWED_DOMAINS.

Scheduler

VariableDefaultDescription
DAGU_SCHEDULER_PORT8090Health check port
DAGU_SCHEDULER_ZOMBIE_DETECTION_INTERVAL45sZombie run detection interval (0 to disable)
DAGU_SCHEDULER_LOCK_STALE_THRESHOLD30sHA lock stale threshold
DAGU_QUEUE_ENABLEDtrueEnable queue system

Coordinator / Worker

VariableDefaultDescription
DAGU_COORDINATOR_HOST127.0.0.1Coordinator bind address
DAGU_COORDINATOR_PORT50055Coordinator gRPC port
DAGU_COORDINATOR_HEALTH_PORT8091Coordinator health check port
DAGU_WORKER_IDWorker instance ID
DAGU_WORKER_MAX_ACTIVE_RUNS100Max concurrent runs per worker
DAGU_WORKER_HEALTH_PORT8092Worker health check port
DAGU_WORKER_LABELSWorker labels (key=value,key=value); os and arch are built in and cannot be overridden
DAGU_COORDINATOR_ADVERTISEauto-detected hostnameAddress advertised in the service registry
DAGU_WORKER_COORDINATORSExplicit coordinator addresses for shared-nothing mode

Peer TLS (gRPC)

VariableDefaultDescription
DAGU_PEER_CERT_FILEPeer TLS certificate
DAGU_PEER_KEY_FILEPeer TLS private key
DAGU_PEER_CLIENT_CA_FILECA for client verification
DAGU_PEER_INSECUREtrueUse h2c instead of TLS
DAGU_PEER_SKIP_TLS_VERIFYSkip TLS certificate verification

Git Sync

VariableDefaultDescription
DAGU_GITSYNC_ENABLEDfalseEnable Git sync
DAGU_GITSYNC_REPOSITORYRepository URL
DAGU_GITSYNC_BRANCHmainBranch to sync
DAGU_GITSYNC_AUTH_TYPEtokentoken or ssh
DAGU_GITSYNC_AUTH_TOKENPersonal access token for HTTPS auth
DAGU_GITSYNC_AUTH_SSH_KEY_PATHPath to the SSH private key
DAGU_GITSYNC_AUTOSYNC_ENABLEDfalseEnable periodic auto-pull
DAGU_GITSYNC_AUTOSYNC_INTERVAL300Sync interval in seconds

These tables cover the variables most deployments touch. The full reference lists about 180 DAGU_* variables, including SSE, tunnel, UI, monitoring, audit, and secret-provider settings: see the configuration reference.

Embedded Go API (Experimental)

Go applications can import Dagu and start DAG runs from the host process:

import "github.com/dagucloud/dagu/v2"
engine, err := dagu.New(ctx, dagu.Options{
	HomeDir: "/var/lib/myapp/dagu",
})
if err != nil {
	return err
}
defer engine.Close(context.Background())

run, err := engine.RunYAML(ctx, []byte(`
params:
  - MESSAGE
steps:
  - name: hello
    run: echo "${params.MESSAGE}"
`), dagu.WithParams(map[string]string{
	"MESSAGE": "hello from the host app",
}))
if err != nil {
	return err
}

status, err := run.Wait(ctx)
if err != nil {
	return err
}
fmt.Println(status.Status)

The embedded API is experimental and may change. See the embedded API documentation and examples/embedded.

Community

Development

Prerequisites: Go 1.27+, Node.js, pnpm

git clone https://github.com/dagucloud/dagu.git && cd dagu
make build    # Build frontend + Go binary
make test     # Run tests with race detection
make lint     # Run golangci-lint

See CONTRIBUTING.md for development workflow and code standards.

Acknowledgements

Premium Sponsors

/bin labs

Supporters

@gyger @disizmj @Arvintian @yurivish @jayjoshi64 @alangrafu



Sponsor

Contributing

We welcome contributions of all kinds. See our Contribution Guide for details.

License

GNU GPLv3 - See LICENSE. See LICENSING.md for embedded API and commercial embedding notes.

Frequently Asked Questions

What is dagu?

dagu is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by dagucloud. Self-hostable workflow orchestrator for teams whose main work isn't orchestration. Declarative YAML over your scripts, SSH commands, containers, etc; keep workflows separate from business logic. One binary, no database, runs on limited H/W resources. Alternative to Airflow / Cron / Job Scheduler. It has 3,788 GitHub stars.

Is dagu safe to use?

Yes. dagu passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.

How do I install dagu?

Clone the repository with "git clone https://github.com/dagucloud/dagu" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is dagu written in?

dagu is primarily written in Go. It is open-source under dagucloud on GitHub, so you can review or fork the full source.

Are there alternatives to dagu?

Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh dagu against similar tools.

Comments (0)

No comments yet. Be the first to share your thoughts!

ECC

by affaan-m

10

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

242,21936,702JavaScript
AI Agentsai-agentsanthropicclaude-code
View details
15

An agentic skills framework & software development methodology that works.

234,96620,863Shell
AI Agentsai-agentsbrainstorming
View details

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

185,94028,768JavaScript
AI Agentsai-agentsanthropicclaude-code
View details

cc-switch

by farion1231

3

A cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build & Hermes Agent. Only official website: ccswitch.io

128,8688,826Rust
AI Agentsclaude-codeai-tools
View details

claude-code

by anthropics

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

120,03119,897Shell
AI Agents
View details

Developers Also Liked

Based on votes and bookmarks from developers who liked this skill

ECC

by affaan-m

10

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

242,21936,702JavaScript
AI Agentsai-agentsanthropicclaude-code
View details
15

An agentic skills framework & software development methodology that works.

234,96620,863Shell
AI Agentsai-agentsbrainstorming
View details

n8n

by n8n-io

12

Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.

201,88160,308TypeScript
MCP Serversapisai-tools
View details

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

185,94028,768JavaScript
AI Agentsai-agentsanthropicclaude-code
View details

cc-switch

by farion1231

3

A cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build & Hermes Agent. Only official website: ccswitch.io

128,8688,826Rust
AI Agentsclaude-codeai-tools
View details