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              # Include DEBUG logs and HTTP request headers when true
log_format: "text"         # "text" or "json"
access_log_mode: "none"    # Access log mode: "all", "non-public", or "none" (default)
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)
allowed_hosts: []         # Extra host names accepted with auth.mode none and at first-admin setup
cache: "normal"            # Cache mode

# HTTP client IP allowlist
ip_access:
  allowed_ips: []         # IPv4/IPv6 addresses or CIDR ranges; empty disables filtering
  trusted_proxies: []     # Proxies permitted to supply forwarded client IP headers

# 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" # DAGs and Git Sync supporting files
  wiki_dir: ""                # Auto: {dags_dir}/wiki
  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: ""      # Auto: {data_dir}/suspend
  admin_logs_dir: "~/.local/share/dagu/logs/admin"
  event_store_dir: ""        # Auto: {admin_logs_dir}/events
  base_config: "~/.config/dagu/base.yaml"
  calendars_dir: "~/.config/dagu/calendars" # Business calendar files
  dag_runs_dir: ""            # Auto: {data_dir}/dag-runs
  dag_run_work_dir: ""        # Auto: {data_dir}/dag-run-work
  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)
  symlinks: false           # Include DAG file symlinks and allow external targets

# External Secret Providers
secrets:
  vault:
    address: "https://vault.example.com"
    token: "hvs.DummyToken"
    # token_file: /run/secrets/vault-token  # Instead of token
    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`
  aws:
    region: ""         # Default region for the `aws` provider
  gcp:
    project_id: ""     # Default project ID for the `gcp` provider
    location: ""       # Optional regional location for the `gcp` provider
  azure:
    vault_url: ""      # Default Key Vault URL for the `azure` provider
  alibaba:
    region: ""         # Default region for the `alibaba` provider
    endpoint: ""       # Dedicated KMS gateway hostname (no scheme or path)
    ca_file: ""        # CA certificate file for the dedicated gateway

# 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
      # secret_file: /run/secrets/token-secret  # Instead of secret
      ttl: "24h"
    initial_admin:            # Admin created on first start when no user exists
      username: ""            # Set together with password
      password: ""            # At least 8 characters
      # password_file: /run/secrets/admin-password  # Instead of password

  # Basic auth (simple username/password)
  basic:
    username: "admin"
    password: "secret"
    # password_file: /run/secrets/basic-password  # Instead of password

  # 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_secret_file: /run/secrets/oidc-client-secret  # Instead of 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"  # Charset for log lines that are not UTF-8 (see supported encodings below)
  max_dashboard_page_limit: 100
  dags:
    sort_field: "name"        # Default DAG list request sort field (`name`, `nextRun`, `status`, or `lastRun`)
    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_

# Browser steps
browser:
  sandbox: true             # Set false only where Chromium's sandbox cannot start
  max_open: 0               # Most browsers open at once on this host (default: 0, no limit)
  write_gate: off           # Least strict write gate mode: off (default), record, ask, or rehearse
  write_policy: /etc/dagu/browser-write-policy.yaml  # Sign-ins, declared writes, and noise hosts for the write gate
  client_certificates:      # TLS client certificates every browser presents
    - hosts: ["*.corp.example.com"]    # Host, *.domain, or * for every host
      pfx_file: /etc/dagu/certs/device.p12
      passphrase_file: /etc/dagu/certs/device.passphrase
      # cert_file / key_file: PEM certificate and unencrypted key instead of pfx_file
  guard_client_certificates: true  # Prevent Chrome certificate prompts
  trusted_cas:              # Private CAs trusted for these sites
    - hosts: [portal.example.com, "*.corp.example.com"]
      ca_file: /etc/dagu/certs/company-ca.pem

# 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"
    # basic_auth_password_file: /run/secrets/staging-password  # Instead of basic_auth_password
  - name: "production"
    api_base_url: "https://prod.example.com/api/v1"
    auth_type: "token"
    auth_token: "prod-token"
    # auth_token_file: /run/secrets/prod-token  # Instead of auth_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_wait_timeout: "2m"  # Hold a run with no matching healthy worker this long before it fails (0 refuses at once)

# Worker (for distributed execution)
worker:
  id: ""                  # Worker ID (default: hostname@PID)
  coordinators: []         # Required by dagu worker (host:port)
  max_active_runs: 100      # Max parallel task executions
  health_port: 8092         # HTTP health check port (0 to disable)
  shutdown_timeout: "60s"   # Drain bound on SIGINT/SIGTERM before running DAG runs are canceled (0 waits without a bound)
  labels:                 # Worker capabilities
    gpu: "false"
    memory: "16G"
    region: "us-east-1"
  postgres_pool:           # PostgreSQL connection pool for worker processes
    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
  wake_hold: "0"                   # Longest the scheduler holds its ticks after the host wakes from sleep (0 = never hold)

# 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
  stale_threshold: "90s"           # Time after which a heartbeat is considered stale

# Shutdown signal handling (server, scheduler, start-all)
signal_handling:
  enable_propagation: false  # Forward SIGINT/SIGTERM to running DAG runs and wait for their cleanup

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

# Dagu Console Monitoring (Beta)
cloud:
  report: ""              # "off", "health", "runs", or "errors"; empty (default) = choose in the web UI
  remote_access: ""       # "off", "viewer", "operator", or "developer"; empty (default) = choose in the web UI
  # remote_approvals: true # Let Dagu Cloud calls decide waiting steps; omit (default) to choose in the web UI

# 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}"
    # token_file: /run/secrets/git-token  # Instead of token
    ssh_key_path: ""
    ssh_passphrase: ""
    # ssh_passphrase_file: /run/secrets/ssh-passphrase  # Instead of 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.

Run dagu config --values to see the value of each setting and whether it came from a default, the configuration file, or an environment variable. See Check Effective Settings.

Variables ending in _FILE name a file that holds a secret. See Secrets From Files.

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. Dagu's own credentials, such as DAGU_AUTH_BASIC_PASSWORD and DAGU_ENCRYPTION_KEY, are never forwarded either way. 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_PATH - API endpoint base path (default: /api/v1)
• 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 - Include DEBUG logs and HTTP request headers
• DAGU_LOG_FORMAT - Log format (text/json)
• DAGU_ACCESS_LOG_MODE - Access log mode (all, non-public, or none; default: none); see Operations - Logging
• 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_IP_ACCESS_ALLOWED_IPS - Comma-separated IPv4/IPv6 addresses and CIDR ranges allowed to access the HTTP server. An empty value disables filtering.
• DAGU_IP_ACCESS_TRUSTED_PROXIES - Comma-separated proxy addresses and CIDR ranges permitted to supply forwarded client IP headers.
• DAGU_CACHE - Cache mode (default: normal)
• DAGU_CORS_ALLOWED_ORIGINS - Comma-separated origins allowed for cross-origin browser access (cors_allowed_origins; default: empty, which disables it). See Cross-Origin Browser Access.
• DAGU_ALLOWED_HOSTS - Comma-separated host names accepted, beyond those always accepted, on every request with auth.mode: none and on first-admin setup (allowed_hosts; default: empty). An entry is an exact name, .example.com for a domain and its subdomains, or * to turn the check off. See Allowed Host Names.

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 and Git Sync supporting files
• DAGU_DAGS - Alternative to DAGU_DAGS_DIR
• DAGU_WIKI_DIR - Markdown Wiki pages and runbooks (default: {dags_dir}/wiki)
• DAGU_DOCS_DIR - Deprecated alias for DAGU_WIKI_DIR
• DAGU_CALENDARS_DIR - Business calendar files (default: ~/.config/dagu/calendars, or $DAGU_HOME/calendars when DAGU_HOME is set)
• 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 (default: {data_dir}/suspend)
• 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_DAG_RUN_WORK_DIR - Per-run working directory root (default: {data_dir}/dag-run-work)
• 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)
• DAGU_DAG_DISCOVERY_SYMLINKS - Include DAG file symlinks in recursive discovery and allow targets outside 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. External symlink targets are read-only through Dagu. See Recursive DAG Discovery for traversal, symlink, 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_SECRET_FILE - File holding the JWT signing secret (auth.builtin.token.secret_file)
• 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_AUTH_BUILTIN_INITIAL_ADMIN_PASSWORD_FILE - File holding the initial admin password (auth.builtin.initial_admin.password_file)
• 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
• DAGU_AUTH_BASIC_PASSWORD_FILE - File holding the basic auth password (auth.basic.password_file)

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_SECRET_FILE - File holding the OAuth2 client secret (auth.oidc.client_secret_file)
• 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 - Charset for log lines that are not UTF-8 (see Supported Log Encodings)
• DAGU_UI_MAX_DASHBOARD_PAGE_LIMIT - Dashboard limit
• DAGU_UI_DAGS_SORT_FIELD - Default DAGs page request sort field (name, nextRun, status, or lastRun)
• 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_BROWSER_SANDBOX - Set to false to turn off Chromium's sandbox for every browser that browser steps start on this host (default: true). Use it only where the sandbox cannot start; see Browser requirements. With the sandbox on, a browser step fails when CI is set or Dagu runs as root on Linux, because the browser would run without the sandbox there.
• DAGU_BROWSER_MAX_OPEN - Most browsers open at once on this host, counting browser steps, steps waiting for an answer, and browser sessions (browser.max_open; default: 0, no limit). A browser past it waits for one to close. A negative value is a configuration error. See Limiting Open Browsers.
• DAGU_BROWSER_WRITE_GATE - Least strict write gate mode every browser on this host runs in: off, record, ask, or rehearse (browser.write_gate; default: off). A step or a browser session can only choose a stricter one. Any other value is a configuration error.
• DAGU_BROWSER_WRITE_POLICY - YAML or JSON file of the write policy browser steps follow: the sign-ins whose writes are sent, requests declared as writes, and noise hosts (browser.write_policy; default: empty).
• DAGU_BROWSER_GUARD_CLIENT_CERTIFICATES - Set to false to stop Dagu from guarding other HTTPS sites against Chrome client certificate prompts (browser.guard_client_certificates; default: true when client certificates are configured). See Browser Certificate Trust.
• 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:.

OpenCode

• DAGU_OPENCODE_EXECUTABLE - OpenCode executable path or command name for the managed OpenCode service (opencode.executable; default: opencode)
• DAGU_OPENCODE_ENV_PASSTHROUGH - Comma-separated exact environment variable names forwarded to the managed OpenCode service (opencode.env_passthrough). See OpenCode service setup.

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)
• DAGU_COORDINATOR_WORKER_WAIT_TIMEOUT - How long the coordinator holds a dispatched run as Queued when no healthy worker matches its selector. The first matching worker that registers in time takes the run; after the timeout the run fails with an error that names the selector (coordinator.worker_wait_timeout; default: 2m, 0 refuses the dispatch at once).

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_SHUTDOWN_TIMEOUT - How long a worker that stops on SIGINT or SIGTERM waits for running DAG runs to finish before it cancels them (worker.shutdown_timeout; default: 60s, 0 waits without a bound). Set the supervisor's stop timeout at least 15s above this value: systemd TimeoutStopSec defaults to 90s, docker stop to 10s, and Kubernetes terminationGracePeriodSeconds to 30s.
• DAGU_WORKER_LABELS - Worker labels (format: key1=value1,key2=value2)
• DAGU_WORKER_COORDINATORS - Coordinator addresses required by dagu worker (host:port,...)
• 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)
• DAGU_SCHEDULER_WAKE_HOLD - Longest the scheduler holds its ticks after the host wakes from sleep, paused by scheduler until the pause is cleared (scheduler.wake_hold; default: 0, never hold). See Wake hold.

Signal Handling

• DAGU_SIGNAL_PROPAGATION - Forward shutdown signals (SIGINT/SIGTERM) received by dagu server, dagu scheduler, or dagu start-all to the DAG runs it started, and wait for their cleanup before exiting (default: false). See Graceful Shutdown.

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_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_STALE_THRESHOLD - Deprecated alias for DAGU_PROC_STALE_THRESHOLD

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

proc.heartbeat_sync_interval and scheduler.heartbeat_sync_interval are deprecated and ignored: they are accepted so existing configuration files still load, but they have no effect. DAGU_PROC_HEARTBEAT_SYNC_INTERVAL and DAGU_SCHEDULER_HEARTBEAT_SYNC_INTERVAL are no longer read.

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 - Server key or license key from Dagu Console (license.key)
• DAGU_LICENSE_CLOUD_URL - License validation service URL (license.cloud_url)
• DAGU_LICENSE_SERVER_NAME - Name this server reports to Dagu Console (license.server_name; default: the hostname). A name set in Dagu Console or Dagu is shown in its place

Dagu Console Monitoring (Beta)

• DAGU_CLOUD_REPORT - What the server reports to Dagu Console: off, health, runs, or, on v2.22 or later, errors (cloud.report; default: empty, which reports nothing until an administrator chooses in the web UI). A set value, off included, fixes the level and the web UI shows it read-only. See Monitoring (Beta).
• DAGU_CLOUD_REMOTE_ACCESS - Highest role a Dagu Cloud user gets on calls Dagu Cloud carries to this server: off, viewer, operator, or developer (cloud.remote_access; default: empty, which leaves the choice to an administrator in the web UI, where it starts at off). A set value fixes it.
• DAGU_CLOUD_REMOTE_APPROVALS - Whether those calls, at operator or above, may approve, reject, or push back steps waiting for a person (cloud.remote_approvals; default: unset, which leaves the choice to the web UI, where it starts off). A set value fixes it.

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_TOKEN_FILE - File holding the default Vault token (secrets.vault.token_file)
• 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
• DAGU_SECRETS_AWS_REGION - Default region for the aws secret provider. See AWS Secrets Manager.
• DAGU_SECRETS_GCP_PROJECT_ID - Default project ID for the gcp secret provider
• DAGU_SECRETS_GCP_LOCATION - Optional regional location for the gcp secret provider. See Google Secret Manager.
• DAGU_SECRETS_AZURE_VAULT_URL - Default Key Vault URL for the azure secret provider. See Azure Key Vault.
• DAGU_SECRETS_ALIBABA_REGION - Default region for the alibaba secret provider
• DAGU_SECRETS_ALIBABA_ENDPOINT - Dedicated KMS gateway hostname for the alibaba secret provider, without https:// or a path
• DAGU_SECRETS_ALIBABA_CA_FILE - CA certificate file for the dedicated KMS gateway. See Alibaba Cloud KMS.

Git Sync

See Git Sync for repository layout, supporting-file behavior, and operational guidance.

• 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 - Repository subdirectory to sync, mapped relative to the local DAG and Wiki roots (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_TOKEN_FILE - File holding the access token (git_sync.auth.token_file)
• DAGU_GITSYNC_AUTH_SSH_KEY_PATH - Path to SSH private key
• DAGU_GITSYNC_AUTH_SSH_PASSPHRASE - SSH key passphrase
• DAGU_GITSYNC_AUTH_SSH_PASSPHRASE_FILE - File holding the SSH key passphrase (git_sync.auth.ssh_passphrase_file)
• 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_NAVBAR_COLOR - Use DAGU_UI_NAVBAR_COLOR
• DAGU_NAVBAR_TITLE - Use DAGU_UI_NAVBAR_TITLE
• DAGU_LOG_ENCODING_CHARSET - Use DAGU_UI_LOG_ENCODING_CHARSET
• DAGU_MAX_DASHBOARD_PAGE_LIMIT - Use DAGU_UI_MAX_DASHBOARD_PAGE_LIMIT
• 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

When a short UI variable such as DAGU_NAVBAR_TITLE and its DAGU_UI_* form are both set, the DAGU_UI_* value is used.

Browser Certificate Trust

browser.trusted_cas sets which private CAs Dagu trusts for specific sites. Configure it in config.yaml on each machine that runs browsers. See Trusted Certificate Authorities for setup and a connection check.

browser.guard_client_certificates prevents Chrome from asking the user to choose a client certificate. Dagu checks each other HTTPS site once with a TLS handshake of its own. Sites that use TLS 1.3, ask for no client certificate, and have a publicly trusted certificate keep Chrome's own connection, so they see Chrome's TLS handshake. Other sites go through Dagu's proxy, which presents no client certificate. Under TLS 1.3 a request for a certificate is encrypted, so a site that asks Chrome but did not ask during Dagu's check can still reach Chrome's certificate selection. The default is true when client certificates are configured. Set it to false to disable this behavior.

The guard also trusts CAs from client_certificates[].ca_file for other hosts. Use trusted_cas to restrict a CA to named hosts. Those hosts always use Dagu's proxy, even with the guard disabled. They also keep the system CAs and every client_certificates[].ca_file, so an entry only adds trust.

For an HTTPS upstream proxy with a private CA, add a trusted_cas entry for the proxy's hostname.

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
    ├── suspend/       # DAG suspend flags
    └── service-registry/  # Service registry data

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
│   ├── suspend/       # DAG suspend flags
│   └── service-registry/  # Service registry data
├── 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: the system charset (the ANSI code page on Windows, the LC_ALL or LANG locale elsewhere), or 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)
• allowed_hosts: empty (only the always-accepted host names)
• ip_access.allowed_ips: empty (HTTP client IP filtering disabled)
• ip_access.trusted_proxies: empty (forwarded client IP headers are ignored)
• default_execution_mode: local
• coordinator.enabled: true
• coordinator.worker_wait_timeout: 2m
• worker.shutdown_timeout: 60s
• terminal.enabled: false
• terminal.max_sessions: 5
• audit.enabled: true
• event_store.enabled: true
• event_store.retention_days: 1
• webhooks.max_payload_size: 1048576

Auto-generated Paths

When not specified, these paths are automatically derived:

• paths.wiki_dir: {paths.dags_dir}/wiki - Stores Markdown Wiki pages and runbooks
• paths.docs_dir: Deprecated compatibility alias for paths.wiki_dir
• 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.suspend_flags_dir: {paths.data_dir}/suspend - Stores DAG suspend flags
• paths.dag_runs_dir: {paths.data_dir}/dag-runs - Stores DAG run history
• paths.dag_run_work_dir: {paths.data_dir}/dag-run-work - Stores per-run working directories
• 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

Suspend Flag Upgrades

Suspend flags default to {paths.data_dir}/suspend, so processes sharing the data directory share suspension state. Explicit paths.suspend_flags_dir settings, including DAGU_SUSPEND_FLAGS_DIR and legacy configuration keys, keep their configured location and disable legacy fallback and migration. A configured path outside data_dir produces a warning; all servers and schedulers must use the same suspension directory.

When using the default path, Dagu also reads flags from the previous default location: suspend/ under the selected Dagu home (DAGU_HOME, --dagu-home, or an existing ~/.dagu), or $XDG_DATA_HOME/dagu/suspend (normally ~/.local/share/dagu/suspend) for XDG layouts. After acquiring leadership, the scheduler copies those flags into the new directory before processing runs. Startup retains the original flags. Suspending a DAG writes its new flag before removing its legacy flag; resuming removes both.

For upgrades:

• Make the same legacy flags available to all servers and schedulers. Reconcile any separate per-host flag directories first.
• Upgrade all processes before changing suspension state. Running older processes that write legacy flags alongside upgraded processes is unsupported.
• Include the legacy directory in backups until scheduler migration completes. Processes need permission to remove legacy flags when suspension state changes.
• For rollback, explicitly configure the older version to use the new shared suspend directory; retained legacy flags alone may no longer reflect the current state.

Supported Log Encodings

The ui.log_encoding_charset configuration option decodes log lines that are not valid UTF-8. Lines that are valid UTF-8 are always shown as is; utf-16, iso-2022-jp, and hz-gb-2312 decode the whole log instead. See Log Encoding for how lines are read and how the default is chosen.

Common Encodings

Encoding	Aliases	Description
utf-8	utf8	Unicode
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