Website | Examples | Discord

What is Dagu?

Dagu is a lightweight workflow engine with a modern Web UI. Workflows are defined in a simple, declarative YAML format and can be executed on schedule. It supports shell commands, remote execution via SSH, and Docker images. Built-in error notifications and logging out of the box.

For a quick feel of how it works, take a look at the examples.

Motivation

Legacy systems often have complex and implicit dependencies between jobs. When there are hundreds of cron jobs on a server, it can be difficult to keep track of these dependencies and to determine which job to rerun if one fails. It can also be a hassle to SSH into a server to view logs and manually rerun shell scripts one by one. Dagu aims to solve these problems by allowing you to explicitly visualize and manage pipeline dependencies as a DAG, and by providing a web UI for checking dependencies, execution status, and logs and for rerunning or stopping jobs with a simple mouse click.

Why Not Use an Existing Workflow Scheduler Like Airflow?

There are many existing tools such as Airflow, but many of these require you to write code in a programming language like Python to define your DAG. For systems that have been in operation for a long time, there may already be complex jobs with hundreds of thousands of lines of code written in languages like Perl or Shell Script. Adding another layer of complexity on top of these codes can reduce maintainability. Dagu was designed to be easy to use, self-contained, and require no coding, making it ideal for small projects.

How it Works

Dagu executes your workflows defined in a simple, declarative YAML format.

For example, a simple sequential DAG:

schedule: "0 0 * * *" # Runs at 00:00 everyday

steps:
  - echo "Hello, dagu!"
  - echo "This is a second step"

Highlights

• Install by placing a single binary with zero dependency
• Run without DBMS or any cloud service
• Define workflows (DAG) in a declarative YAML format
• Use existing programs, scripts, and container images without any modification
• Schedule workflows with cron expressions
• Run in HA mode and distribute tasks to workers through built-in queue system.
• Modularize workflows by nesting them with sub DAGs (and inspect each sub-run in the UI).

CLI Preview

Web UI Preview

Table of Contents

• Quick Start
  • Quick Start
  • Docker-Compose
• Documentation
  • Documentation
  • Environment Variables
  • Architecture
  • Roadmap
• Development & Contributing
  • Development
  • Discussion
  • Contributing
  • Acknowledgements
• License

Quick Start

1. Install dagu

macOS/Linux:

# Install to ~/.local/bin (default, no sudo required)
curl -L https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.sh | bash

# Install specific version
curl -L https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.sh | bash -s -- --version v1.17.0

# Install to custom directory
curl -L https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.sh | bash -s -- --install-dir /usr/local/bin

# Install to custom directory with custom working directory
curl -L https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.sh | bash -s -- --install-dir /usr/local/bin --working-dir /var/tmp

Windows (PowerShell):

# Install latest version to default location (%LOCALAPPDATA%\Programs\dagu)
irm https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.ps1 | iex

# Install specific version
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.ps1))) v1.24.0

# Install to custom directory
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.ps1))) latest "C:\tools\dagu"

Windows (CMD/PowerShell):

REM Install latest version to default location (%LOCALAPPDATA%\Programs\dagu)
curl -fsSL https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.cmd -o installer.cmd && .\installer.cmd && del installer.cmd

REM Install specific version
curl -fsSL https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.cmd -o installer.cmd && .\installer.cmd v1.24.0 && del installer.cmd

REM Install to custom directory
curl -fsSL https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.cmd -o installer.cmd && .\installer.cmd latest "C:\tools\dagu" && del installer.cmd

Docker:

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

Note: see documentation for other methods.

Homebrew:

brew update && brew install dagu

# Upgrade to latest version
brew update && brew upgrade dagu

npm:

# Install via npm
npm install -g --ignore-scripts=false @dagu-org/dagu

2. Create your first workflow

Note

: When you first start Dagu with an empty DAGs directory, it automatically creates example workflows to help you get started. To skip this, set DAGU_SKIP_EXAMPLES=true.

