Guides
API

Clearing-Layer Guides

Task-focused, end-to-end walkthroughs for building and operating on Ductor.

Guides are practical, start-to-finish walkthroughs for the tasks you actually do with Ductor. Where the Core Concepts pages explain how Ductor works, guides show how to get something done — with real commands, real payloads, and the exact config keys involved.

Each guide assumes you have a running Ductor instance. If you don't yet, start with Getting Started or the Run Ductor locally guide below.

  1. Start the stack

    Bring up the dependencies and confirm the API is ready.

  2. Publish a workflow

    Move from a local definition to a durable, runnable version.

  3. Add an integration

    Connect a provider and dispatch real work through it.

  4. Operate with confidence

    Export traces and metrics before moving into production.

Build & operate

Start here. Each card is a start-to-finish walkthrough with the exact commands, payloads, and config keys involved.

Run Ductor locally

Bring up TimescaleDB, Dragonfly, and Ductor with Docker Compose, apply migrations, and confirm the API is serving.

Define & publish a workflow

Author a DAG workflow definition in YAML, validate it offline, load it, publish a version, then trigger it and watch it run.

Add a connector & connection

Register a provider config, establish an encrypted connection, and dispatch a step to a third-party system.

Routing rules & strategies

Create pools, write CEL routing rules, and pick a selection strategy — via the API or a declarative bundle.

Issue & use API keys

Mint a DB-backed tenant API key over POST /api/v2/api-keys, scope it, and authenticate requests with it.

Enable tracing & metrics

Turn on OTLP trace export and Prometheus metrics, and point them at the VictoriaMetrics stack.

Extend the surface

Once the core stack is running, wire in the two newer surfaces — LLM steps and an MCP tool endpoint, and workflow definitions authored in code instead of YAML.

Enable the AI & MCP surface

Turn on the AI inference proxy behind ai_action / ai_agent steps and expose Ductor as an MCP tool server.

Define workflows in code

Build the same DAG definitions in Go, TypeScript, or Python with the SDKs — types, IDE completion, and inline tests, compiling to the identical runtime definition.

Where to go deeper

  • Core Concepts explains how Ductor works — the DAG workflow model, the routing pipeline, the single-writer coordinator, and connectors.
  • Architecture covers how Ductor is built — the layered, fx-composed engine, the coordinator/worker model, storage, and extension points.
  • The Configuration reference documents every DUCTOR_* environment variable these guides touch, and the CLI reference covers every ductor subcommand and flag.
  • The Operations section covers running Ductor in production — migrations, observability, security, health checks, and backups.

Stripe integration & invoicing

The money-movement layer — the always-on billing summary that points at the Stripe portal, plus the experimental recipient-wallet plugin and metered-usage invoicing worker.

Run Ductor locally

Bring up Ductor with Docker Compose, apply migrations, and make your first API call.