# WORKFLOW.md Front Matter Configuration Options in OpenAI Symphony

> Explore WORKFLOW.md front matter options in OpenAI Symphony. Configure tracker, polling, workspace, hooks, agent, and codex for powerful workflow orchestration.

- Repository: [OpenAI/symphony](https://github.com/openai/symphony)
- Tags: api-reference
- Published: 2026-05-08

---

**The [`WORKFLOW.md`](https://github.com/openai/symphony/blob/main/WORKFLOW.md) file in `openai/symphony` uses YAML front matter to configure six top-level orchestration parameters—`tracker`, `polling`, `workspace`, `hooks`, `agent`, and `codex`—that govern Linear integration, workspace lifecycle, agent concurrency, and LLM execution sandboxing.**

The [`WORKFLOW.md`](https://github.com/openai/symphony/blob/main/WORKFLOW.md) file located in the repository’s `elixir/` directory defines the runtime behavior of Symphony’s automated workflow agents. Its YAML front matter block, delimited by `---` markers at the top of the file, supplies the complete configuration for how the orchestration system connects to issue trackers, manages temporary workspaces, and executes AI-powered tasks.

## Tracker Integration Settings

The **`tracker`** key configures the connection to your issue tracking system and maps ticket states to the agent’s internal workflow logic. According to the source code in [`elixir/WORKFLOW.md`](https://github.com/openai/symphony/blob/main/elixir/WORKFLOW.md), this section supports the following sub-keys:

- **`kind`** – Specifies the issue tracking system (e.g., `linear`).
- **`project_slug`** – The unique identifier for the Linear project (e.g., `"symphony-0c79b11b75ea"`).
- **`active_states`** – Array of ticket states considered "in progress" (e.g., `Todo`, `In Progress`, `Merging`, `Rework`).
- **`terminal_states`** – Array of states that signal workflow completion (e.g., `Closed`, `Cancelled`, `Canceled`, `Duplicate`, `Done`).

```yaml
tracker:
  kind: linear
  project_slug: "symphony-0c79b11b75ea"
  active_states:
    - Todo
    - In Progress
    - Merging
    - Rework
  terminal_states:
    - Closed
    - Cancelled
    - Canceled
    - Duplicate
    - Done

```

## Polling Frequency and Workspace Paths

The **`polling`** and **`workspace`** keys control the operational tempo and file system layout of the orchestration system.

**`polling`** accepts:
- **`interval_ms`** – The frequency in milliseconds that the agent polls the tracker for updates (default: `5000`).

**`workspace`** accepts:
- **`root`** – The base directory where per-ticket workspaces are materialized (e.g., `~/code/symphony-workspaces`).

```yaml
polling:
  interval_ms: 5000
workspace:
  root: ~/code/symphony-workspaces

```

## Lifecycle Hooks for Workspace Management

The **`hooks`** key defines shell scripts executed at specific points in the workspace lifecycle, allowing custom setup and teardown procedures.

- **`after_create`** – Executed immediately after a new workspace directory is instantiated. Typically used for cloning repositories and installing dependencies.
- **`before_remove`** – Executed before a workspace is torn down, useful for cleanup tasks or final state persistence.

```yaml
hooks:
  after_create: |
    git clone --depth 1 https://github.com/openai/symphony .
    if command -v mise >/dev/null 2>&1; then
      cd elixir && mise trust && mise exec -- mix deps.get
    fi
  before_remove: |
    cd elixir && mise exec -- mix workspace.before_remove

```

## Agent Concurrency and Turn Limits

The **`agent`** key imposes resource guardrails on the orchestration system to prevent runaway processes and manage server load.

- **`max_concurrent_agents`** – Hard ceiling on simultaneous agent processes (default: `10`).
- **`max_turns`** – Per-agent limit on interaction turns before forced termination (default: `20`).

```yaml
agent:
  max_concurrent_agents: 10
  max_turns: 20

```

## Codex LLM and Sandboxing Configuration

The **`codex`** key configures the underlying LLM-powered executor, including model selection, sandboxing policies, and approval behaviors.

- **`command`** – The base shell command used to launch the Codex AI worker, including model specifications and configuration overrides.
- **`approval_policy`** – Controls auto-approval privileges (`never` in the default configuration).
- **`thread_sandbox`** – Sandboxing mode for the entire conversation thread (`workspace-write`).
- **`turn_sandbox_policy.type`** – Sandboxing mode for individual turns (`workspaceWrite`).

```yaml
codex:
  command: codex --config shell_environment_policy.inherit=all --config 'model="gpt-5.5"' --config model_reasoning_effort=xhigh app-server
  approval_policy: never
  thread_sandbox: workspace-write
  turn_sandbox_policy:
    type: workspaceWrite

```

## Practical Configuration Examples

When customizing a Symphony deployment, you can override specific front matter values while preserving the rest of the configuration structure.

**Reducing API load by extending the polling interval:**

```yaml
polling:
  interval_ms: 10000

```

**Directing agents to a different Linear project:**

```yaml
tracker:
  kind: linear
  project_slug: "my-custom-project"

```

**Adding automated linting to the workspace creation hook:**

```yaml
hooks:
  after_create: |
    git clone --depth 1 https://github.com/openai/symphony .
    cd elixir && mix deps.get
    mix compile
    mix credo --strict

```

**Increasing parallel throughput for high-volume environments:**

```yaml
agent:
  max_concurrent_agents: 25
  max_turns: 20

```

**Switching to a newer model while preserving sandboxing:**

```yaml
codex:
  command: codex --config shell_environment_policy.inherit=all --config 'model="gpt-6.0"' --config model_reasoning_effort=high app-server
  approval_policy: never
  thread_sandbox: workspace-write
  turn_sandbox_policy:
    type: workspaceWrite

```

## Summary

- The [`WORKFLOW.md`](https://github.com/openai/symphony/blob/main/WORKFLOW.md) front matter in `openai/symphony` uses six top-level YAML keys to configure the entire orchestration system.
- **`tracker`** maps Linear states to active and terminal workflow phases.
- **`polling`** and **`workspace`** control operational timing and directory structure.
- **`hooks`** enable custom setup via `after_create` and cleanup via `before_remove` shell scripts.
- **`agent`** enforces concurrency limits (`max_concurrent_agents`) and interaction caps (`max_turns`).
- **`codex`** configures the LLM executor, including sandbox policies (`thread_sandbox`, `turn_sandbox_policy`) and approval controls.

## Frequently Asked Questions

### What happens if I omit the `terminal_states` list in the tracker configuration?

The workflow agent will not recognize which Linear ticket states indicate completed work, potentially causing agents to continue processing tickets that should be ignored. Always define `terminal_states` to include values like `Closed`, `Done`, or `Cancelled` according to your Linear workflow.

### Can I use environment variables in the `workspace.root` path?

The front matter is parsed as static YAML, so you should use shell expansion in your deployment scripts rather than environment variables directly in the YAML value. Write the absolute path (e.g., `~/code/symphony-workspaces`) and ensure the directory exists before the agent starts.

### How do I prevent the Codex agent from auto-approving dangerous operations?

Set **`codex.approval_policy`** to `never` as shown in the default configuration. This forces the system to require explicit human approval for all actions, regardless of the sandbox settings. The `thread_sandbox` and `turn_sandbox_policy` provide additional filesystem isolation but do not replace approval controls.

### What is the difference between `thread_sandbox` and `turn_sandbox_policy`?

**`thread_sandbox`** applies to the entire conversation thread (the complete lifecycle of a single ticket’s agent), while **`turn_sandbox_policy`** governs individual interaction turns within that thread. In the default [`WORKFLOW.md`](https://github.com/openai/symphony/blob/main/WORKFLOW.md), both are set to `workspace-write`, allowing write access to the ticket-specific workspace directory.