Configuration Reference

All Dagu configuration options.

For configuration precedence, file locations, DAGU_HOME, and path defaults, see Configuration.

Configuration File

Default: ~/.config/dagu/config.yaml

# Server
host: "127.0.0.1"
port: 8080
public_url: ""            # External Web UI URL for generated links
base_path: ""              # For reverse proxy (e.g., "/dagu")
api_base_path: "/api/v1"    # API endpoint base path
tz: "America/New_York"
debug: false
log_format: "text"         # "text" or "json"
access_log_mode: "all"     # Access log mode: "all", "non-public", or "none"
headless: false
check_updates: true       # Automatic web UI update checks (default: true)
skip_examples: false       # Skip creating example DAGs
metrics: "private"        # Metrics endpoint: "private" (default) or "public"
cors_allowed_origins: []  # Empty disables cross-origin browser access (default)
cache: "normal"            # Cache mode

# Terminal (web-based shell access)
terminal:
  enabled: false          # Enable web terminal (default: false)
  max_sessions: 5         # Max concurrent terminals per server (default: 5)

# Audit Logging
audit:
  enabled: true           # Enable audit logging (default: true)
  retention_days: 7        # Days to keep audit logs (default: 7, 0 = keep forever)

# Centralized Event Store
event_store:
  enabled: true           # Enable centralized event logging (default: true)
  retention_days: 1        # Days to keep event log files (default: 1, 0 = keep forever)

# Webhook Trigger Limits
webhooks:
  max_payload_size: 1048576 # Max accepted webhook payload size in bytes (default: 1MiB)

# Server-Sent Events
sse:
  max_topics_per_connection: 20
  max_clients: 1000
  heartbeat_interval: "10s"
  write_buffer_size: 65536
  slow_client_timeout: "30s"

# Directories (must be under "paths" key)
paths:
  dags_dir: "~/.config/dagu/dags"
  docs_dir: ""                # Auto: {dags_dir}/docs
  alt_dags_dir: ""          # Additional read-only DAG directories
  log_dir: "~/.local/share/dagu/logs"
  data_dir: "~/.local/share/dagu/data"
  tools_dir: ""              # Auto: {data_dir}/tools
  artifact_dir: ""           # Auto: {data_dir}/artifacts
  dag_state_dir: ""           # Auto: {data_dir}/dag-state
  suspend_flags_dir: "~/.local/share/dagu/suspend"
  admin_logs_dir: "~/.local/share/dagu/logs/admin"
  event_store_dir: ""        # Auto: {admin_logs_dir}/events
  base_config: "~/.config/dagu/base.yaml"
  dag_runs_dir: ""            # Auto: {data_dir}/dag-runs
  queue_dir: ""              # Auto: {data_dir}/queue
  proc_dir: ""               # Auto: {data_dir}/proc
  service_registry_dir: ""    # Auto: {data_dir}/service-registry
  users_dir: ""              # Auto: {data_dir}/users
  contexts_dir: ""           # Auto: {data_dir}/contexts
  workspaces_dir: ""         # Auto: {data_dir}/workspaces
  executable: ""            # Auto: current executable path

# DAG definition discovery
dag_discovery:
  recursive: false          # Discover DAGs below paths.dags_dir (default: false)

# External Secret Providers
secrets:
  vault:
    address: "https://vault.example.com"
    token: "hvs.DummyToken"
    ca_cert: ""        # Path to a CA certificate file for verifying a custom/private Vault TLS endpoint
    client_cert: ""    # Path to a client certificate file for mTLS authentication to Vault
    client_key: ""     # Path to a client key file paired with `client_cert`

# Permissions
permissions:
  write_dags: true         # Create/edit/delete DAGs
  run_dags: true           # Run/stop/retry DAGs

# Authentication
auth:
  mode: "builtin"          # "none", "basic", or "builtin" (default)

  # Builtin auth (user management with RBAC)
  builtin:
    token:
      secret: "your-secret-key"  # Auto-generated if not set
      ttl: "24h"

  # Basic auth (simple username/password)
  basic:
    username: "admin"
    password: "secret"

  # OIDC auth (auto-enabled under builtin mode when all required fields are set)
  oidc:
    client_id: "your-client-id"
    client_secret: "your-client-secret"
    client_url: "https://dagu.example.com"
    issuer: "https://accounts.google.com"
    scopes: ["openid", "profile", "email"]
    # Builtin-specific settings (only when mode=builtin)
    auto_signup: true         # Auto-create users on first login
    role_mapping:
      # Used for unmatched users when default_workspace_access is "all"
      default_role: "viewer"
      group_mappings: {}       # OIDC group to global Dagu role map
      workspace_mappings: {}   # OIDC group to workspace grant lists
      # Required when workspace_mappings is non-empty; defaults to "all" otherwise
      default_workspace_access: "all"
    allowed_domains: []       # Restrict by email domain
    button_label: "Login with SSO"

  # Proxy authentication (enabled under builtin mode)
  proxy:
    enabled: false
    source: ""                # Optional identity namespace
    button_label: "Continue with SSO"
    headers:
      user: "X-Auth-Request-User"
      groups: "X-Auth-Request-Groups"
    auto_signup: true
    role_mapping:
      default_role: "viewer"
      group_mappings: {}
      workspace_mappings: {}
      default_workspace_access: "none"
      require_mapping: false
      skip_org_role_sync: false

