Configuration reference

The complete front-matter contract for WORKFLOW.md. This page is for integrators who want every key, its type, its verified default, and its meaning in one place. It supersedes the configuration section of the README; where the two disagree, this page and the code win.

Lorenz reads a single file per repository: WORKFLOW.md. The file has two parts. The YAML front matter (between the first --- and the next ---) is the config covered here. The Markdown body below it is the agent prompt template, documented in workflow-prompt.md. The runtime reloads this file before each poll, so config changes apply without a restart. See workflow-hot-reload for the reload semantics.

---
tracker:
  kind: linear          # selects the bundle
trackers:
  linear:
    provider: linear    # names the implementation
    api_key: $LINEAR_API_KEY
    project_slugs: [backend]
polling:
  interval_ms: 30000
agent:
  kind: codex
  max_concurrent_agents: 4
---
You are working on {{ issue.identifier }}: {{ issue.title }}.

The nested bundle form above is the recommended shape: tracker.kind selects the bundle and the matching trackers.<bundle>.provider names the implementation. The flat form (provider options directly under tracker) is a terser shorthand for the same config; see Bundle and flat shapes.

How keys are named

Front-matter keys are snake_case. The parser normalizes them to camelCase internally, but that is an implementation detail; write the snake_case form shown in every table below. Each section is validated against a strict schema: unknown keys inside a known section raise an operator-readable error (<section>.<key> is not supported). Two sections are deliberately open: trackers.<name> and agents.<kind> pass provider-specific and executor-specific keys straight through to the provider, which validates them.

Error messages are emitted in snake_case (for example tracker.active_states must be a list of strings), except provider passthrough keys that surface their camelCase spelling (for example tracker.baseUrl must be a string).

Secret syntax

Any string value can be a secret reference. Resolution runs at parse time.

Order: an inline $VAR that resolves non-empty wins; otherwise the provider env fallback applies; then any op:// value is read. A bare op:// fallback resolves even when no inline value is set. A missing op binary throws 1Password CLI (op) is required ... cannot be managed by mise.; a failed read throws Failed to resolve 1Password reference: <ref>. See secret-resolution.

