Configuration

Ductor is configured from a single typed Config struct, loaded once at startup. Fields are set through a YAML file or inline YAML; scalar keys and supported simple lists also use DUCTOR_* environment variables. This page documents the loading model and the most commonly-used keys, grouped by subsystem.

How configuration loads

Configuration is resolved with Viper and unmarshalled into internal/config/config.go. Precedence, highest to lowest:

1. CLI flag (e.g. --database-url)
2. Environment variable (DUCTOR_*)
3. Inline YAML in DUCTOR_CONFIG, or a config file
4. Registered defaults (from the code's config.Default())

The env var rule

• Prefix is DUCTOR_.
• A YAML key path maps to an env var by uppercasing and replacing dots with underscores.

database.url            → DUCTOR_DATABASE_URL
server.http_addr        → DUCTOR_SERVER_HTTP_ADDR
router.queue.enabled    → DUCTOR_ROUTER_QUEUE_ENABLED
tracing.pressure.mode   → DUCTOR_TRACING_PRESSURE_MODE

Config file

If neither DUCTOR_CONFIG nor --config is set, Ductor searches for a ductor.yaml in $HOME, the current directory, and /etc/ductor. Override with --config <path>.

Inline YAML

DUCTOR_CONFIG may contain a full YAML document. When set, it is parsed directly and takes precedence over any config file (the file is skipped). Invalid YAML aborts startup. This is the recommended way to inject config in Kubernetes — the Helm chart mounts it as DUCTOR_CONFIG from a Secret.

.env files

In development, a ./.env file is auto-loaded. It loads only when DUCTOR_ENVIRONMENT=development or DUCTOR_LOAD_DOTENV=true. A missing .env is ignored.

Validate what resolved

Use the CLI to print the effective config, its source, and DSN-redacted values:

ductor validate-config

Core & logging

Server

The server.* struct also carries an internal transport plane (server.internal_*) and an executor plane (server.exec_*) with their own mTLS, runner-kind, and payload/timeout settings — see the executor flags in the CLI reference.

Database

Cache (Redis / Dragonfly)

Authentication & authorization

API (Connect/gRPC + OIDC)

Routing engine (routing.*)

The credentials map resolves the auth_ref/tls_ref names on a remote strategy deployment into concrete transport security, and resolution fails closed — a deployment whose ref points at a missing or incomplete entry never registers. Each entry is keyed by an operator-chosen ref name (the <ref> above), so the map is normally set in YAML or inline DUCTOR_CONFIG rather than per-leaf env vars; the secret values themselves live in the env var named by token_env or the files the other keys point at, never in the config document. An entry must resolve at least one of token_env/token_file or TLS material, and tls_cert_file/tls_key_file must be set together. See Writing a custom strategy → Secure the transport.

routing.* has many more advanced sub-blocks (capacity_reconciliation, pin_cache, market_controls, middleware, runtime.queue, runtime.flow, dag_bridge). Consult internal/config/routing.go for the full set.

Queue & flow control (router.*)

Workflow runtime (workflow_runtime.*)

Run-mode concurrency is an opt-in nested block:

See Run-concurrency lease ownership for rollout and monitoring guidance.

The workflow runtime has an extensive set of optional feature blocks (sharding.range_id_fencing, result_externalization, scatter, stream, transition_compaction, defer, ops.*, worker_compatibility, inline_run, bridge_*). See internal/config/config_workflow.go.

Events & tracing

Connector

Archival & retention

Billing, entitlements & rate limits

Identity (SCIM / SAML)

AI inference (ai_inference.*)

The AI inference subsystem is the proxy every AI-assisted feature (routing strategies, the chat agent) calls through. It is off by default; enabling it wires a provider pool and a per-provider circuit breaker.

Providers (ai_inference.providers.<name>.*)

providers is a map keyed by an arbitrary provider name you choose (e.g. primary, fallback). Each entry configures one upstream:

AI routing policy (ai.routing.*)

Server-level cost and model-selection policy for AI-assisted routing decisions. Distinct from ai_inference.* (the transport) and from per-pool AI strategy config (which is dynamic, pool-level config, not here).

MCP (mcp.*)

Ductor's inbound Model Context Protocol server (it also imports tools from external MCP servers — see the glossary).

expose_unwired_tools only affects discovery: tools/call still returns ErrNotImplemented for an unwired tool regardless of the flag. Discovery is filtered; execution is not.

Clearing surfaces

The pricing, settlement, receipt, and agent-procurement planes each sit behind their own gate. All default off except connector_shared_executor. The operator view of what each gate guarantees and what fails closed is in Clearing surfaces.

Enabled award execution also validates a positive recovery interval and requires the award service at startup. Tenant ids are trimmed and deduplicated, but must already be canonical nonzero UUIDs. This coverage is static configuration, not a worker-health or capacity signal. Immediate-settlement markets do not gain award execution from this list.

Receipt worker policy

These keys belong under work_receipt.worker. The values below are both canonical zero-field defaults and the shipped YAML values. Enabled issuance resolves and validates this policy before starting the worker; negative values never select defaults. An issuance-disabled verification-only deployment ignores unused worker policy while retaining validation of its public verification keys.

Every claim increments attempts, including claims after crashes or lease recovery. Lifetime claims never reset. The current cycle counts attempts - claim_baseline; the initial cycle has baseline zero. An authorized redrive records the current lifetime count as the next baseline and advances retry_generation, with at most three redrive cycles. This is not a failed-attempt counter: success can complete beyond the cycle's threshold, while non-retryable evidence refusals can dead-letter immediately. Use the receipt recovery controls to inspect a failed request before requesting a redrive. Lowering lease_seconds without lowering the default processing timeout can make the policy invalid. An eleven-second lease permits at most 5.5s, not a rounded six seconds. The deployment supplies a unique explicit owner per replica; there is no operator owner override or shared static-owner fallback.

See bounded receipt issuance for shutdown behavior and recovery. Shutdown does not automatically finish all pending receipts or revive failed requests.

The snapshot/signing observer uses fixed timings: an immediate pass, a fifteen-second interval, a five-second database-read bound and at most thirty seconds to join on stop, subject to the remaining Fx deadline. There is no additional observer configuration flag. See clearing telemetry for interpreting sample freshness and database state.

Bounded bidder targets

The bidder values shown as shipped YAML come from configs/ductor.yaml, not implicit fallback bounds for custom configuration. config.Default() leaves the bidder values zero-valued. Supply positive request/scan/time bounds and a nonempty target list explicitly when enabling bidding in your own document.

Each entry in agent_rfq.bidder_targets contains:

Target records use a YAML file or inline YAML in DUCTOR_CONFIG. Do not assume DUCTOR_AGENT_RFQ_BIDDER_TARGETS accepts JSON or derive per-index env vars. The machine key resolves from the tenant-default secret partition, separately from the task environment. Current claims must permit agent_rfq:read, routing_market_bid:write, the environment, and worker ownership. Pricing uses its own exact model-only preset, separate from the registered fulfilment source.

A new job atomically reserves the full request ceiling from its target's Postgres-backed lifetime allowance. The counter never resets or refunds; the initial persisted cap can only be reduced. Increasing configuration cannot restore consumed slots. A reduction below reservations prevents new jobs; existing jobs retain their frozen bounds. Stable target scope, original subject, credential reference, and pricing source cannot be changed in place. The allowance is per target, not a tenant money budget. See bounded autonomous bidding and the complete opt-in example for dependencies, secret encoding, durable recovery, zero-retry pricing, and cost limits.

Public bidder observation reads persisted target caps and all-state job history without changing configuration or allowances. It requires the RFQ front door and current caller read/environment/ worker-ownership authority; bidder_enabled can remain false. Persisted targets can outlive current configuration. The view does not report current poller health, actual model usage, or whether the current per-job ceiling can fit remaining slots. Page limits are observation request bounds, separate from bidder_scan_limit. There is no allowance reset or increase operation on this read surface.

AI chat agent (aichat.*)

Mounts the durable chat API: turn admission, session list/detail, resumable events, input responses, turn cancellation, and feedback under /api/v1/chat. When a Slack connector is bound for agent conversations, the same runtime also serves the signed POST /agent-webhook/slack bridge. Approval links add GET and POST /agent-approval.

See External Conversation Bridges for Slack signature verification, participant bindings, ordered admission, same-thread replies, and single-use approval behavior.

Analytics (analytics.*)

A read-only proxy that lets the dashboard query Ductor's Prometheus metrics (stored in VictoriaMetrics) without the browser reaching VM directly. It validates PromQL against the K1 metric catalog and enforces tenant scoping.

Entitlement enforcement

Entitlement enforcement decides what happens when a tenant's plan/feature facts are missing, stale, or deny an action.

grace_unprovisioned only softens the never-had-any-entitlement case. Genuine gaps — a stale snapshot, a present-but-incomplete snapshot, or a tenant with sources but no snapshot — still fail closed under strict.

Key provider / BYOK (key_provider.*)

Bring-Your-Own-Key boot path for the connector-credential master key. When disabled (the default), the legacy connector.encryption_key path is used unchanged. When enabled, uri dispatches to a registered KEK backend and wrapped_master is unwrapped at boot into the 32-byte AEAD master.

Security profiles (security_profile)

security_profile (top-level, DUCTOR_SECURITY_PROFILE) applies a named posture after static config is resolved. The enterprise profile forces fail-closed controls — among them it requires key_provider.enabled, rejects a local key provider, rejects analytics.allow_unscoped_metrics, and forces the nonzero AI budget defaults described above. Config that would otherwise load happily is rejected under this profile, so validate it explicitly with ductor validate-config before rollout.

Dynamic configuration

Ductor has two distinct dynamic-config systems — don't conflate them:

• dynamic_config.* — a file-based hot-reload source. It watches a YAML file and re-reads on change so a subset of config can be updated without a restart.
• The dynamicconfig registry — a code-generated, typed, per-key registry (regenerated via make dynamicconfig-generate) that backs the writable runtime surface exposed at /api/config/{schema,export}.

Notifications (notification.*)

Notification management and dispatch are separately gated. Subscriber, topic, integration, layout, and preference APIs require the notification substrate; provider sends additionally require dispatch. Topic sends require the durable fan-out queue and never fall back to an in-process loop.

See Notification Platform for the send API and Delivery Reliability for payload limits, attempt semantics, observations, dead letters, and redrive.

Other subsystems

Ductor ships many more optional subsystems, each config-gated and off by default unless noted: webhooks.*, inbox.*, realtime.*, visibility.*, template.*, inbound_mail.*, dashboard.*, editor.*, cases.*, tables.*, approval.*, multi_region.*, per_namespace.*, bridge.*, egress.*, payload.*, audit.*, consent.*, fraud.*, yield.*, marketplace.*, reliability.*, debug.*, tls.*, cors.*. Each follows the same env-var rule; consult the corresponding file in internal/config/ for defaults.

See the API surface reference for how these subsystems' endpoints are served and discovered.