# TLS/HTTPS
tls:
  cert_file: "/path/to/cert.pem"
  key_file: "/path/to/key.pem"

# UI
ui:
  navbar_color: "#1976d2"     # Hex or CSS color
  navbar_title: "Dagu"
  log_encoding_charset: "utf-8"  # Character encoding for log files (see supported encodings below)
  max_dashboard_page_limit: 100
  dags:
    sort_field: "name"        # Default DAG list request sort field (`name` or `nextRun`)
    sort_order: "asc"         # Default sort order (asc/desc)

latest_status_today: true      # Show only today's status

# Execution
default_execution_mode: "local"  # "local" (default) or "distributed"
default_shell: ""           # Default shell for command steps
env_passthrough:
  - SSL_CERT_FILE
  - HTTP_PROXY
env_passthrough_prefixes:
  - AWS_

# Queues
queues:
  enabled: true          # Default: true
  config:
    - name: "critical"
      max_concurrency: 5   # Maximum concurrent DAG runs
    - name: "batch"
      max_concurrency: 1
    - name: "default"
      max_concurrency: 2

# Remote Nodes
remote_nodes:
  - name: "staging"
    api_base_url: "https://staging.example.com/api/v1"
    auth_type: "basic"
    basic_auth_username: "admin"
    basic_auth_password: "password"
  - name: "production"
    api_base_url: "https://prod.example.com/api/v1"
    auth_type: "token"
    auth_token: "prod-token"
    skip_tls_verify: false

# Coordinator (for distributed execution)
coordinator:
  enabled: true           # Enable coordinator (default: true)
  host: "127.0.0.1"       # Bind address
  port: 50055             # gRPC port
  health_port: 8091       # HTTP health check port (0 to disable)

# Worker (for distributed execution)
worker:
  id: ""                  # Worker ID (default: hostname@PID)
  coordinators: []          # Explicit coordinator addresses for shared-nothing mode
  max_active_runs: 100      # Max parallel task executions
  health_port: 8092         # HTTP health check port (0 to disable)
  labels:                 # Worker capabilities
    gpu: "false"
    memory: "16G"
    region: "us-east-1"
  postgres_pool:           # PostgreSQL connection pool (shared-nothing mode only)
    max_open_conns: 25      # Total connections across ALL PostgreSQL DSNs (default: 25)
    max_idle_conns: 5       # Idle connections per DSN (default: 5)
    conn_max_lifetime: 300  # Connection lifetime in seconds (default: 300)
    conn_max_idle_time: 60   # Idle connection timeout in seconds (default: 60)

# Peer TLS configuration (for distributed execution)
peer:
  insecure: true          # Use h2c instead of TLS (default: true)
  cert_file: ""            # TLS certificate for peer connections
  key_file: ""             # TLS key for peer connections
  client_ca_file: ""        # CA certificate for peer verification
  skip_tls_verify: false    # Skip TLS certificate verification

# Scheduler
scheduler:
  port: 8090              # Health check port (0 to disable)
  lock_stale_threshold: "30s"  # Time after which a scheduler lock is considered stale
  lock_retry_interval: "5s"   # Interval between lock acquisition attempts
  zombie_detection_interval: "45s"  # Interval for detecting zombie DAG runs (0 to disable)
  retry_failure_window: "24h"  # Lookback window for DAG-level retry scanning (0 to disable). Current limitation: window uses the original DAG-run time bucket, not the latest failed attempt timestamp.
  failure_threshold: 3             # Consecutive stale checks before marking a run as failed

# Local proc heartbeat/liveness (used by all local run owners: server, scheduler, CLI runs, and workers)
proc:
  heartbeat_interval: "5s"         # How often local workflow processes write a heartbeat timestamp
  heartbeat_sync_interval: "10s"   # How often heartbeat files are fsynced to disk
  stale_threshold: "90s"           # Time after which a heartbeat is considered stale

# Resource Monitoring
monitoring:
  retention: "24h"        # How long to keep resource history (default: 24h)
  interval: "5s"          # How often to collect metrics (default: 5s)

# Git Sync
git_sync:
  enabled: false
  repository: "github.com/your-org/dags"
  branch: "main"
  path: ""                 # Subdirectory in repo (empty = root)
  push_enabled: true

  auth:
    type: "token"          # "token" or "ssh"
    token: "${GITHUB_TOKEN}"
    ssh_key_path: ""
    ssh_passphrase: ""

  auto_sync:
    enabled: false
    on_startup: true
    interval: 300          # Seconds (0 = no periodic sync)

  commit:
    author_name: "Dagu"
    author_email: "dagu@localhost"

Environment Variables

All options support DAGU_ prefix.

