Configuration

Not all of Ductor's configuration is baked in at boot. A meaningful slice is runtime-writable — feature flags you toggle, per-tenant overrides you set, a routing pipeline mode you flip — and takes effect across the fleet without a redeploy. This page maps the config surface: what you can read, what you can change at runtime, and what is fixed at process start via environment variables.

Two tiers of configuration

The static tier is the deployment's shape — connection strings, ports, keys — and is documented in Getting Started and the deployment guides. Everything below is the dynamic tier.

System config: ConfigService

System-wide dynamic config lives under /api/config, resource_type: "config".

Snapshot and version

GetConfigSnapshot returns the entire current system config as a key/value map — this is your export of what the running config actually is:

curl -s https://api.ductor.io/api/config \
  -H "Authorization: Bearer $DUCTOR_ADMIN_TOKEN"

GetVersion returns a version, a content hash, and loaded_at — cheap to poll, and the right way to detect that config changed without pulling the whole snapshot:

{ "version": "2026-07-11T09:00:00Z", "hash": "sha256:1f3c…", "loaded_at": "2026-07-11T09:00:02Z" }

Feature flags

ListFlags returns every flag with its enabled state and rollout percentage. ToggleFlag updates one, keyed in the URL:

curl -s -X PUT https://api.ductor.io/api/config/flags/enable_advanced_routing \
  -H "Authorization: Bearer $DUCTOR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "percentage": 25 }'

percentage (0–100) drives a gradual rollout and only applies when enabled is true. The response echoes the updated FeatureFlag.

Reload

ReloadConfig forces an immediate re-read from the backing store and returns the new version + hash. It requires the admin action (stricter than the write used for flag toggles) because it re-loads the entire config:

curl -s -X POST https://api.ductor.io/api/config/reload \
  -H "Authorization: Bearer $DUCTOR_ADMIN_TOKEN"

Per-tenant config: TenantConfigService

Per-tenant overrides live under /api/tenants/{tenant_id}/config, resource_type: "tenant_config".

GetTenantConfig returns only the tenant's own overrides — not inherited defaults. SetTenantConfig replaces the entire config (it's a PUT, not a merge), so read-modify-write the whole object:

curl -s -X PUT https://api.ductor.io/api/tenants/$DUCTOR_TENANT/config \
  -H "Authorization: Bearer $DUCTOR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "config": { "default_strategy": "weighted_round_robin", "features": { "beta_scoring": true } } }'

GetResolvedConfig is the one you'll reach for when debugging "why is this tenant behaving this way" — it returns the fully merged view (system defaults + tenant overrides + optional pool-level overrides) plus a sources list showing precedence order. Pass pool_id to fold in a pool's overrides too:

curl -s "https://api.ductor.io/api/tenants/$DUCTOR_TENANT/config/resolved?pool_id=$POOL_ID" \
  -H "Authorization: Bearer $DUCTOR_ADMIN_TOKEN"

Runtime config refs: RuntimeConfigService

RuntimeConfigService (/api/runtime-config, resource_type: "runtime_config") is a read-only, always-redacted surface describing the runtime dependencies an executable artifact needs — the secrets, variables, connection metadata, and non-secret config it references. It never returns plaintext secret values; it answers questions about config bindings:

Use impact:preview before rotating a secret or deleting a variable to see every artifact that would be affected — it's the safe pre-flight for config changes that ripple across workflows and connections.

Routing pipeline mode

Pipeline mode selects how a routing request is executed. It's resolved per-request down a chain — pool → tenant → global — with each level able to inherit from the next.

The resolver (domain/pool/pipeline_mode.go, Resolve) walks the chain and returns the first concrete (non-inherit) value: pool override wins, else the tenant override, else the global setting. If all three levels are inherit (the out-of-the-box state, the safe fall-through for an unknown value), it resolves to dag — so a fresh install routes through the DAG runtime with no configuration.

# Set a single pool to the linear kill-switch path
ductor pipeline-mode set --pool $POOL_ID --mode linear

# Set the tenant-wide default
ductor pipeline-mode set --tenant $DUCTOR_TENANT --mode dag

--pool and --tenant are mutually exclusive; exactly one is required. The command accepts inherit|linear|shadow|dag at the flag level, but a shadow write is rejected downstream as retired (see above).

What's runtime-writable, at a glance

Where to go next