Skip to main content
Symphony is an engineering preview for testing in trusted environments. It launches coding agents with elevated access to your repository and Linear workspace.

​
Prerequisites

Before you begin, ensure you have:
  • A codebase that follows harness engineering principles
  • A Linear workspace with API access
  • Access to Codex or your preferred coding agent
Symphony works best in codebases with good test coverage, clear build commands, and automated CI/CD pipelines.

​
Two Paths Forward

You can either build your own Symphony implementation or use the reference Elixir implementation.

Build Your Own

Implement Symphony in your preferred language using the spec

Use Elixir Reference

Get started quickly with the provided Elixir implementation

​
Option 1: Build Your Own

The language-agnostic specification lets you implement Symphony in any language.
1

Read the specification

Review the complete specification to understand Symphony’s architecture and requirements.
curl -O https://raw.githubusercontent.com/openai/symphony/main/SPEC.md
2

Implement core components

Build the six core components:
  • Workflow Loader: Parse YAML frontmatter and Liquid templates
  • Tracker Client: Integrate with Linear’s GraphQL API
  • Orchestrator: Manage polling, dispatch, and reconciliation
  • Workspace Manager: Handle isolated workspace lifecycle
  • Agent Runner: Launch and communicate with coding agents
  • Status Surface: Provide runtime observability
See the implementation guide for detailed guidance.
3

Test your implementation

Validate your implementation against the specification:
  • Poll cycle completes successfully
  • Workspaces are created and cleaned up correctly
  • Agent sessions execute and report status
  • Retry logic handles transient failures
  • Reconciliation stops stale agents
4

Configure and run

Create your WORKFLOW.md configuration file and start the service. Jump to Configuration below.

​
Option 2: Elixir Reference

The reference Elixir implementation gets you running quickly.
1

Install dependencies

Install Elixir and Erlang using mise:
curl https://mise.run | sh
You should see:
Elixir 1.19.x (compiled with Erlang/OTP 28)
2

Build Symphony

Set up dependencies and build the binary:
mise exec -- mix setup
mise exec -- mix build
This creates the executable at bin/symphony.
3

Get Linear API key

Create a personal API key in Linear:
  1. Go to Settings → Security & access → Personal API keys
  2. Click Create new key
  3. Copy the key and set it as an environment variable:
export LINEAR_API_KEY="lin_api_xxxxx"
4

Find your project slug

Get your Linear project identifier:
  1. Open your Linear project
  2. Right-click the project name and select Copy link
  3. Extract the slug from the URL: https://linear.app/your-workspace/project/YOUR-PROJECT-SLUG

​
Configure Symphony

Create a WORKFLOW.md file in your repository:
WORKFLOW.md
---
tracker:
  kind: linear
  project_slug: "your-project-slug-here"
  active_states:
    - Todo
    - In Progress
  terminal_states:
    - Done
    - Closed
    - Cancelled

workspace:
  root: ~/code/symphony-workspaces

hooks:
  after_create: |
    git clone --depth 1 git@github.com:your-org/your-repo.git .
    # Add any additional setup commands here

agent:
  max_concurrent_agents: 10
  max_turns: 20

codex:
  command: codex app-server
  approval_policy: on-request
  thread_sandbox: workspace-write
---

You are working on Linear issue {{ issue.identifier }}.

**Title**: {{ issue.title }}

**Description**: {{ issue.description }}

{% if issue.labels %}
**Labels**: {{ issue.labels | join: ", " }}
{% endif %}

Complete this issue following our team's coding standards and practices.
See the workflow file reference for all configuration options and templating capabilities.

​
Key Configuration Options

  • kind: Currently only "linear" is supported
  • project_slug: Your Linear project identifier
  • active_states: Issue states Symphony will work on
  • terminal_states: States that trigger workspace cleanup
  • api_key: Defaults to $LINEAR_API_KEY environment variable
  • root: Base directory for all issue workspaces (supports ~ and $VAR)
  • Each issue gets a subdirectory: root/ISSUE-123/
  • max_concurrent_agents: Global agent concurrency limit (default: 10)
  • max_turns: Maximum agent turns per session (default: 20)
  • command: Shell command to launch Codex app-server
  • approval_policy: Control when agents need approval (never, on-request, on-failure, untrusted)
  • thread_sandbox: Workspace access level (workspace-write, read-only, danger-full-access)

