OpenAI Symphony: Autonomous Coding Agent Orchestration Guide

Direct answer

OpenAI Symphony is an open-source specification and experimental Elixir reference implementation for turning an issue tracker into a control plane for coding agents. Instead of asking an engineer to babysit several Codex sessions, Symphony polls work items, creates an isolated workspace per issue, launches Codex in app-server mode, runs a workflow prompt, and keeps the task moving until it reaches a review or terminal state.

The practical idea is bigger than a new CLI command: manage project work, not individual agent chats. Symphony is useful for teams that already have strong repository instructions, deterministic checks, isolated workspaces, and human review. It is not production-hardened software out of the box—the repository explicitly describes the Elixir implementation as a prototype for trusted environments—so treat it as an architecture to adapt, not a turnkey autonomous engineering department.

Key takeaways

• Symphony uses an issue tracker such as Linear, GitHub Issues, Jira Cloud, Asana, or GitLab as the work queue and control plane.
• Each issue gets a deterministic, isolated workspace and an agent session rather than sharing one broad working directory.
• The language-agnostic SPEC.md separates policy, scheduling, workspace management, agent execution, tracker integration, and observability.
• The reference implementation can restart stalled agents, reconcile tracker state, expose blocked work, and cap concurrency.
• Safety still depends on the implementation: approval policy, sandbox mode, network access, credentials, branch protection, and human review must be designed explicitly.

What Symphony changes in the coding-agent loop

A conventional agent workflow looks like this: an engineer opens a session, gives it a task, watches tool calls, reviews the diff, and repeats. That model is manageable for a few tasks, but attention becomes the bottleneck when a repository has a large queue of independent work.

Symphony changes the unit of coordination from a chat session to a work item. The tracker remains the source of task state while the orchestrator owns dispatch, retries, reconciliation, and runtime status. A completed task can stop at a workflow-defined handoff such as Human Review; it does not have to merge or deploy automatically.

The official repository describes Symphony as a service that continuously reads a configured tracker, creates a per-issue workspace, and runs a coding agent inside it. InfoQ independently reports the same core design: tasks are assigned to dedicated agents, agents can be restarted when they stall, and humans remain responsible for reviewing the result. Those two sources satisfy the core-claim gate while also making the important limitation clear: this is orchestration, not proof that generated code is safe.

Figure 1 — Original architecture diagram based on the component boundaries and lifecycle described in the official Symphony specification. It is an editorial abstraction, not an official OpenAI diagram.

How the reference implementation works

The current Elixir implementation is deliberately easy to inspect. Its README says it can poll Linear, GitHub Issues, Jira Cloud, Asana, and GitLab; create a workspace per issue; launch Codex in app-server mode; and continue the workflow until the work is done or requires operator input.

A useful detail is how credentials are handled. Provider-native tracker tools can be advertised to the app-server session, while configured tracker tokens remain host-side and are removed from the Codex child environment. That reduces the need to give the agent a second copy of a tracker credential. It does not eliminate risk: the orchestrator, host, tool adapter, and workspace still need to be trusted and audited.

The implementation also distinguishes blocked work from completed work. If Codex reports that approval, operator input, or MCP elicitation is required, Symphony keeps the issue claimed and exposes it as blocked through runtime state, the JSON API, and the optional dashboard. That is a healthier default than silently retrying a sensitive action forever.

The repository's SPEC.md defines the portable design in layers:

This separation is closely related to the principles in the harness engineering guide for AI coding agents: prompts are only one part of a reliable agent system. Repository context, permissions, tests, telemetry, and stop conditions are equally important.

Installation and a minimal workflow

The reference implementation recommends Elixir/Erlang version management with mise. The verified setup path from the project README is:

1git clone https://github.com/openai/symphony
2cd symphony/elixir
3mise trust
4mise install
5mise exec -- mix setup
6mise exec -- mix build
7mise exec -- ./bin/symphony ./WORKFLOW.md

The project also documents self-contained Burrito release targets for macOS ARM64, macOS x86_64, Linux ARM64, and Linux x86_64. Those binaries still expect codex, git, and the selected tracker credentials on the target machine.

A minimal workflow file contains YAML configuration followed by the prompt sent to Codex:

1---
2tracker:
3  kind: linear
4  provider:
5    api_key: $LINEAR_API_KEY
6    project_slug: "your-project-slug"
7workspace:
8  root: ~/code/symphony-workspaces
9agent:
10  max_concurrent_agents: 4
11  max_turns: 12
12codex:
13  command: codex app-server
14---
15
16Work on the assigned issue in the repository workspace.
17Run the required tests and report changed files, evidence, and blockers.
18Stop at Human Review when the implementation is ready for a person.

Do not copy this into production unchanged. The official README notes that workflow status names, provider settings, approval policy, sandbox mode, and network access need to match the target environment. In particular, never place a literal tracker token in a repository-owned workflow file; use host-side environment references or a secret broker.

