Configuration Reference

WOML has two different configuration layers. <config> defines how one workflow is admitted and timed. woml.runtime.json defines how the host process stores state, listens, logs, and exposes operations. Keeping them separate prevents deployment details from leaking into the workflow language.

Workflow config

WOML

<config concurrency="4" rate-limit="100/1m" timeout="10m" queue="orders" />

Attribute	Contract
`concurrency`	Positive maximum active runs, up to 1,000,000.
`rate-limit`	Positive count and duration such as `100/1m`.
`timeout`	Total execution deadline from `1ms` through `365d`.
`queue`	Lowercase scheduling lane, maximum 128 characters.

Example interpretation:

WOML

<config concurrency="4" rate-limit="100/1m" timeout="10m" queue="orders" />

At most four runs of this workflow execute concurrently. No more than 100 are admitted per rolling minute according to the frozen policy contract. A run cannot execute beyond ten minutes. Eligible work uses the orders scheduling lane.

These policies are durable. Restarting the host does not intentionally erase the queue or reset the truth of admitted runs. See Runtime Policies for behavior under pressure.

Runtime config

woml.runtime.json uses schemaVersion: 1. Supported fields include deploymentName, statePath, public and admin host/port, logging format/level/directory, workers, shutdownTimeoutMs, health/metrics switches, retention policy, and backup directory.

JSON

{
  "schemaVersion": 1,
  "deploymentName": "order-automation",
  "statePath": "./data/workflow-history.sqlite",
  "public": { "host": "127.0.0.1", "port": 3000 },
  "admin": { "host": "127.0.0.1", "port": 3001 },
  "logging": {
    "format": "json",
    "level": "info",
    "directory": "./logs"
  },
  "workers": 4,
  "shutdownTimeoutMs": 30000,
  "observability": { "health": true, "metrics": true },
  "retention": {
    "enabled": true,
    "succeededAfterDays": 30,
    "failedAfterDays": 90,
    "cancelledAfterDays": 30,
    "maintenanceHourUtc": 3
  },
  "backup": { "directory": "./backups" }
}

Field	Meaning
`schemaVersion`	Required runtime configuration contract; exactly `1`.
`deploymentName`	Stable lowercase segmented identity, up to 128 characters.
`statePath`	Durable SQLite authority. Relative paths resolve from the config file.
`public`	Listener for public triggers such as webhooks and events.
`admin`	Local operations listener; production remains loopback-only.
`logging.format`	`text` for people or `json` for collectors.
`logging.level`	`error`, `warn`, `info`, or `debug`.
`logging.directory`	Runtime log destination.
`workers`	Bun worker capacity from 1 through 256.
`shutdownTimeoutMs`	Graceful drain window from 1,000 through 300,000 ms.
`observability`	Enables local health and Prometheus metrics endpoints.
`retention`	Automatic terminal-run retention by outcome, 1–3,650 days.
`backup.directory`	Default location for operational backups.

Workers range from 1–256 and shutdown timeout from 1,000–300,000 ms. Admin remains loopback-only in production. Precedence is explicit CLI option, reviewed WOML_RUNTIME_* variable, config file, then safe default.

Configuration precedence

When the same reviewed setting appears in multiple places, WOML uses:

Explicit CLI option.
Supported WOML_RUNTIME_* environment variable.
woml.runtime.json value.
Safe built-in default.

Use CLI overrides for temporary operational changes, not as an undocumented permanent deployment configuration.

Validate before deployment

Terminal

woml check workflows/ --config woml.runtime.json

This verifies configuration shape, relevant paths and listeners, workflow contracts, and referenced production secrets without activating triggers.