Diagram placeholder: secret resolution decision tree (inline $VAR then provider env fallback then op:// 1Password read), with the empty-string and bare-op:// edge cases. Caption: how a single string value becomes a resolved secret.

Environment variables

These are read directly, outside the front matter.

tracker

The core tracker bundle. tracker.kind selects the provider. There is no default kind: validateDispatchConfig throws tracker.kind is required if it is unset, so this key is effectively mandatory. See trackers.

active_states, terminal_states, and the dispatch.* keys are core fields shared by every provider, not provider-specific. See dispatch and dispatch-routing.

Bundle and flat shapes

The recommended nested bundle shape names the implementation explicitly: tracker.kind selects the bundle and the matching trackers.<bundle>.provider names the provider (it does not default to the bundle name). The selector options under tracker merge into that bundle.

The flat shape (tracker.kind: <provider> with provider options directly under tracker) still works when no matching trackers.<name> bundle is present, but it is deprecated: provider-specific keys placed directly under tracker (anything outside the core selector keys kind, provider, endpoint, api_key, assignee, active_states, terminal_states, dispatch) emit a deprecation warning recommending you move them into a trackers.<name> bundle selected by tracker.kind. The warning is printed at daemon start, at config validation, and as a config_deprecation_* check in lorenz doctor. Unregistered kinds parse generically (options pass through unvalidated) and are rejected at dispatch validation.

Diagram placeholder: tracker selection, flat tracker.kind versus a trackers.<name>.provider bundle, and option passthrough to provider.parseOptions. Caption: how the parser picks a provider and hands it its option slice.

trackers.<name>

Named tracker bundles, used with the dispatch kind or to define multiple trackers. Keys beyond provider pass through to the named provider.

Per-provider tracker options

The keys below live under tracker (flat shape) or trackers.<name> (bundle shape).

linear

See trackers/linear.md. Requires api_key and exactly one of project_slugs, project_labels, or the deprecated singular project_slug.

jira

Direct Jira Cloud REST v3. See trackers/jira.md. Requires base_url, email, api_key, and at least one of jql or project_keys. Issues must be labeled agent and assigned to the worker, or Lorenz never dispatches them; that gate is not configurable.

jira-mcp

Jira operations proxied as JSON-RPC tools/call requests to an external MCP server. Requires mcp.url (and at least one of jql or project_keys); has no env fallback for credentials. The agent label gate still applies.

project_keys, jql, issue_type, and assignee carry the same meaning as the jira kind. The mcp.tools.* keys accept both snake_case and camelCase; search and comment have no snake_case alias.

local

Filesystem board: one Markdown file per issue. See trackers/local.md. path is optional and defaults to .lorenz/local; an explicitly empty path is rejected.

slack

Slack as a tracker: an @-mention of the bot becomes an issue. See trackers/slack.md. Requires channels and bot_user_id. assignee is rejected for this kind.

The shipped Slack workflow uses polling.interval_ms: 60000 and dispatch.route_label_prefix: route-, because conversations.history can be throttled to roughly one request per minute.

discord

Discord as a tracker: a bot-user or bot-managed-role mention in a configured guild channel becomes an issue whose native thread carries status and progress. See trackers/discord.md. Requires guild_id, channels, bot_user_id, and a bot token. assignee is rejected for this kind.

memory

In-process tracker for tests and dry runs. See trackers/memory.md. Takes no options; issues come from LORENZ_MEMORY_TRACKER_ISSUES_JSON (fallback LORENZ_MEMORY_TRACKER_ISSUES). Exposes no agent tools.

tools.<pack>

Per-tool-pack options. String values are secret-resolved. Tool packs mount automatically for the dispatch tracker (for example Linear mounts the linear pack); these keys override credentials or mount a pack standalone. See jira-tools.md.

The Jira pack was renamed from tracker to jira; the former tools.tracker key was removed, so use tools.jira.

The tools.linear slice accepts only api_key/apiKey and endpoint; any other key throws tools.linear.<key> is not supported. The tools.local slice accepts only path and idPrefix/id_prefix.

polling

workspace

Where agent runs check out. See workspace.

worker

Where agent runs execute. The warm pool is the single dispatch path; the legacy ssh_hosts list folds into a static-ssh pool. You cannot name a driver twice for the same hosts: worker.ssh_hosts cannot combine with worker_pool.driver or worker.kind. See workers.

worker.worker_pool

The embedded warm pool. See worker-pool.

workers.<name>

Driver profiles referenced by worker.kind or worker_pool.driver. The driver key selects the backend; all other keys pass through verbatim to that driver. See docker and static-ssh.

hooks

Lifecycle shell hooks. See workspace. Each runs at a workspace lifecycle point. workspace.isolation: none forbids them.

agent

Run-loop and concurrency settings, independent of which executor runs. See agent-orchestrator.

agents

Executor records keyed by kind, plus shared timeout defaults. The agents block is the single runtime source of truth for executors. See agents and acp-bridges.

Every agents.<kind> key is also eligible as a same-named route. A Lorenz:claude label selects agents.claude when the route prefix is Lorenz:. This selection does not change accept_unrouted or only_routes eligibility.

The built-in codex record uses bridge_command: codex-acp. The built-in claude record uses bridge_command: claude-agent-acp and a provider_config of {model: claude-opus-4-6[1m], permissions: {defaultMode: dontAsk}}. That model pin is DEFAULT_CLAUDE_MODEL (currently claude-opus-4-6[1m]; the authoritative value lives in packages/config/src/defaults.ts). The bridge_command is a single shell command string split on whitespace; there is no bridge_args key. See codex and claude.

Legacy agent sugar

Top-level codex: and claude: sections map into agents.<kind> records. command maps to bridge_command (the canonical key wins when both are set). claude.model pins provider_config.model unless provider_config already sets it. These sections are deprecated: every key under a top-level codex:/claude: block emits a deprecation warning naming its agents.<kind> replacement. The warning is printed at daemon start, at config validation, and as a config_deprecation_* check in lorenz doctor. Prefer the agents block.

status_overrides

Per-state setting overrides, keyed by issue state name (normalized with trim and lowercase). Each entry can override agent fields and per-kind agents fragments, merged into the effective settings for an issue in that state. A per-state fragment cannot retarget skills or switch executor; both keys are rejected.

Diagram placeholder: status_overrides merge into the effective per-issue-state settings (settingsForIssueState). Caption: how a state name selects an override fragment that is merged onto a cloned base.

observability

TUI dashboard settings. See observability.

server

The HTTP observability server, agent MCP listener, and trace store. See http-api.md.

The config default for server.port is 4040, not disabled. Whether the web server actually starts is gated separately by the --no-dashboard CLI flag, not by this default.

logging

See also

• workflows.md - writing and structuring WORKFLOW.md
• workflow-prompt.md - the Markdown prompt template and its variables
• trackers/index.md - choosing and configuring a tracker
• secret-resolution - how $VAR and op:// references resolve
• workflow-hot-reload - reload semantics and last-good fallback