cat > ./hello.yaml << 'EOF'
steps:
  - echo "Hello from Dagu!"
  - echo "Running step 2"
EOF

3. Run the workflow

dagu start hello.yaml

4. Check the status and view logs

dagu status hello

5. Explore the Web UI

dagu start-all

Visit http://localhost:8080

Docker-Compose

Clone the repository and run with Docker Compose:

git clone https://github.com/dagu-org/dagu.git
cd dagu

Run with minimal setup:

docker compose -f deploy/docker/compose.minimal.yaml up -d
# Visit http://localhost:8080

Stop containers:

docker compose -f deploy/docker/compose.minimal.yaml down

You can also use the production-like configuration deploy/docker/compose.prod.yaml with OpenTelemetry, Prometheus, and Grafana:

docker compose -f deploy/docker/compose.prod.yaml up -d
# Visit UI at http://localhost:8080
# Jaeger at http://localhost:16686, Prometheus at http://localhost:9090, Grafana at http://localhost:3000

Note: It's just for demonstration purposes. For production, please customize the configuration as needed.

Looking for Kubernetes? See the example manifests in deploy/k8s/README.md.

Documentation

Full documentation is available at docs.dagu.cloud.

Helpful Links:

• Feature by Examples - Explore useful features with examples
• Remote Execution via SSH - Run commands on remote machines using SSH
• Distributed Execution - How to run workflows across multiple machines
• Scheduling - Learn about flexible scheduling options (start, stop, restart) with cron syntax
• Authentication - Configure authentication for the Web UI
• Configuration - Detailed configuration options for customizing Dagu

Changelog

For a detailed list of changes, bug fixes, and new features, please refer to the Changelog.

Environment Variables

Note: Configuration precedence: Command-line flags > Environment variables > Configuration file

Frontend Server Configuration

Environment Variable	Default	Description
DAGU_HOST	127.0.0.1	Web UI server host
DAGU_PORT	8080	Web UI server port
DAGU_BASE_PATH	-	Base path for reverse proxy setup
DAGU_API_BASE_URL	/api/v2	API endpoint base path
DAGU_TZ	-	Server timezone (e.g., Asia/Tokyo)
DAGU_DEBUG	false	Enable debug mode
DAGU_LOG_FORMAT	text	Log format (text or json)
DAGU_HEADLESS	false	Run without Web UI
DAGU_LATEST_STATUS_TODAY	false	Show only today's latest status
DAGU_WORK_DIR	-	Default working directory for DAGs
DAGU_DEFAULT_SHELL	-	Default shell for command execution
DAGU_CERT_FILE	-	TLS certificate file path
DAGU_KEY_FILE	-	TLS key file path

Path Configuration

Environment Variable	Default	Description
DAGU_HOME	-	Base directory that overrides all path configurations
DAGU_DAGS_DIR	~/.config/dagu/dags	Directory for DAG definitions
DAGU_LOG_DIR	~/.local/share/dagu/logs	Directory for log files
DAGU_DATA_DIR	~/.local/share/dagu/data	Directory for application data
DAGU_SUSPEND_FLAGS_DIR	~/.local/share/dagu/suspend	Directory for suspend flags
DAGU_ADMIN_LOG_DIR	~/.local/share/dagu/logs/admin	Directory for admin logs
DAGU_BASE_CONFIG	~/.config/dagu/base.yaml	Path to base configuration file
DAGU_EXECUTABLE	-	Path to dagu executable
DAGU_DAG_RUNS_DIR	{dataDir}/dag-runs	Directory for DAG run data
DAGU_PROC_DIR	{dataDir}/proc	Directory for process data
DAGU_QUEUE_DIR	{dataDir}/queue	Directory for queue data
DAGU_SERVICE_REGISTRY_DIR	{dataDir}/service-registry	Directory for service registry

Authentication