Note: Dagu filters which system environment variables are passed to step processes and sub-DAG executions. Built-in forwarding includes the platform allowlist plus the prefixes DAGU_, DAG_, LC_, and KUBERNETES_. You can extend that set with top-level env_passthrough and env_passthrough_prefixes. See Operations - Security for exact behavior.

Server

• DAGU_HOST - Server host (default: 127.0.0.1)
• DAGU_PORT - Server port (default: 8080)
• DAGU_PUBLIC_URL - External Web UI URL used in generated links, including notification and incident DAG-run links
• DAGU_BASE_PATH - Base path for reverse proxy
• DAGU_API_BASE_URL - DEPRECATED - Use api_base_path config instead
• DAGU_TZ - Server timezone
• DAGU_ENV_PASSTHROUGH - Comma-separated exact env var names to forward to step execution
• DAGU_ENV_PASSTHROUGH_PREFIXES - Comma-separated env var prefixes to forward to step execution
• DAGU_DEBUG - Enable debug mode
• DAGU_LOG_FORMAT - Log format (text/json)
• DAGU_ACCESS_LOG_MODE - Access log mode (all, non-public, or none; default: all)
• DAGU_HEADLESS - Run without UI
• DAGU_CHECK_UPDATES - Enable automatic web UI update checks (default: true)
• DAGU_LATEST_STATUS_TODAY - Show only today's status
• DAGU_SKIP_EXAMPLES - Skip automatic creation of example DAGs (default: false)
• DAGU_SERVER_METRICS - Metrics endpoint access: private (default) or public
• DAGU_CACHE - Cache mode (default: normal)

Terminal

• DAGU_TERMINAL_ENABLED - Enable web-based terminal (default: false)
• DAGU_TERMINAL_MAX_SESSIONS - Maximum concurrent terminal sessions (default: 5)

Audit Logging

• DAGU_AUDIT_ENABLED - Enable audit logging (default: true)
• DAGU_AUDIT_RETENTION_DAYS - Days to keep audit logs (default: 7, 0 = keep forever)

Event Store

• DAGU_EVENT_STORE_ENABLED - Enable centralized event logging (default: true)
• DAGU_EVENT_STORE_RETENTION_DAYS - Days to keep event log files (default: 1, 0 = keep forever)

Webhooks

• DAGU_WEBHOOKS_MAX_PAYLOAD_SIZE - Max accepted webhook payload size in bytes (default: 1048576)

Server-Sent Events

• DAGU_SSE_MAX_TOPICS_PER_CONNECTION - Max subscribed topics per SSE connection (default: 20)
• DAGU_SSE_MAX_CLIENTS - Max concurrent SSE clients (default: 1000)
• DAGU_SSE_HEARTBEAT_INTERVAL - SSE heartbeat interval (default: 10s)
• DAGU_SSE_WRITE_BUFFER_SIZE - Per-client SSE write buffer size (default: 65536)
• DAGU_SSE_SLOW_CLIENT_TIMEOUT - Timeout for slow SSE clients (default: 30s)

Directories

• DAGU_HOME - Set all directories to this path (can be overridden by --dagu-home flag)
• DAGU_DAGS_DIR - DAG definitions
• DAGU_DAGS - Alternative to DAGU_DAGS_DIR
• DAGU_DOCS_DIR - Markdown documents and runbooks (default: {dags_dir}/docs)
• DAGU_ALT_DAGS_DIR - Additional read-only DAG directories
• DAGU_LOG_DIR - Log files
• DAGU_DATA_DIR - Application data
• DAGU_TOOLS_DIR - Managed DAG tool cache (default: {data_dir}/tools)
• DAGU_ARTIFACT_DIR - DAG run artifact directory (default: {data_dir}/artifacts)
• DAGU_DAG_STATE_DIR - Persistent DAG state directory (default: {data_dir}/dag-state)
• DAGU_SUSPEND_FLAGS_DIR - Suspend flags
• DAGU_ADMIN_LOG_DIR - Admin logs
• DAGU_EVENT_STORE_DIR - Centralized event log directory (default: {admin_logs_dir}/events)
• DAGU_BASE_CONFIG - Base configuration
• DAGU_DAG_RUNS_DIR - DAG run data directory
• DAGU_QUEUE_DIR - Queue data directory
• DAGU_PROC_DIR - Process data directory
• DAGU_SERVICE_REGISTRY_DIR - Service registry data directory
• DAGU_USERS_DIR - User data directory (default: {data_dir}/users)
• DAGU_CONTEXTS_DIR - CLI contexts directory (default: {data_dir}/contexts)
• DAGU_WORKSPACES_DIR - Workspace data directory (default: {data_dir}/workspaces)
• DAGU_EXECUTABLE - Path to Dagu executable

Note: The --dagu-home CLI flag takes precedence over the DAGU_HOME environment variable.

paths.artifact_dir is the global artifact base directory. A DAG can override it with artifacts.dir.

DAG Discovery

• DAGU_DAG_DISCOVERY_RECURSIVE - Discover .yaml and .yml DAG definitions recursively below paths.dags_dir (default: false)

