duckflux — Declarative Workflow DSL for Multi-Agent Orchestration

Design Philosophy

duckflux isn't "another DSL". It's an easy workflow engine for the 2000 century developers.

Declarative-first

Describe what your workflow should do. YAML is the source of truth: readable, version-controlled, diffable.

Deterministic

A state machine — not an LLM — controls flow. Your pipeline runs the same way every time. No hallucinated next steps.

Multi-runtime

The spec is implementation-agnostic. Same YAML, any runtime. Currently supporting any platform using binaries or Node/Bun environments.

Powered by Google CEL

Google Common Expression Language for all conditional logic. Type-safe, sandboxed, and battle-tested in Kubernetes.

Batteries included

Redis, NATS and custom event hubs. A Mermaid-powered editor. A web server UI for observability.

Focused on DX

For developers without a PhD in distributed systems. Simple YAML with great capabilities.

Features

From simple scripts to complex multi-agent pipelines — duckflux speaks the same YAML regardless of complexity.

🔁 Loops ⚡ Parallel execution 🔀 Conditionals 🛡️ Guards & retry 📡 Events 📋 Input/Output schemas 🪆 Nested workflows 🔧 Error handling

Powered by Google CEL

Google's Common Expression Language keeps your logic safe, predictable, and readable. The same engine that powers Kubernetes admission controllers.

Type-safeSandboxedNo side effectsFast evaluationKubernetes-provenHuman-readable

workflow.duck.yaml

steps:
  - run: analyze
    output: result

  - run: approve
    when: "result.score >= 0.9 && result.issues.size() == 0"

  - run: review
    when: "result.score >= 0.6 && result.score < 0.9"

  - run: reject
    when: "result.score < 0.6"

CEL expressions used

result.score >= 0.9

Direct field access with comparison

result.issues.size() == 0

CEL built-in: list length check

&&

Boolean AND — both conditions must be true

Full CEL reference

workflow.duck.yaml

steps:
  - run: llm_reviewer
    output: review
    retry:
      max: 5
      delay: 1s
      backoff: exponential
      when: >
        review.status == "incomplete" ||
        review.confidence < 0.7 ||
        "RETRY" in review.flags

CEL expressions used

review.status == "incomplete"

String equality check

review.confidence < 0.7

Numeric threshold condition

"RETRY" in review.flags

CEL `in` operator: list membership

Full CEL reference

workflow.duck.yaml

participants:
  deploy:
    type: exec
    command: >
      deploy.sh
      --env {{ inputs.environment }}
      --tag {{ inputs.tag }}

steps:
  - run: deploy
    input:
      target: >
        inputs.environment == "prod"
          ? inputs.prod_cluster
          : inputs.staging_cluster
      replicas: "inputs.replicas * (inputs.environment == 'prod' ? 2 : 1)"

CEL expressions used

inputs.environment == "prod" ? … : …

Ternary operator for dynamic values

inputs.replicas * 2

Arithmetic in expressions

{{ inputs.tag }}

Template interpolation in commands

Full CEL reference

Building Blocks

Every step in a duckflux workflow is powered by a participant. Six types cover everything from shell commands to event-driven coordination.

💻

exec

Shell commands & scripts

Execute any shell command, script, or binary. Perfect for AI agent CLIs, build tools, or custom runners.

Full exec reference

example.duck.yaml

participants:
  coder:
    type: exec
    command: >
      claude --model claude-opus-4-5
      --prompt "{{ inputs.task }}"
      --output-format json

🌐

http

HTTP/REST API calls

Make HTTP requests to any REST API. Supports GET, POST, PUT, DELETE with headers, auth, and body templating.

Full http reference

example.duck.yaml

participants:
  deploy_api:
    type: http
    method: POST
    url: "https://api.deploy.io/deploys"
    headers:
      Authorization: "Bearer {{ secrets.API_TOKEN }}"
    body:
      repo: "{{ inputs.repo }}"
      branch: "{{ inputs.branch }}"

🔌

mcp

Model Context Protocol

Call any MCP (Model Context Protocol) server tool. Bridges workflows with the broader MCP ecosystem.

Full mcp reference

example.duck.yaml