A safer production adaptation

Symphony's own warning is important: the Elixir implementation is prototype software intended for evaluation. A production adaptation should begin with a threat model rather than a higher concurrency number.

Start with isolated workspaces and least privilege

Map each issue to a disposable or clearly owned workspace. Give the agent only the repository and task data it needs. Keep production credentials, broad cloud tokens, and personal SSH keys outside the child process. Use short-lived credentials where possible, and separate read, branch-write, merge, deployment, and production actions into different capabilities.

Make approval boundaries explicit

The specification intentionally does not mandate one universal approval or sandbox posture. That flexibility is useful, but it means the implementer must document the choice. A reasonable baseline is workspace-write access with network access disabled by default, explicit approval for sandbox escalation, MCP elicitation, credential use, deployment, and irreversible data changes.

Treat the tracker as a control plane, not a security boundary

An issue description can contain a prompt injection, an accidental secret, or an instruction that conflicts with repository policy. Parse tracker content as untrusted task input. Keep system policy separate from issue text, validate state transitions, and require human review for changes to auth, billing, infrastructure, migrations, and externally visible behavior.

Capture evidence, not just final text

For every run, store the issue identifier, workspace, commit or diff, commands executed, exit codes, tests, logs, agent turns, approvals, tool calls, and known limitations. A PR that says “tests pass” is weaker than one that links the exact commands and artifacts. This is where Symphony should connect to the OpenAI Agents SDK sandbox and harness patterns rather than relying on an unrestricted local shell.

Symphony compared with a normal coding-agent setup

This is not a claim that one replaces the other. Interactive sessions remain better for ambiguous product decisions, debugging with a human, and tasks whose acceptance criteria are still changing. Symphony is more interesting when the queue is clear and each task can be validated independently.

Common errors and debugging checks

Agents never dispatch. Check the tracker kind, project scope, active states, required labels, assignee settings, and the API token. An issue that is not eligible should remain visible as ineligible rather than being forced into a run.

The service starts but tasks fail immediately. Confirm that the codex command resolves on the host, the app-server mode is supported by the installed Codex version, the workspace hook creates a valid repository, and the workflow YAML parses correctly.

Package installation or tests cannot reach the network. The specification and README make network access a policy decision. Set network access only in the sandbox policy that needs it, prefer an egress allowlist, and log outbound requests. Do not solve this by giving every agent unrestricted host networking.

A stalled agent consumes a slot. Inspect retry and timeout logs, then verify that the orchestrator reconciles tracker state and releases terminal issues. Keep concurrency low until the failure and cleanup path is tested.

The agent makes plausible but wrong changes. Improve the task contract and acceptance evidence before increasing model capability. Add structural checks, focused tests, browser or integration evidence, and a separate review gate for changes that deterministic tests cannot judge.

FAQ

Is Symphony a hosted OpenAI product?

No. OpenAI presents Symphony as an open-source specification and reference implementation that developers can adapt. The repository is Apache-2.0 licensed, while the Elixir implementation is described as experimental prototype software.

Does Symphony require Codex?

The reference implementation launches Codex in app-server mode, and the specification names a coding-agent executable that supports the targeted protocol. A compatible implementation could adapt the execution layer, but that is engineering work—not a documented plug-and-play promise.

Does it merge pull requests automatically?

Not by default. The design supports workflow-defined handoff states and review evidence. Teams can add merge or deployment automation, but those actions should be separate approval boundaries rather than an assumption baked into the scheduler.

Is it safe to run on a developer laptop?

Only for a trusted evaluation with carefully scoped credentials and a disposable repository. The official warning is a reason to start in a sandbox or isolated machine, not a reason to expose a personal workstation and production tokens to autonomous runs.

Conclusion

Symphony's important contribution is a change in abstraction: coding agents become workers in a supervised project system instead of isolated chats that humans manually keep alive. Its tracker adapters, per-issue workspaces, app-server sessions, retry behavior, and language-agnostic specification provide a concrete starting point for teams building agent-native delivery workflows.

The engineering lesson is equally important: orchestration multiplies both productivity and mistakes. Before raising concurrency, build the boring controls—repository instructions, deterministic checks, workspace isolation, secret boundaries, network policy, observable evidence, and human review. Symphony is worth studying precisely because it makes those system boundaries visible.

Sources and visual credits

• OpenAI Symphony repository — primary source for the README, implementation status, supported trackers, setup, and license.
• Symphony service specification — primary source for architecture, lifecycle, state, and security-policy boundaries.
• Symphony Elixir README — primary source for installation, configuration, workspace behavior, and warnings.
• InfoQ: OpenAI Open-Sources Symphony — independent secondary confirmation and architectural reporting.
• Figure 1 Mermaid diagram — original editorial visualization derived from the official specification; no external image rights claimed.