When recursive discovery is enabled, file stems and effective DAG names must each be unique across the discovered tree. Conflicting DAGs are excluded until the conflict is resolved. See Recursive DAG Discovery for traversal and Web UI behavior.

Authentication

• DAGU_AUTH_MODE - Authentication mode: none, basic, or builtin (default: builtin)

Builtin Auth (RBAC)

• DAGU_AUTH_TOKEN_SECRET - JWT signing secret (auto-generated if not set)
• DAGU_AUTH_TOKEN_TTL - JWT token expiry (default: 24h, maximum: 8760h / 365 days)
• DAGU_AUTH_BUILTIN_INITIAL_ADMIN_USERNAME - Auto-provision admin username on first startup (requires password)
• DAGU_AUTH_BUILTIN_INITIAL_ADMIN_PASSWORD - Auto-provision admin password on first startup (requires username, minimum 8 characters)
• DAGU_USERS_DIR - User data directory (default: {data_dir}/users)

Basic Auth

• DAGU_AUTH_BASIC_USERNAME - Basic auth username
• DAGU_AUTH_BASIC_PASSWORD - Basic auth password

OIDC Auth

OIDC settings (used under builtin auth mode, auto-enabled when all required fields are set):

See OIDC Workspace Access for mapping evaluation, fallback, and synchronization behavior.

• DAGU_AUTH_OIDC_CLIENT_ID - OAuth2 client ID from your OIDC provider
• DAGU_AUTH_OIDC_CLIENT_SECRET - OAuth2 client secret
• DAGU_AUTH_OIDC_CLIENT_URL - Base URL of your Dagu instance (for callback)
• DAGU_AUTH_OIDC_ISSUER - OIDC provider URL
• DAGU_AUTH_OIDC_SCOPES - OAuth2 scopes (comma-separated, default: openid,profile,email)
• DAGU_AUTH_OIDC_WHITELIST - Email addresses allowed to authenticate (comma-separated)

Builtin-specific OIDC settings (only used when auth.mode=builtin):

• DAGU_AUTH_OIDC_AUTO_SIGNUP - Auto-create users on first OIDC login (default: true)
• DAGU_AUTH_OIDC_DEFAULT_ROLE - Role assigned across all workspaces when no mapping matches and DAGU_AUTH_OIDC_DEFAULT_WORKSPACE_ACCESS=all (default: viewer)
• DAGU_AUTH_OIDC_GROUP_MAPPINGS - OIDC group-to-role mappings
• DAGU_AUTH_OIDC_WORKSPACE_MAPPINGS - OIDC group-to-workspace grants as a JSON object
• DAGU_AUTH_OIDC_DEFAULT_WORKSPACE_ACCESS - Unmapped-user workspace access (all or none); required with workspace mappings, otherwise defaults to all
• DAGU_AUTH_OIDC_ALLOWED_DOMAINS - Email domains allowed to authenticate (comma-separated)
• DAGU_AUTH_OIDC_BUTTON_LABEL - SSO login button text (default: Login with SSO)
• DAGU_AUTH_OIDC_GROUPS_CLAIM - JWT claim containing group membership (default: groups)
• DAGU_AUTH_OIDC_ROLE_ATTRIBUTE_PATH - jq expression for role extraction
• DAGU_AUTH_OIDC_ROLE_ATTRIBUTE_STRICT - Deny login when neither a global nor workspace mapping matches (default: false)
• DAGU_AUTH_OIDC_SKIP_ORG_ROLE_SYNC - Only assign role and workspace access on first login (default: false)

Proxy authentication

These settings add proxy login to builtin auth mode. See Proxy authentication for configuration, identity headers, access mapping, and network requirements.

• DAGU_AUTH_PROXY_ENABLED - Enable proxy authentication (default: false)
• DAGU_AUTH_PROXY_SOURCE - Optional identity namespace (default: empty)
• DAGU_AUTH_PROXY_BUTTON_LABEL - Login-page option text (default: Continue with SSO)
• DAGU_AUTH_PROXY_HEADERS_USER - Header containing the stable user identity
• DAGU_AUTH_PROXY_HEADERS_GROUPS - Header containing CSV group names; required when mappings are configured
• DAGU_AUTH_PROXY_AUTO_SIGNUP - Create users on first login (default: true)
• DAGU_AUTH_PROXY_DEFAULT_ROLE - Global fallback role when default workspace access is all (default: viewer)
• DAGU_AUTH_PROXY_GROUP_MAPPINGS - Group-to-global-role mappings as a JSON object
• DAGU_AUTH_PROXY_WORKSPACE_MAPPINGS - Group-to-workspace-grant mappings as a JSON object
• DAGU_AUTH_PROXY_DEFAULT_WORKSPACE_ACCESS - Unmatched-user workspace access (all or none; default: none)
• DAGU_AUTH_PROXY_REQUIRE_MAPPING - Deny login when no global or workspace mapping matches (default: false)
• DAGU_AUTH_PROXY_SKIP_ORG_ROLE_SYNC - Keep stored role and workspace access on later logins (default: false)

