Concepts
Monitor identity
Section titled “Monitor identity”The whole point of Panes is that a monitor keeps the same identity even when the OS renumbers
it. Instead of trusting \\.\DISPLAY1, Panes matches each physical panel by a layered
fingerprint and scores candidates rather than requiring an exact match:
- Hardware (EDID) — manufacturer, product code, and serial. Survives re-cabling, port changes, and GPU-driver reinstalls. This is the strongest signal.
- Topology — the Windows device-instance ID (including the
UID####GPU-port) or the Linux connector (card0-HDMI-A-1). Survives reboots but not a cable swap. - Last resort — friendly name and native resolution.
A stored monitor is re-matched only if a candidate scores high enough and is unique. If two panels are genuinely indistinguishable (e.g. two identical monitors with blank serials), the match is ambiguous and Panes asks you to disambiguate with Identify rather than guessing.
Identify displays
Section titled “Identify displays”Identify flashes a large 1-based number on each connected screen for a few seconds, and shows the same number on the matching card in the UI. It’s the escape hatch for telling two hardware-identical panels apart, and it surfaces automatically when identity is ambiguous.
Commands
Section titled “Commands”A command is one thing to launch on one monitor. A monitor can have several (e.g. a left-half browser and a right-half app). Each command carries a preset, an executable/URL, arguments, a placement, and the startup/watchdog toggles. Full field reference: Commands.
Commands run in launch order (their ordinal). A command can be disabled — it’s kept but never launched or watched.
Process states
Section titled “Process states”Each command reports a live state:
| State | Meaning |
|---|---|
| Stopped | Not running. |
| Starting | Launch in progress. |
| Running | Up and placed. |
| Waiting for monitor | Its monitor isn’t currently connected. |
| Crash-looping | Exited too many times too fast; Panes stopped restarting it. |
| Failed | Could not launch. |
The watchdog
Section titled “The watchdog”When Restart if it exits is on, Panes supervises each launched process (checked every couple of seconds):
- If it exits, Panes restarts it.
- If it exits more than the “max restarts” limit within ~60 seconds, it’s marked crash-looping and Panes stops hammering it — it waits for a human. Pressing Run clears the counter.
When the agent shuts down, it kills every process it launched, so kiosk browsers go down with it and leave no orphans.
Apply & reconcile
Section titled “Apply & reconcile”Apply now reconciles the stored configuration against what’s actually running: it launches anything enabled and set to start that isn’t running, and re-places windows that have drifted to the wrong screen.
Reconcile also runs automatically:
- On boot — the logon task (Windows) or systemd-user / autostart (Linux) starts the agent, which detects monitors and applies the desired layout.
- On a display change — when a monitor is connected or disconnected, Panes re-detects (debounced) and reconciles. A running app whose monitor just returned is re-placed, not restarted; a command whose monitor is absent sits in Waiting for monitor.