Environment Variable	Default	Description
DAGU_AUTH_BASIC_USERNAME	-	Basic auth username
DAGU_AUTH_BASIC_PASSWORD	-	Basic auth password
DAGU_AUTH_OIDC_CLIENT_ID	-	OIDC client ID
DAGU_AUTH_OIDC_CLIENT_SECRET	-	OIDC client secret
DAGU_AUTH_OIDC_CLIENT_URL	-	OIDC client URL
DAGU_AUTH_OIDC_ISSUER	-	OIDC issuer URL
DAGU_AUTH_OIDC_SCOPES	-	OIDC scopes (comma-separated)
DAGU_AUTH_OIDC_WHITELIST	-	OIDC email whitelist (comma-separated)

UI Configuration

Environment Variable	Default	Description
DAGU_UI_NAVBAR_COLOR	#1976d2	UI header color (hex or name)
DAGU_UI_NAVBAR_TITLE	Dagu	UI header title
DAGU_UI_LOG_ENCODING_CHARSET	utf-8	Log file encoding
DAGU_UI_MAX_DASHBOARD_PAGE_LIMIT	100	Maximum items on dashboard
DAGU_UI_DAGS_SORT_FIELD	name	Default DAGs sort field
DAGU_UI_DAGS_SORT_ORDER	asc	Default DAGs sort order

Scheduler Configuration

Environment Variable	Default	Description
DAGU_SCHEDULER_PORT	8090	Health check server port
DAGU_SCHEDULER_LOCK_STALE_THRESHOLD	30s	Scheduler lock stale threshold
DAGU_SCHEDULER_LOCK_RETRY_INTERVAL	5s	Lock retry interval
DAGU_SCHEDULER_ZOMBIE_DETECTION_INTERVAL	45s	Zombie DAG detection interval (0 to disable)
DAGU_QUEUE_ENABLED	true	Enable queue system

Worker Configuration

This configuration is used for worker instances that execute DAGs. See the Distributed Execution documentation for more details.

Environment Variable	Default	Description
DAGU_COORDINATOR_HOST	127.0.0.1	Coordinator gRPC server bind address
DAGU_COORDINATOR_ADVERTISE	(auto)	Address to advertise in service registry (default: hostname)
DAGU_COORDINATOR_PORT	50055	Coordinator gRPC server port
DAGU_WORKER_ID	-	Worker instance ID
DAGU_WORKER_MAX_ACTIVE_RUNS	100	Maximum concurrent runs per worker
DAGU_WORKER_LABELS	-	Worker labels (format: key1=value1,key2=value2, e.g., gpu=true,memory=64G)
DAGU_SCHEDULER_PORT	8090	Scheduler health check server port
DAGU_SCHEDULER_LOCK_STALE_THRESHOLD	30s	Time after which scheduler lock is considered stale
DAGU_SCHEDULER_LOCK_RETRY_INTERVAL	5s	Interval between lock acquisition attempts

Peer Configuration

This configuration is used for communication between coordinator services and other services (e.g., scheduler, worker, web UI). See the Distributed Execution documentation for more details.

Environment Variable	Default	Description
DAGU_PEER_CERT_FILE	-	Peer TLS certificate file
DAGU_PEER_KEY_FILE	-	Peer TLS key file
DAGU_PEER_CLIENT_CA_FILE	-	Peer CA certificate file for client verification
DAGU_PEER_SKIP_TLS_VERIFY	false	Skip TLS certificate verification for peer connections
DAGU_PEER_INSECURE	true	Use insecure connection (h2c) instead of TLS

Development

Building from Source

Prerequisites

• Go 1.25+
• Node.js
• pnpm

1. Clone the repository and build server

git clone https://github.com/dagu-org/dagu.git && cd dagu
make

This will start the dagu server at http://localhost:8080.

2. Run the frontend development server

cd ui
pnpm install
pnpm dev

Navigate to http://localhost:8081 to view the frontend.

Running Tests

To ensure the integrity of the go code, you can run all Go unit and integration tests.

Run all tests from the project root directory:

make test

To run tests with code coverage analysis:

make make-coverage

Feature Matrix

Dagu is designed to be a comprehensive solution for workflow orchestration. Below is a detailed list of currently supported capabilities.