By default, unmatched users can sign in with viewer and no named-workspace grants. Set DAGU_AUTH_PROXY_REQUIRE_MAPPING=true to reject them.

TLS/HTTPS

• DAGU_CERT_FILE - SSL certificate
• DAGU_KEY_FILE - SSL key

UI

• DAGU_UI_NAVBAR_COLOR - Nav bar color
• DAGU_UI_NAVBAR_TITLE - Nav bar title
• DAGU_UI_LOG_ENCODING_CHARSET - Log file character encoding (see Supported Log Encodings)
• DAGU_UI_MAX_DASHBOARD_PAGE_LIMIT - Dashboard limit
• DAGU_UI_DAGS_SORT_FIELD - Default DAGs page request sort field (name or nextRun)
• DAGU_UI_DAGS_SORT_ORDER - Default DAGs page sort order

Queue

• DAGU_QUEUE_ENABLED - Enable queue system (default: true)

Execution

• DAGU_DEFAULT_EXECUTION_MODE - Default execution mode: local (default) or distributed. When distributed, all DAGs are dispatched to workers through the coordinator, even without an explicit worker_selector. Use worker_selector: local in a DAG to override.
• DAGU_DEFAULT_SHELL - Default shell for command steps. When unset, Dagu falls back to $SHELL, then sh.
• DAGU_CONTAINER_RUNTIME - Container runtime for root-level container:, step-level container:, docker.run, and containerized harness.run. Valid values: docker (default) or podman.
• DAGU_PODMAN_HOST - Podman's Docker-compatible API socket when DAGU_CONTAINER_RUNTIME=podman (default: unix:///run/podman/podman.sock).

DAGU_CONTAINER_RUNTIME and DAGU_PODMAN_HOST are read from the Dagu process environment. They are not DAG YAML fields and cannot be selected from DAG-level or step-level env:.

Coordinator

• DAGU_COORDINATOR_ENABLED - Enable coordinator service (default: true)
• DAGU_COORDINATOR_HOST - Coordinator bind address (default: 127.0.0.1)
• DAGU_COORDINATOR_ADVERTISE - Address to advertise in service registry (default: auto-detected hostname)
• DAGU_COORDINATOR_PORT - Coordinator gRPC port (default: 50055)
• DAGU_COORDINATOR_HEALTH_PORT - Coordinator HTTP health check port (default: 8091, 0 to disable)

Worker

• DAGU_WORKER_ID - Worker instance ID (default: hostname@PID)
• DAGU_WORKER_MAX_ACTIVE_RUNS - Max concurrent task executions (default: 100)
• DAGU_WORKER_HEALTH_PORT - Worker HTTP health check port (default: 8092, 0 to disable)
• DAGU_WORKER_LABELS - Worker labels (format: key1=value1,key2=value2)
• DAGU_WORKER_COORDINATORS - Explicit coordinator addresses for shared-nothing mode
• DAGU_WORKER_POSTGRES_POOL_MAX_OPEN_CONNS - PostgreSQL max open connections across all DSNs (default: 25)
• DAGU_WORKER_POSTGRES_POOL_MAX_IDLE_CONNS - PostgreSQL max idle connections per DSN (default: 5)
• DAGU_WORKER_POSTGRES_POOL_CONN_MAX_LIFETIME - PostgreSQL connection max lifetime in seconds (default: 300)
• DAGU_WORKER_POSTGRES_POOL_CONN_MAX_IDLE_TIME - PostgreSQL connection max idle time in seconds (default: 60)

Peer (for distributed TLS)

• DAGU_PEER_INSECURE - Use insecure connection (default: true)
• DAGU_PEER_CERT_FILE - TLS certificate for peer connections
• DAGU_PEER_KEY_FILE - TLS key for peer connections
• DAGU_PEER_CLIENT_CA_FILE - CA certificate for peer verification
• DAGU_PEER_SKIP_TLS_VERIFY - Skip TLS certificate verification

Scheduler

• DAGU_SCHEDULER_PORT - Health check server port (default: 8090)
• DAGU_SCHEDULER_LOCK_STALE_THRESHOLD - Time after which a scheduler lock is considered stale (default: 30s)
• DAGU_SCHEDULER_LOCK_RETRY_INTERVAL - Interval between lock acquisition attempts (default: 5s)
• DAGU_SCHEDULER_ZOMBIE_DETECTION_INTERVAL - Interval for detecting zombie DAG runs (default: 45s, 0 to disable)
• DAGU_SCHEDULER_RETRY_FAILURE_WINDOW - Lookback window for DAG-level retry scanning (default: 24h, 0 to disable)
• DAGU_SCHEDULER_FAILURE_THRESHOLD - Consecutive stale checks before marking a run as failed (default: 3)

Proc Liveness

These settings apply to all locally owned DAG runs, not just dagu scheduler.

