# Clearing-Layer Guides (/docs/guides)



Guides are practical, start-to-finish walkthroughs for the tasks you actually
do with Ductor. Where the [Core Concepts](/docs/concepts/coordinator-workers)
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](/docs/getting-started) or the
[Run Ductor locally](/docs/guides/run-locally) guide below.

<Journey>
  <JourneyStep title="Start the stack" href="/docs/guides/run-locally" icon="run">
    Bring up the dependencies and confirm the API is ready.
  </JourneyStep>

  <JourneyStep title="Publish a workflow" href="/docs/guides/define-workflow" icon="build">
    Move from a local definition to a durable, runnable version.
  </JourneyStep>

  <JourneyStep title="Add an integration" href="/docs/guides/add-connector" icon="connect">
    Connect a provider and dispatch real work through it.
  </JourneyStep>

  <JourneyStep title="Operate with confidence" href="/docs/guides/enable-observability" icon="operate">
    Export traces and metrics before moving into production.
  </JourneyStep>
</Journey>

## Build & operate [#build--operate]

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

<Cards>
  <Card title="Run Ductor locally" href="/docs/guides/run-locally">
    Bring up TimescaleDB, Dragonfly, and Ductor with Docker Compose, apply
    migrations, and confirm the API is serving.
  </Card>

  <Card title="Define & publish a workflow" href="/docs/guides/define-workflow">
    Author a DAG workflow definition in YAML, validate it offline, load it,
    publish a version, then trigger it and watch it run.
  </Card>

  <Card title="Add a connector & connection" href="/docs/guides/add-connector">
    Register a provider config, establish an encrypted connection, and dispatch
    a step to a third-party system.
  </Card>

  <Card title="Routing rules & strategies" href="/docs/guides/routing-rules-strategies">
    Create pools, write CEL routing rules, and pick a selection strategy — via
    the API or a declarative bundle.
  </Card>

  <Card title="Issue & use API keys" href="/docs/guides/api-keys">
    Mint a DB-backed tenant API key over `POST /api/v2/api-keys`, scope it, and
    authenticate requests with it.
  </Card>

  <Card title="Enable tracing & metrics" href="/docs/guides/enable-observability">
    Turn on OTLP trace export and Prometheus metrics, and point them at the
    VictoriaMetrics stack.
  </Card>
</Cards>

## Extend the surface [#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.

<Cards>
  <Card title="Enable the AI & MCP surface" href="/docs/ai">
    Turn on the AI inference proxy behind `ai_action` / `ai_agent` steps and
    expose Ductor as an MCP tool server.
  </Card>

  <Card title="Define workflows in code" href="/docs/sdks">
    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.
  </Card>
</Cards>

## Where to go deeper [#where-to-go-deeper]

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