Category	Capability	Description	Link
Core Execution	Local execution	Run workflows locally with CLI / Web UI / API	CLI, Web UI
	Queue based execution	Dispatch DAG execution to workers with labels and priorities	Queues
	Immediate execution	Disable queue for immediate execution	CLI
	Idempotency	Prevent duplicate DAG execution with same DAG-run ID	start command
	Status management	queued → running → succeeded/partially_succeeded/failed/aborted	Status Management
	Cancel propagation	Cancel signals to sub-DAG
	Cleanup hooks	Define cleanup processing with onExit handlers	Lifecycle Handlers
	Status hooks	Define hooks on success / failure / cancel	Lifecycle Handlers
Definition & DSL	Declarative YAML DSL	Validation with JSON Schema, display error locations	YAML Specification
	Environment variables	Environment variables at DAG and step level, support dotenv	Environment Variables
	Command substitution	Use command output as value for variables or parameters	Command Substitution
	Shell support	Use shell features like pipes, redirects, globbing, etc.	Shell Executor
	Script support	Use scripts in Python, Bash, etc. as steps	Script Execution
	Modular DAGs	Reusable DAGs with params	Base Configuration
	Secrets management	Reference-only secrets via KMS/Vault/OIDC	Secrets
Control Structures	Fan-out/Fan-in	Native parallel branches + join	Parallel Execution
	Iteration (loop)	Iteration over list values	Parallel Execution
	Conditional routes	Data/expression based routing	Conditional Execution
	Sub-DAG call	Reusable sub-DAG	Parallel Execution
	Worker & Dispatch	Runs DAG on different nodes with selector conditions	Distributed Execution
	Retry policies	Retry with backoff/interval	Retry Policies
	Repeat Policies	Repeat step until condition is met	Repeat Policies
	Timeout management	DAG Execution Timeouts	Workflow Timeout
Triggers & Scheduling	Cron expression	Schedule to start / stop / restart	Scheduling
	Multiple schedules	Multiple schedules per DAG	Multiple Schedules
	Timezone support	Per-DAG timezone for cron schedules	Timezone Support
	Skip	Skip an execution when a previous manual run was successful	Skip Redundant Runs
	Zombie detection	Automatic detection for processes terminated unexpectedly	Scheduling
	Trigger via Web API	Web API to start DAG executions	Web API
Container Native	Step-level container config	Run steps in Docker containers with granular control	Docker Executor
	DAG level container config	Run all steps in a container with shared volumes and env vars	Container Field
	Authorized registry access	Access private registries with credentials	Registry Auth
Data & Artifacts	Passing data between steps	Passing ephemeral data between steps in a DAG	Data Flow
	Secret redaction	Auto-mask secrets in logs/events	Secrets
	Automatic log cleanup	Automatic log cleanup based on retention policies	Log Retention
Observability	Logging with live streaming	Structured JSON logs with live tail streaming	Log Viewer
	Metrics	Prometheus metrics	Metrics
	OpenTelemetry	Distributed tracing with OpenTelemetry	OpenTelemetry
	DAG Visualization	DAG / Gantt charts for critical path analysis	DAG Visualization
	Email notification	Email notification on success / failure with the log file attachment	Email Notifications
	Health monitoring	Health check for scheduler & failover	Health Check
	Nested-DAG visualization	Nested DAG visualization with drill down functionality	Nested DAG Visualization
Security & Governance	Secret injection	Vault/KMS/OIDC ref-only; short-lived tokens	Secrets
	Authentication	Basic auth / OIDC support for Web UI and API	Authentication
	HA (High availability) mode	Control-plane with failover for scheduler / Web UI / Coordinator	High Availability
Executor types	jq	JSON processing with jq queries	JQ Executor
	ssh	Remote command execution via SSH	SSH Executor
	docker	Container-based task execution	Docker Executor
	http	HTTP/REST API calls with retry	HTTP Executor
	mail	Send emails with template	Mail Executor
	archive	Archive/unarchive operations (zip, tar, etc.)	Archive Executor