• DAGU_PROC_HEARTBEAT_INTERVAL - How often local workflow processes write a heartbeat timestamp (default: 5s)
• DAGU_PROC_HEARTBEAT_SYNC_INTERVAL - How often heartbeat files are fsynced to disk (default: 10s)
• DAGU_PROC_STALE_THRESHOLD - Time after which a heartbeat is considered stale (default: 90s)
• DAGU_SCHEDULER_HEARTBEAT_INTERVAL - Deprecated alias for DAGU_PROC_HEARTBEAT_INTERVAL
• DAGU_SCHEDULER_HEARTBEAT_SYNC_INTERVAL - Deprecated alias for DAGU_PROC_HEARTBEAT_SYNC_INTERVAL
• DAGU_SCHEDULER_STALE_THRESHOLD - Deprecated alias for DAGU_PROC_STALE_THRESHOLD

Legacy YAML keys scheduler.heartbeat_interval, scheduler.heartbeat_sync_interval, and scheduler.stale_threshold are also still accepted as deprecated aliases. Use proc.* for new configuration. If both are set, proc.* takes precedence.

Resource Monitoring

• DAGU_MONITORING_RETENTION - How long to keep resource history (default: 24h)
• DAGU_MONITORING_INTERVAL - How often to collect resource metrics (default: 5s)

Tunnel

• DAGU_TUNNEL / DAGU_TUNNEL_ENABLED - Enable the Tailscale tunnel
• DAGU_TUNNEL_TAILSCALE_AUTH_KEY - Tailscale auth key
• DAGU_TUNNEL_TAILSCALE_HOSTNAME - Tailscale hostname
• DAGU_TUNNEL_TAILSCALE_FUNNEL - Enable Tailscale Funnel
• DAGU_TUNNEL_TAILSCALE_HTTPS - Enable HTTPS for the tunnel
• DAGU_TUNNEL_TAILSCALE_STATE_DIR - Tailscale tunnel state directory
• DAGU_TUNNEL_ALLOW_TERMINAL - Allow terminal access through the tunnel
• DAGU_TUNNEL_ALLOWED_IPS - Comma-separated allowed source IP ranges
• DAGU_TUNNEL_RATE_LIMITING_ENABLED - Enable tunnel login rate limiting
• DAGU_TUNNEL_RATE_LIMITING_LOGIN_ATTEMPTS - Allowed login attempts per window
• DAGU_TUNNEL_RATE_LIMITING_WINDOW_SECONDS - Login rate-limit window in seconds
• DAGU_TUNNEL_RATE_LIMITING_BLOCK_DURATION_SECONDS - Login rate-limit block duration in seconds

License

• DAGU_LICENSE_KEY - License key
• DAGU_LICENSE_CLOUD_URL - License validation service URL

External Secrets

• DAGU_SECRETS_VAULT_ADDRESS - Default Vault server address for the vault secret provider
• DAGU_SECRETS_VAULT_TOKEN - Default Vault token for the vault secret provider
• DAGU_SECRETS_VAULT_CA_CERT - Path to a CA certificate file for verifying a custom/private Vault TLS endpoint
• DAGU_SECRETS_VAULT_CLIENT_CERT - Path to a client certificate file for mTLS authentication to Vault
• DAGU_SECRETS_VAULT_CLIENT_KEY - Path to a client key file paired with DAGU_SECRETS_VAULT_CLIENT_CERT
• DAGU_SECRETS_KUBERNETES_NAMESPACE - Default namespace for the kubernetes secret provider
• DAGU_SECRETS_KUBERNETES_KUBECONFIG - Default kubeconfig path for the kubernetes secret provider
• DAGU_SECRETS_KUBERNETES_CONTEXT - Default kubeconfig context for the kubernetes secret provider

Git Sync

• DAGU_GITSYNC_ENABLED - Enable git sync (default: false)
• DAGU_GITSYNC_REPOSITORY - Remote repository URL. For SSH servers that require a username other than git, include it in the URL, for example deploy@git.example.com:org/dags.git.
• DAGU_GITSYNC_BRANCH - Branch to sync (default: main)
• DAGU_GITSYNC_PATH - Subdirectory in repo (default: "")
• DAGU_GITSYNC_PUSH_ENABLED - Enable push operations (default: true)
• DAGU_GITSYNC_AUTH_TYPE - Auth type: token or ssh (default: token)
• DAGU_GITSYNC_AUTH_TOKEN - Personal access token for HTTPS auth
• DAGU_GITSYNC_AUTH_SSH_KEY_PATH - Path to SSH private key
• DAGU_GITSYNC_AUTH_SSH_PASSPHRASE - SSH key passphrase
• DAGU_GITSYNC_AUTOSYNC_ENABLED - Enable auto-sync background worker (default: false)
• DAGU_GITSYNC_AUTOSYNC_ON_STARTUP - Pull on startup (default: true)
• DAGU_GITSYNC_AUTOSYNC_INTERVAL - Sync interval in seconds (default: 300, 0 = no periodic sync)
• DAGU_GITSYNC_COMMIT_AUTHOR_NAME - Git commit author name (default: Dagu)
• DAGU_GITSYNC_COMMIT_AUTHOR_EMAIL - Git commit author email (default: dagu@localhost)

Legacy Environment Variables (Deprecated)

