Getting Started

This guide takes you from a clean checkout to a running engine that does its actual job. Ductor clears work through one lifecycle — priced → routed → executed → settled → proven — and this quickstart is the shortest path to its load-bearing middle: you'll bring up the stack, mint a tenant and API keys, define a small two-step workflow, trigger it, watch it complete, and then kill the process mid-run and watch the run pick up where it left off. By the end you'll have proven the executed stage — durable execution — on your own machine; the pricing, routing, and settlement stages build on the same engine.

You need

Docker, Compose, curl, and jq

You will build

A published two-step workflow

You will prove

The run resumes after a process restart

Prerequisites

• Docker and Docker Compose — the fastest path to a full stack.
• curl and jq — to drive the API and read JSON responses.

The compose stack brings up everything else for you: TimescaleDB (Postgres 16), Dragonfly (a Redis-compatible cache), and Ductor itself. The production image is a static, CGO-disabled Go binary on Alpine that runs as a non-root user — there's nothing else to install on the host.

Bring it up

git clone https://github.com/ductor-io/ductor.git
cd ductor
git checkout v1.8.0   # example pin; replace with the release you have validated
make up

until curl -fsS http://localhost:8080/health >/dev/null 2>&1; do sleep 2; done

docker compose exec -T ductor /usr/local/bin/ductor version
# version=v1.8.0 build_time=2026-01-15T12:00:00Z

Mint a tenant and API keys

Every tenant-scoped call needs a tenant. In the compose stack auth is disabled (DUCTOR_AUTH_ENABLED=false, DUCTOR_AUTH_ALLOW_ANONYMOUS=true), so you don't need a bearer token locally — but you still need a real tenant to scope your requests to. The seed-demo subcommand mints that tenant, seeds dashboard-visible demo data, and prints a set of API keys. It only needs Postgres, and it's idempotent:

docker compose exec -T ductor /usr/local/bin/ductor seed-demo --reset --no-migrate

--reset wipes the demo tenants' data first for a clean run, and --no-migrate skips migrations because the container already auto-migrated on boot. This seeds two fixed-UUID tenants — demo and acme — and prints a summary like:

=== ductor seed-demo: done ===

Seeded tenants (use the UUID as the X-Tenant-ID / dashboard workspace id):
  - demo    11111111-1111-1111-1111-111111111111
  - acme    22222222-2222-2222-2222-222222222222

API keys (plaintext shown once — these are demo keys, safe to print):
  - tenant=demo   name=demo-admin     roles=admin      key=<printed once>
  - tenant=demo   name=demo-operator  roles=operator   key=<printed once>
  - tenant=demo   name=demo-readonly  roles=viewer     key=<printed once>

Capture the tenant UUID (and a key, if you want to try authenticated requests later). The plaintext keys are printed once — the database only stores their hashes:

export DUCTOR_TENANT_ID="11111111-1111-1111-1111-111111111111"
# Optional locally (auth is off). When you turn auth on, send the key you
# captured above as a bearer token:
# export DUCTOR_API_KEY="<demo-admin key from the seed-demo output>"

Smoke test

Make one authenticated read to confirm the API is serving your tenant. Listing workflow runs returns the demo runs seed-demo just created:

curl -s http://localhost:8080/api/workflows/runs \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" | jq '.data | length'

Two things to internalize from this call:

• REST paths are /api/... (and /api/v2/... for newer services), not /v1/.... The REST surface is generated from the same protobuf definitions as the Connect-RPC API, so anything you can do over gRPC you can do with plain JSON — all snake_case.
• Every tenant-scoped call needs an X-Tenant-ID header. With auth enabled it must match your token's tenant; with the local stack's auth disabled, the header alone scopes the request.

Run your first workflow

Now make the engine do its job. You'll define a small two-step DAG that needs no connectors — a dataflow step (a deterministic in-coordinator transform) feeding a wait step (a durable delay) — then publish it, trigger a run, and poll it to completion.

BASE=http://localhost:8080
DEF=$(curl -s -X POST $BASE/api/workflow-definitions \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" -H "Content-Type: application/json" -d '{
  "family_slug": "hello-world",
  "title": "Hello World",
  "steps": [
    {"ref": "greet", "type": "STEP_TYPE_DATAFLOW", "title": "Build greeting",
     "args": {"operation": "project", "project": {"message": "\"hello\""}}},
    {"ref": "pause", "type": "STEP_TYPE_WAIT", "title": "Short delay",
     "args": {"duration": "2s"}}
  ],
  "edges": [{"source_ref": "greet", "target_ref": "pause", "type": "EDGE_TYPE_SUCCESS"}]
}')
ID=$(echo "$DEF" | jq -r '.data.id')
echo "definition: $ID"

curl -s -X POST $BASE/api/workflow-definitions/$ID/publish \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" >/dev/null

RUN=$(curl -s -X POST "$BASE/api/v2/workflow-definitions/$ID:trigger" \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" -H "Content-Type: application/json" \
  -d '{"subject_type": "demo", "subject_id": "1", "input": {"name": "world"}}')
RID=$(echo "$RUN" | jq -r '.run_id')
echo "run: $RID"

curl -s $BASE/api/workflows/runs/$RID \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" | jq '.data.summary.status'

curl -s $BASE/api/workflows/runs/$RID/steps \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" | jq

Watch it survive a crash

Durable execution means a run's progress lives in Postgres, not in process memory — so killing the engine mid-run doesn't lose the run. Prove it by parking a run on a longer wait, crashing the container, and watching it resume.

DEF=$(curl -s -X POST $BASE/api/workflow-definitions \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" -H "Content-Type: application/json" -d '{
  "family_slug": "durable-demo",
  "title": "Durable Demo",
  "steps": [
    {"ref": "greet", "type": "STEP_TYPE_DATAFLOW", "title": "Build greeting",
     "args": {"operation": "project", "project": {"message": "\"hello\""}}},
    {"ref": "pause", "type": "STEP_TYPE_WAIT", "title": "Long delay",
     "args": {"duration": "60s"}}
  ],
  "edges": [{"source_ref": "greet", "target_ref": "pause", "type": "EDGE_TYPE_SUCCESS"}]
}')
ID=$(echo "$DEF" | jq -r '.data.id')
curl -s -X POST $BASE/api/workflow-definitions/$ID/publish \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" >/dev/null
RID=$(curl -s -X POST "$BASE/api/v2/workflow-definitions/$ID:trigger" \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" -H "Content-Type: application/json" \
  -d '{"subject_type": "demo", "subject_id": "2"}' | jq -r '.run_id')
echo "run: $RID"

curl -s $BASE/api/workflows/runs/$RID \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" | jq '.data.summary.status'

docker compose kill ductor
docker compose up -d ductor
until curl -fsS http://localhost:8080/health >/dev/null 2>&1; do sleep 2; done

curl -s $BASE/api/workflows/runs/$RID \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" | jq '.data.summary.status'

Why this works. A wait step is persisted with a durable wakeup, not an in-memory timer, so a parked run is just a row waiting to be ticked. On restart, the workflow runtime coordinator scans for runs due for a tick every poll_interval (5s by default) and reclaims any run whose previous coordinator lease went stale after recovery_stale_after (30s by default). It only picks up non-terminal runs — completed runs are skipped — so nothing is re-executed twice. Concretely, a cleanly-parked run resumes within roughly the poll interval, or up to the stale-after window if the previous coordinator's lease has to expire first.

Next steps

Going further: enable the inbound MCP server and in-product chat agent under AI & agents, or define your workflows in code with the Go and Python SDKs instead of authoring DAGs through the API.