Symphony

Symphony is the Matrix coding-agent operator for Linear work. On each customer VPS it runs as matrix-symphony.service, owned by the matrix user with MATRIX_HOME=/home/matrix/home.

The service is an adapted Elixir runtime. It polls eligible Linear issues, creates Matrix-owned workspaces, starts agents through codex app-server, and exposes loopback state to the Matrix gateway. The browser never talks to the Elixir service directly.

Linear Access

Connect Linear from Matrix settings or the Integrations app. Symphony uses that Matrix-owned connection through the platform integration bridge.

You do not need to put LINEAR_API_KEY on the VPS. The Elixir runtime defaults to the Matrix credential bridge, which calls the platform internal integrations route using the VPS internal token. The UI only receives coarse setup or availability status, not provider tokens or raw provider errors.

For local development, an explicit SYMPHONY_LINEAR_API_KEY or SYMPHONY_LINEAR_CREDENTIAL can still override the bridge.

Runtime Paths

Symphony workspaces live under the owner home:

/home/matrix/home/projects/matrix-os/symphony-workspaces/<issue>

Runtime logs live under:

/home/matrix/home/system/symphony/logs

Updates replace /opt/matrix/app only. They must not overwrite owner data under /home/matrix/home.

Matrix App

Open Symphony from Matrix to see the Elixir runtime state. The app shows:

• Queue, Running, Needs Attention, and Done/Handoff groups
• active issue identifier
• Codex app-server session ID and turn count
• latest event and message
• workspace path
• workpad link when available
• recent logs

Use Refresh to ask the Elixir runtime to poll and reconcile now. Use Stop to terminate the active issue session through the gateway proxy.

Service Operations

The host bundle installs and starts:

systemctl status matrix-symphony.service
journalctl -u matrix-symphony.service -f

The service binds to 127.0.0.1:4766. Matrix gateway proxies authenticated requests from /api/symphony/* to that loopback API with validation, body limits, timeouts, and generic error mapping.

Migration Notes

The old in-gateway TypeScript Symphony runner is no longer the runtime source of truth for the Matrix app. Gateway routes now proxy the Elixir service instead of maintaining a separate run table. Existing docs or workflows that mention manual Symphony API-key setup should be moved to Matrix Integrations.