These variables are maintained for backward compatibility but should not be used in new deployments:

• DAGU__ADMIN_NAVBAR_COLOR - Use DAGU_UI_NAVBAR_COLOR
• DAGU__ADMIN_NAVBAR_TITLE - Use DAGU_UI_NAVBAR_TITLE
• DAGU__ADMIN_PORT - Use DAGU_PORT
• DAGU__ADMIN_HOST - Use DAGU_HOST
• DAGU__DATA - Use DAGU_DATA_DIR
• DAGU__SUSPEND_FLAGS_DIR - Use DAGU_SUSPEND_FLAGS_DIR
• DAGU__ADMIN_LOGS_DIR - Use DAGU_ADMIN_LOG_DIR
• DAGU__EVENT_STORE_DIR - Use DAGU_EVENT_STORE_DIR

Base Configuration

Shared defaults for all DAGs: ~/.config/dagu/base.yaml

# Environment
env:
  - ENVIRONMENT: production
  - LOG_LEVEL: info

# Defaults
queue: "default"
hist_retention_days: 30

# Email notifications
mail_on:
  failure: true

smtp:
  host: "smtp.gmail.com"
  port: "587"
  username: "notifications@company.com"
  password: "${SMTP_PASSWORD}"

error_mail:
  from: "dagu@company.com"
  to: "ops-team@company.com"
  prefix: "[ERROR]"
  attach_logs: true

For complete documentation on all available fields, inheritance behavior, and common patterns, see Base Configuration.

Command-Line Flags

Global Flags (All Commands)

• --config, -c - Config file (default: ~/.config/dagu/config.yaml)
• --dagu-home - Override DAGU_HOME for this command invocation
• --quiet, -q - Suppress output
• --cpu-profile - Enable CPU profiling

The --dagu-home flag sets a custom application home directory for the current command, overriding the DAGU_HOME environment variable. When set, all paths use a unified structure under the specified directory.

Example:

# Use a custom home directory
dagu --dagu-home=/tmp/dagu-test start my-workflow.yaml

# Run server with isolated data
dagu --dagu-home=/opt/dagu-prod start-all

Server/Start-All

• --host, -s - Server host
• --port, -p - Server port
• --dags, -d - DAGs directory

Scheduler

• --dags, -d - DAGs directory

Configuration Precedence

1. Command-line flags (highest)
2. Environment variables
3. Configuration file
4. Base configuration
5. Default values (lowest)

# Port 9000 wins (CLI flag beats env var)
DAGU_PORT=8080 dagu start-all --port 9000

# --dagu-home flag overrides DAGU_HOME environment variable
DAGU_HOME=/opt/dagu dagu --dagu-home=/tmp/dagu-test start my-workflow.yaml

Runtime Context and Variables

Dagu exposes workflow metadata through canonical ${context.*} references and shell-oriented environment projections such as DAG_RUN_ID, DAG_RUN_LOG_FILE, and DAG_RUN_STEP_NAME. Consult Runtime Context and Variables for the full list and examples of how to use them in automations.

Directory Structure

Default (XDG)

~/.config/dagu/
├── dags/              # DAG definitions
├── config.yaml        # Main configuration
└── base.yaml          # Shared DAG defaults

~/.local/share/dagu/
├── logs/              # All log files
│   ├── admin/         # Admin/server logs
│   │   ├── audit/     # Audit logs (daily JSONL files)
│   │   └── events/    # Centralized event logs
│   └── <dag name>/    # Per-DAG run logs
├── data/              # Application data
│   ├── artifacts/     # DAG run artifacts
│   ├── dag-runs/      # DAG run history
│   ├── queue/         # Queue data
│   ├── proc/          # Process data
│   ├── contexts/      # CLI remote contexts
│   └── service-registry/  # Service registry data
└── suspend/           # DAG suspend flags

With DAGU_HOME

$DAGU_HOME/
├── dags/              # DAG definitions
├── logs/              # All log files
│   ├── <dag name>/    # Per-DAG run logs
│   └── admin/         # Admin/server logs
│       ├── audit/     # Audit logs (daily JSONL files)
│       └── events/    # Centralized event logs
├── data/              # Application data
│   ├── artifacts/     # DAG run artifacts
│   ├── dag-runs/      # DAG run history
│   ├── queue/         # Queue data
│   ├── proc/          # Process data
│   ├── contexts/      # CLI remote contexts
│   └── service-registry/  # Service registry data
├── suspend/           # DAG suspend flags
├── config.yaml        # Main configuration
└── base.yaml          # Shared DAG defaults

Configuration Examples

Minimal

port: 8080

Production

host: 0.0.0.0
port: 443

auth:
  mode: builtin
  builtin:
    token:
      secret: ${AUTH_TOKEN_SECRET}  # auto-generated if not set
      ttl: 24h

tls:
  cert_file: /etc/ssl/certs/dagu.crt
  key_file: /etc/ssl/private/dagu.key

permissions:
  write_dags: false
  run_dags: true

ui:
  navbar_color: "#ff0000"
  navbar_title: "Production"