​
Run Symphony

Start the orchestrator: 
cd symphony/elixir
mise exec -- ./bin/symphony ./WORKFLOW.md \
  --i-understand-that-this-will-be-running-without-the-usual-guardrails
The --i-understand-that-this-will-be-running-without-the-usual-guardrails flag is required. Symphony launches agents with elevated workspace access and does not enforce additional sandboxing beyond what you configure.

​
What Happens Next

Once started, Symphony will:
  1. Poll Linear every 5 seconds (configurable) for eligible issues
  2. Create workspaces for new issues using your after_create hook
  3. Dispatch agents up to your configured concurrency limit
  4. Monitor progress through Codex app-server events
  5. Retry failures with exponential backoff
  6. Clean up workspaces when issues reach terminal states
Use --port 4000 to access the observability dashboard at http://localhost:4000. See monitoring for details.

​
Verify It’s Working

Check that Symphony is operating correctly:
1

Check console output

You should see polling activity in the terminal:
[info] Poll tick: checking 3 candidate issues
[info] Dispatching ABC-123 (priority=1) to workspace
[info] Workspace created: ~/code/symphony-workspaces/ABC-123
[info] Agent session started for ABC-123
2

View the dashboard (optional)

If you enabled --port, open http://localhost:4000 to see:
  • Active agent sessions
  • Issue queue and states
  • Token usage and rate limits
  • Recent completion history
3

Check workspace creation

Verify that workspace directories exist:
ls -la ~/code/symphony-workspaces/
You should see directories named after Linear issue identifiers.
4

Monitor logs

Tail the structured log file:
tail -f log/symphony.log

​
Test with a Sample Issue

Create a test issue in Linear to verify end-to-end operation:
  1. Create a new issue in your configured Linear project
  2. Set the state to one of your active_states (e.g., “In Progress”)
  3. Add a clear description of what needs to be done
  4. Watch Symphony’s console output for dispatch activity
  5. Monitor the workspace directory for repository cloning and agent activity
Start with a simple, low-risk task like “Update README with current version” to validate your setup before tackling complex work.

​
Next Steps

Configure Linear Integration

Fine-tune issue selection, state management, and assignee filtering

Customize Workflow Prompts

Use Liquid templating to create powerful workflow prompts

Set Up Monitoring

Configure observability, dashboards, and log aggregation

Add Custom Skills

Extend agent capabilities with repository-specific skills

​
Troubleshooting

Error: Workflow file not found: /path/to/WORKFLOW.mdSolution: Ensure the path to WORKFLOW.md is correct. Use an absolute path or ensure you’re in the correct directory.
# Check file exists
ls -la ./WORKFLOW.md

# Use absolute path
./bin/symphony ~/my-repo/WORKFLOW.md --i-understand-that-this-will-be-running-without-the-usual-guardrails
Error: Linear API returned 401 UnauthorizedSolution: Verify your Linear API key is set correctly:
# Check environment variable
echo $LINEAR_API_KEY

# Ensure it starts with lin_api_
export LINEAR_API_KEY="lin_api_xxxxx"
Possible causes:
  • No issues in active_states for the configured project
  • All eligible issues are already running (check concurrency limit)
  • Issue validation failures (check logs for validation errors)
Debug steps:
  1. Check your Linear project for issues in active states
  2. Review Symphony logs: tail -f log/symphony.log
  3. Enable the dashboard to see issue queue state
  4. Verify project_slug matches your Linear project
Error: Failed to create workspace: permission deniedSolution: Ensure the workspace.root directory is writable:
# Check directory permissions
ls -ld ~/code/symphony-workspaces

# Create directory if needed
mkdir -p ~/code/symphony-workspaces
Possible causes:
  • Codex binary not in PATH
  • Agent approval required but not configured
  • Workspace hook script failures
Debug steps:
  1. Test Codex manually: codex app-server
  2. Check hook output in workspace creation logs
  3. Review codex.approval_policy setting
  4. Check agent logs in the workspace directory
For more detailed troubleshooting, see the troubleshooting guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us