Skip to main content

​
Starting Symphony

Symphony is started via the command-line interface with a workflow configuration file: 
./bin/symphony /path/to/WORKFLOW.md
If no path is provided, Symphony defaults to ./WORKFLOW.md in the current directory.

​
CLI Flags

Symphony supports the following command-line flags: 
./bin/symphony ./WORKFLOW.md

​
Available Flags

FlagTypeDescription
--logs-rootstringCustom directory for log files (default: ./log)
--portintegerEnable HTTP observability server on specified port
--i-understand-that-this-will-be-running-without-the-usual-guardrailsbooleanRequired acknowledgement flag for running Symphony
The acknowledgement flag is required to start Symphony. This ensures you understand that Symphony runs Codex without the usual guardrails.

​
Acknowledgement Banner

When started without the required acknowledgement flag, Symphony displays: 
╭──────────────────────────────────────────────────────────────────────────────╮
│                                                                              │
│ This Symphony implementation is a low key engineering preview.              │
│ Codex will run without any guardrails.                                      │
│ SymphonyElixir is not a supported product and is presented as-is.           │
│ To proceed, start with `--i-understand-that-this-will-be-running-without-the-usual-guardrails` CLI argument │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
Source: cli.ex:114-144 (elixir/lib/symphony_elixir/…)

​
Stopping Symphony

Symphony can be stopped using standard process signals:
1

Graceful Shutdown

Send SIGTERM or SIGINT (Ctrl+C) to the Symphony process:
kill -TERM <symphony-pid>
# or press Ctrl+C in the terminal
Symphony will wait for the supervisor to shut down normally.
2

Force Stop

If graceful shutdown hangs, use SIGKILL:
kill -9 <symphony-pid>
Force-stopping Symphony may leave Codex processes running. Clean up workspaces manually after force shutdown.

​
Restarting Symphony

To restart Symphony:
  1. Stop the current Symphony process
  2. Start Symphony again with the same or updated configuration:
./bin/symphony ./WORKFLOW.md
Symphony will:
  • Clean up terminal workspaces on startup
  • Resume polling for active issues
  • Reconcile running agents with the current state
Symphony performs terminal workspace cleanup during initialization to remove workspaces for issues that are no longer active.

​
Production Considerations

​
Process Supervision

For production deployments, run Symphony under a process supervisor: 
[Unit]
Description=Symphony Orchestration Service
After=network.target

[Service]
Type=simple
User=symphony
WorkingDirectory=/opt/symphony
Environment="LINEAR_API_KEY=your-api-key"
ExecStart=/opt/symphony/bin/symphony \
  --i-understand-that-this-will-be-running-without-the-usual-guardrails \
  --logs-root /var/log/symphony \
  --port 4000 \
  /etc/symphony/WORKFLOW.md
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

FROM elixir:1.19-otp-28-alpine

WORKDIR /app

COPY . .

RUN mix local.hex --force && \
    mix local.rebar --force && \
    mix deps.get && \
    mix compile

CMD ["./bin/symphony", \
     "--i-understand-that-this-will-be-running-without-the-usual-guardrails", \
     "--logs-root", "/var/log/symphony", \
     "--port", "4000", \
     "/app/WORKFLOW.md"]

​
Resource Management

1

Configure Maximum Concurrent Agents

Set agent.max_concurrent_agents in your WORKFLOW.md:
agent:
  max_concurrent_agents: 10
  max_turns: 20
Source: config.ex:28-29 (elixir/lib/symphony_elixir/…)
2

Configure Workspace Storage

Ensure sufficient disk space for workspaces:
workspace:
  root: /mnt/symphony-workspaces
Default: System.tmp_dir()/symphony_workspaces
3

Set Timeout Values

Configure timeouts for long-running operations:
codex:
  turn_timeout_ms: 3600000  # 1 hour
  read_timeout_ms: 5000     # 5 seconds
  stall_timeout_ms: 300000  # 5 minutes
hooks:
  timeout_ms: 60000         # 1 minute
Source: config.ex:27-34 (elixir/lib/symphony_elixir/…)

​
Log Rotation

Symphony uses rotating disk logs with configurable size and retention: 
# Default configuration
@default_max_bytes 10 * 1024 * 1024  # 10 MB per file
@default_max_files 5                  # Keep 5 files
Source: log_file.ex:10-11 (elixir/lib/symphony_elixir/…)
Log files automatically rotate when they reach the size limit. Old files are deleted when the maximum file count is reached.

​
Polling Interval

Configure the Linear polling interval to balance responsiveness and API rate limits: 
polling:
  interval_ms: 30000  # Poll every 30 seconds (default)
Source: config.ex:25 (elixir/lib/symphony_elixir/…)

​
Environment Variables

Key environment variables Symphony recognizes:
VariablePurposeRequired
LINEAR_API_KEYLinear API authentication tokenYes (for Linear tracker)
LINEAR_ASSIGNEEFilter issues by assigneeNo
COLUMNSTerminal width for dashboard renderingNo
Source: config.ex:195-209 (elixir/lib/symphony_elixir/…)

​
Validation

Symphony validates configuration on startup: 
# Validation checks performed:
# - Workflow file exists and is readable
# - Tracker kind is supported ("linear" or "memory")
# - Linear API token is present (for linear tracker)
# - Linear project slug is configured
# - Codex command is specified
# - Codex runtime settings are valid
Source: config.ex:364-373 (elixir/lib/symphony_elixir/…)
If configuration validation fails, Symphony will exit with an error message. Fix the configuration and restart.

​
Shutdown Behavior

When Symphony shuts down:
  1. The supervisor receives shutdown signal
  2. All running agent processes are monitored
  3. Graceful shutdown waits for agents to complete
  4. Log handlers are flushed and closed
  5. HTTP server (if enabled) closes connections
Source: cli.ex:172-189 (elixir/lib/symphony_elixir/…)

Build docs developers (and LLMs) love

Get started for freeTalk to us