Multi-Environment

remote_nodes:
  - name: staging
    api_base_url: https://staging.example.com/api/v1
    auth_type: token
    auth_token: ${STAGING_TOKEN}

  - name: production
    api_base_url: https://prod.example.com/api/v1
    auth_type: token
    auth_token: ${PROD_TOKEN}

Distributed Execution

# Main instance with coordinator
host: 0.0.0.0
port: 8080

coordinator:
  host: 0.0.0.0
  port: 50055

default_execution_mode: distributed  # Dispatch all DAGs to workers

# Worker configuration
worker:
  id: gpu-worker-01
  max_active_runs: 10
  labels:
    gpu: "true"
    cuda: "11.8"
    memory: "64G"
    region: "us-east-1"

# TLS configuration for peer connections
peer:
  insecure: false  # Enable TLS
  cert_file: /etc/dagu/tls/cert.pem
  key_file: /etc/dagu/tls/key.pem
  client_ca_file: /etc/dagu/tls/ca.pem

Default Values

Key Defaults

• api_base_path: /api/v1
• queues.enabled: true
• permissions.write_dags: true
• permissions.run_dags: true
• ui.max_dashboard_page_limit: 100
• ui.log_encoding_charset: utf-8
• ui.dags.sort_field: name
• ui.dags.sort_order: asc
• log_format: text
• host: 127.0.0.1
• port: 8080
• public_url: empty
• check_updates: true
• metrics: private
• cors_allowed_origins: empty (cross-origin browser access disabled)
• default_execution_mode: local
• coordinator.enabled: true
• terminal.enabled: false
• terminal.max_sessions: 5
• audit.enabled: true
• event_store.enabled: true
• event_store.retention_days: 3
• webhooks.max_payload_size: 1048576

Auto-generated Paths

When not specified, these paths are automatically derived:

• paths.docs_dir: {paths.dags_dir}/docs - Stores Markdown documents and runbooks
• paths.artifact_dir: {paths.data_dir}/artifacts - Stores DAG run artifacts
• paths.tools_dir: {paths.data_dir}/tools - Stores managed DAG tool cache, locks, manifests, and shims
• paths.dag_state_dir: {paths.data_dir}/dag-state - Stores persistent DAG state values
• paths.dag_runs_dir: {paths.data_dir}/dag-runs - Stores DAG run history
• paths.queue_dir: {paths.data_dir}/queue - Stores queue data
• paths.proc_dir: {paths.data_dir}/proc - Stores process data
• paths.contexts_dir: {paths.data_dir}/contexts - Stores CLI remote contexts
• paths.event_store_dir: {paths.admin_logs_dir}/events - Stores centralized event logs
• paths.executable: Current executable path - Auto-detected from running process

Supported Log Encodings

The ui.log_encoding_charset configuration option supports a wide range of character encodings for reading log files. This is useful when your DAG steps produce output in non-UTF-8 encodings.

Common Encodings

Encoding	Aliases	Description
utf-8	utf8	Unicode (default)
shift_jis	shiftjis, sjis, s-jis	Japanese (Windows)
euc-jp	eucjp	Japanese (Unix)
iso-2022-jp	iso2022jp	Japanese (Email)
gb2312	gb-2312	Simplified Chinese
gbk	cp936, windows-936	Simplified Chinese (Extended)
gb18030		Simplified Chinese (Full)
big5	big-5	Traditional Chinese
euc-kr	euckr, korean	Korean

ISO-8859 (Latin) Encodings

Encoding	Aliases	Description
iso-8859-1	latin1, l1	Western European
iso-8859-2	latin2, l2	Central European
iso-8859-5	cyrillic	Cyrillic
iso-8859-6	arabic	Arabic
iso-8859-7	greek	Greek
iso-8859-8	hebrew	Hebrew
iso-8859-9	latin5, turkish	Turkish
iso-8859-15	latin9	Western European with Euro

Windows Code Pages

Encoding	Aliases	Description
windows-1250	cp1250	Central European
windows-1251	cp1251	Cyrillic
windows-1252	cp1252, ansi	Western European
windows-1253	cp1253	Greek
windows-1254	cp1254	Turkish
windows-1255	cp1255	Hebrew
windows-1256	cp1256	Arabic
windows-1257	cp1257	Baltic
windows-1258	cp1258	Vietnamese

Other Encodings

Encoding	Aliases	Description
koi8-r	koi8r	Russian
koi8-u	koi8u	Ukrainian
macintosh	mac, macroman	Mac Roman
ibm866	cp866	DOS Cyrillic
utf-16	utf16, utf-16le	Unicode (16-bit)
utf-16be	utf16be	Unicode (16-bit Big Endian)

Example Configuration

# For Japanese logs (Shift_JIS encoding)
ui:
  log_encoding_charset: "shift_jis"

# For Russian logs (KOI8-R encoding)
ui:
  log_encoding_charset: "koi8-r"

# For legacy Windows systems
ui:
  log_encoding_charset: "windows-1252"

See Also

• Server Configuration
• Production Setup
• Deployment Guides