participants:
  github_tool:
    type: mcp
    server: "@modelcontextprotocol/server-github"
    tool: create_pull_request
    args:
      repo: "{{ inputs.repo }}"
      title: "{{ inputs.title }}"
      branch: "{{ inputs.branch }}"

🪆

workflow

Nested sub-workflows

Compose workflows from reusable sub-workflows. Build libraries of common patterns and share across teams.

Full workflow reference

example.duck.yaml

participants:
  test_suite:
    type: workflow
    path: ./shared/test-suite.duck.yaml

  security_scan:
    type: workflow
    path: ./shared/security.duck.yaml
    inputs:
      strict: true

📡

emit

Event emission

Emit named events to channels. Enable event-driven architectures and cross-workflow communication.

Full emit reference

example.duck.yaml

steps:
  - run: analyze
    output: result

  - emit:
      channel: "analysis.complete"
      data:
        result: "{{ result }}"
        workflow_id: "{{ context.id }}"
        timestamp: "{{ context.now }}"

⏸️

wait

Event & condition waits

Suspend execution until an event arrives or a condition is met. Supports timeouts and fallback handlers.

Full wait reference

example.duck.yaml

steps:
  - emit:
      channel: "approvals.pending"
      data: { pr_url: "{{ outputs.pr_url }}" }

  - wait:
      event: "approval.decision"
      timeout: 48h
      output: decision
      on_timeout: handle_expired

  - run: merge_pr
    when: "decision.approved"

Tooling & Ecosystem

Everything you need to author, run, observe, and debug workflows — from the terminal to the browser.

⌨️

CLI

Run, lint & validate

Run workflows from the terminal with a single command. Lint for schema and semantic errors. Validate inputs before execution. Supports NATS and Redis event backends for cross-process coordination.

CLI reference

terminal

# Install globally
bun add -g duckflux

# Run a workflow
duckflux run ./pipeline.duck.yaml --input repo=org/app

# Lint before running
duckflux lint ./pipeline.duck.yaml

🖥️

Dev Server

Observe & execute

A GitHub Actions-style web UI for executing and tracing workflows locally. Real-time updates via SSE, auto-generated input forms, step-by-step inspection with collapsible JSON viewers. Dark and light mode.

Server UI docs

terminal

# Start the dev server
duckflux server --trace-dir ./traces --workflow-dir ./workflows

# Open http://localhost:3000

How duckflux Compares

The same workflow scenario across tools: a coder implements, a reviewer reviews, if not approved repeat up to 3 times, then deploy.

Feature	duckflux YAML DSL	Argo K8s CI/CD	GHA GitHub CI	n8n Visual automation	Temporal Durable workflows	Airflow Data pipelines
Conditional loop	native	template recursion	unroll	JS hack	code	impossible
Fixed loop	native	native	✗	JS hack	code	✗
Parallelism	native	native	jobs	visual	goroutines	native
Conditional branch	native	when	if	IF node	code	BranchOp
Guard (when)	native	when	if per step	✗	code	✗
Events (emit/wait)	native	✗	✗	webhook	signals	sensors
Error handling	onError + retry	retryStrategy	continue-on-error	✗	code	✗
Sub-workflows	native	template ref	reusable	sub-workflow	child wf	SubDagOp
Spec is readable	✓	partially	partially	✗ (JSON)	✗ (code)	✗ (Python)
Inline participants	native	✗	✗	✗	✗	✗

Based on publicly available documentation. Table reflects capabilities, not quality.

Ready to quack?

Stop orchestrating
imperatively.

Write your first workflow in 5 minutes. Run it with a single command. Let duckflux handle the state machine so you can focus on what matters.

Get started in 5 min View on GitHub

$ duck run ./hello.duck.yaml

Declarative Workflow DSL for

Design Philosophy

Declarative-first

Deterministic

Multi-runtime

Powered by Google CEL

Batteries included

Focused on DX

Features

Powered by Google CEL

CEL expressions used

CEL expressions used

CEL expressions used

Building Blocks

Tooling & Ecosystem

How duckflux Compares

Stop orchestrating imperatively.

Declarative
Workflow DSL
for

Stop orchestrating
imperatively.