DevX & Testing	Local development	offline runs	CLI Usage
	Dry-run	DAG level Dry-run	dry command
UI & Operations	Run / retry / cancel operations	Start / enqueue / retry / stop	DAG Operations
	Automatic parameter forms	Auto-generate parameter forms for DAGs	Web UI
	DAG definition search	Filter by tag / name	DAG Search
	Execution history search	Filter by status / date-range / name	History Search
	Step-level operations	Rerun, resume from step	Web UI
	Parameter override	Override parameters for a DAG run
	Scheduled DAG management	Enable/disable schedule for a DAG	Web UI
	UI organization	Logical DAG grouping	DAG Organization
	Windows support	Windows support

Roadmap

Our roadmap is driven by community feedback and our mission to make Dagu the most developer-friendly workflow engine.

💡 Have an idea? Open a Feature Request or join the Discord to discuss!

🏗️ In Progress

Active development focus. These features are expected to land in the upcoming releases.

• Windows Support: Native support for Windows OS to ensure Dagu runs seamlessly across all major platforms.
• JSON Schema Validation (#325): Strict validation for DAG parameters to catch configuration errors early.
• Resource Limits: Configurable CPU and Memory limits per step to prevent resource exhaustion.

📅 Planned (Short-term)

High-priority features selected for the near future.

Core Engine

• Human-in-the-loop (#978): Support for manual approval steps (blocking wait) within a workflow—enabling human task integration for wizards and approval gates.
• File Watcher Trigger (#372): Event-driven triggers that start DAGs when specific files change.
• Webhook Triggers & Callbacks: Outbound webhook notifications for workflow events.
• Inter-DAG State: Mechanisms to explicitly share state and data artifacts between different DAG runs.
• External Database Backend (#539): Support for PostgreSQL/MySQL persistence for high-scale deployments (removing reliance on local disk).

Developer Experience

• Edit & Retry (#326, #1058): Capability to hot-fix a DAG definition and immediately retry a failed run from the UI.
• Single Step Execution (#1047): Ability to trigger a specific step in isolation for testing and debugging purposes.

Operations

• Pause/Resume DAGs: Global or per-DAG controls to pause scheduling without modifying YAML files.
• Project / Namespace: Logical grouping of DAGs and execution history per project/team with data segregation for multi-tenant deployments.

🔮 Future (Long-term)

Strategic goals and complex features under consideration.

• Kubernetes Native Execution (#837): Run steps as native K8s jobs/pods for massive scalability.
• Catch Up & Backfill (#695): Robust handling of missed schedule runs and historical data processing.
• RBAC & Multi-User Auth: Fine-grained permissions, user roles, resource quotas, and tenant-scoped API access for SaaS deployments.
• Multi-Tenant Isolation: Full tenant isolation with data segregation, separate execution contexts, and per-tenant resource limits.
• Real-time Notifications: WebSocket-based live notifications for workflow status changes and step completions.
• Audit Logging: Immutable records of all user actions and system events.
• SDK & Plugins (#583): Python/Go/TS SDKs for programmatic DAG generation and a plugin system for custom executors.

Discussion

For discussions, support, and sharing ideas, join our community on Discord.

Recent Updates

Changelog of recent updates can be found in the Changelog section of the documentation.

Contributing

We welcome contributions of all kinds! Whether you're a developer, a designer, or a user, your help is valued. Here are a few ways to get involved:

• Star the project on GitHub.
• Suggest new features by opening an issue.
• Join the discussion on our Discord server.
• Contribute code: Check out our issues you can help with.

For more details, see our Contribution Guide.

Acknowledgements

Contributors

Thanks to all the contributors who have helped make Dagu better! Your contributions, whether through code, documentation, or feedback, are invaluable to the project.

Sponsors & Supporters

Thanks for supporting Dagu’s development! Join our supporters: GitHub Sponsors

License

GNU GPLv3 - See LICENSE