IPC Protocol
Overview
hyprmoncfgd exposes a newline-delimited JSON protocol on:
$XDG_RUNTIME_DIR/hyprmoncfgd.sock
The socket is mode 0600. Protocol version 1 is designed for the bundled TUI and CLI as well as local desktop integrations such as an Omarchy bar panel.
When the socket exists, the daemon is the canonical writer. Clients should not edit profiles or the active generated monitor file alongside it. The bundled TUI and CLI fall back to the same core engine only when no daemon owns the session writer lock.
Envelopes
Every message is one JSON object followed by a newline. A request looks like:
{"type":"request","protocol_version":1,"id":"1","method":"status"}
The matching response repeats the client-generated ID:
{"type":"response","protocol_version":1,"id":"1","result":{}}
Errors replace result with an object containing a stable code, a human-readable message, and optional data.
Methods
| Method | Parameters | Result |
|---|---|---|
status |
none | Status document |
subscribe |
none | Current status document, followed by status events |
editor_state |
none | Editable live profile, supported modes, and source-profile metadata |
edit_profile |
full profile and one edit operation |
Updated profile draft |
scale_info |
width, height (a mode) and scale |
Scale row and sharpness for that mode and scale |
preview |
profile_name or a full profile; optional timeout_seconds and save_on_commit |
Transaction |
confirm |
transaction_id |
none |
commit |
transaction_id; save boolean |
none |
revert |
transaction_id |
none |
save |
full profile |
none |
delete |
name |
none |
rename_profile |
name, new_name |
none |
set_profile_auto |
enabled boolean |
none |
set_rotation |
optional locked, reversed, or calibrate booleans |
none |
rename_profile renames a saved profile and its .conf and .lua files, and
the daemon’s active, manual and last-applied references follow it. It applies
nothing and runs no post-apply command. It keeps created_at, updates
updated_at, and treats names that share a file as the same name, so a change
of case works and Work Desk cannot become work-desk beside an existing
Work Desk. It fails when the new name’s files exist, during an interactive
preview, and for the profile the daemon was started with --profile on.
Daemons with this method report daemon.rename_supported: true in the status
document. Hide Rename when it is absent: older daemons answer with an
unknown-method error. The typed Go client checks this.
A transaction contains an opaque id, the effective profile, and an RFC 3339 deadline.
An omitted or nonpositive timeout_seconds uses the 30-second default. Explicit
durations from older clients are still honored. The deadline starts after apply
verification succeeds; the confirmation interval is separate from link readiness.
Safe preview lifecycle
Only one preview can be active at a time. It belongs to the connection that created it. If that connection disappears—for example, because changing the monitor layout rebuilt a screen-bound panel—the preview stays armed until its original deadline. Its transaction metadata remains available as daemon.preview in status, and a replacement client can reclaim it by sending the same transaction ID to confirm, commit, or revert.
daemon.preview.reclaimable is true only after the owning connection disappears.
A subscriber must not present a modal confirmation for another live client’s
preview: observing a transaction ID does not grant ownership. Present controls
for transactions created by your connection, or for a reclaimable transaction.
Treat a missing reclaimable field from an older daemon as false. The daemon’s
deadline remains authoritative after reclamation, and an expired preview cannot
be kept by a late commit.
A preview is reverted when any of these happens:
- the client calls
revert - the deadline expires
- the daemon shuts down
- monitor management is turned off
Rollback restores both the generated monitor rules and any root-config include added or moved by that preview. If the root config was edited in the meantime, rollback reports the conflict and preserves the edited config and its target instead of overwriting those edits or creating a dangling include.
After confirm, the selected profile becomes a session-scoped override for the current connected monitor set. The daemon still owns monitor management, but automatic best-match selection is paused until the hardware set changes, the daemon restarts, or set_profile_auto is called with enabled: true. A late confirm or revert returns the transaction_unavailable error code.
commit completes the same safe preview transaction and can atomically save its effective profile before making the layout permanent. If saving fails, the transaction stays armed and still reverts at its deadline. Compact editors should use save_on_commit: true when creating a draft preview (or commit with save: true) for “keep and save” rather than racing separate confirm and save requests. Keeping that intent in the daemon lets a replacement panel finish the transaction correctly after reconnecting.
Status events
Status includes workspace_plan, an array of {output_key, output_name,
workspaces} groups resolved from the explicit current Hyprland rules using
the same hardware identity matching as the editor. Disabled, modeless, synthetic
and mirrored outputs have no independent group. This is a read-only view of
live rules, not a saved-profile preview or a declaration of workspace ownership.
An absent field means an older daemon. An empty array means a known empty plan. Shell clients merge this with their live compositor workspace model: a workspace’s actual location always wins over its assignment. Switching a workspace remains a direct compositor action; there is no workspace-switching IPC method. The additive field retains protocol/schema version 1 and existing subscriptions.
Monitor summaries add usable and health (usable, off, sleeping,
no_signal, or synthetic). enabled alone is not evidence of a working mode.
Older daemons omit these fields; clients must not interpret absence as failure.
A monitor summary adds fallback when the daemon runs that display below its
saved settings because it would not stay on at them. It has a reason
(dropping: it kept disconnecting right after connecting; no_mode: it kept
coming back without a mode) and running, a plain description such as
without VRR or at 120 Hz without VRR. The saved profile is unchanged, and
confirming or committing any preview clears every fallback. Absent means the
display runs at its saved settings, or the daemon predates the field.
A daemon with orientation support adds rotation to the status document:
available (an accelerometer reports the orientation), orientation
(iio-sensor-proxy’s normal, left-up, bottom-up, right-up or
undefined), quarters (the counterclockwise quarter turns applied now to
built-in panels that rotate automatically), locked, reversed (the sensor’s
turns are applied the other way, for a device whose accelerometer reports the
opposite direction), and on a convertible tablet_mode and paused (folded
as a laptop, so panels stay upright). Absent rotation means the daemon
predates it; clients then offer neither automatic rotation nor the lock.
set_rotation changes only the fields it is given: locked holds or releases
the current turn, reversed sets the direction. Both persist across daemon
restarts. calibrate: true records the current sensor orientation as upright
and unlocks rotation, without editing profiles. It cannot be combined with other
rotation edits and fails during an interactive preview or without a valid sensor
orientation. Status advertises calibration_supported: true and sensor_upright
(the raw quarter-turn reading used as zero). Clients must check that capability
before sending calibration: old servers ignore unknown fields. The typed Go
client performs this check. Missing calibration fields retain the original zero
baseline. Direction reversal applies after subtracting the sensor baseline.
sensor_claim_pending: true with available: false means iio-sensor-proxy is
running but has refused the claim, which polkit does until the session is
active. The daemon keeps retrying, so clients should say so rather than suggest
installing a sensor service.
rotation_upright holds a sideways upright rotation while a panel set to
Normal is away from Auto; clients leave it alone.
A profile output with rotation_auto: true turns with the device; its
transform is the rotation it has when the device is upright. Profiles,
drafts, editor_state and edit_profile always describe that upright
layout, and the daemon turns it on apply, including previews, moving attached
displays as a resize would. Sensor-driven changes pause until the preview ends.
Monitor summaries keep reporting the live
transform. Editor displays add rotation_auto_supported, true only for a
built-in panel when a sensor is available; only then may an editor offer the
rotation_auto edit, which the daemon refuses for any other display. Older
clients that don’t know the field drop it when they save, so upgrade both
clients together.
Editor documents list vrr_modes, the VRR values edit_profile accepts (-1
follows the global misc:vrr, 0 off, 1 on, 2 fullscreen, 3 fullscreen
games and video). An editor offers only these; when the field is missing the
daemon accepts 0, 1 and 2.
Editor documents add workspace_persistence_supported. Only when true may an
editor offer workspaces.persist_all. Missing capability means unavailable, not
false user intent. The typed client rejects sending this setting to older
daemons rather than silently losing it. Older clients retain their existing
first-per-display default; upgrade both clients before editing profiles that use
the new policy, since old clients cannot preserve an unknown field.
After subscribe, the daemon pushes a fresh status document whenever monitor or profile state changes:
{"type":"event","protocol_version":1,"event":"status","data":{}}
The document schema is versioned independently with schema_version. daemon.profile_override names the session-scoped manual profile for the current monitor set; when it is absent, profile choice is automatic. While an interactive change is awaiting confirmation, daemon.preview contains its transaction_id, profile_name, deadline, full effective profile, and optional save_on_commit intent. The profile lets a screen-bound integration reconstruct the target layout after the monitor change replaces its process or panel. Each profile summary includes connected_outputs, connected_enabled_outputs, exact_display_match, match_score, and a match_reasons breakdown with the count and score contribution for each connection state. With the lid closed and an external connected, built-in panels appear as lid_closed_kept_off (+100 each) or lid_closed_on (+50 each) instead of connected_kept_off or connected. Older clients that don’t know a kind should still show its count and points. exact_display_match is true when the profile accounts for every connected display and has no saved display missing; a connected display deliberately kept off still counts as part of that setup. Integrations should only offer a profile for manual selection when connected_enabled_outputs is greater than zero. This guarantees that applying the profile leaves at least one currently connected output enabled. The two connection counts let a browser distinguish all available saved outputs from the subset the profile enables.
Monitor summaries include the connector, make, model, serial, output key, hardware match_key, active mode, physical and logical dimensions, position, scale, transform, internal/focused flags, and enabled state. Integrations can therefore render the same monitor identity and layout information as the TUI without querying Hyprland separately. hyprmoncfg status --json prints the same shape without requiring clients to speak the socket protocol.
editor_state is intentionally fetched on demand rather than included in every status event. Its profile is the live display and workspace state in the same shape accepted by preview and save; profiles contains the complete saved profiles for profile browsers. workspace_plan contains the resolved workspace assignments for the editable live profile, while profile_workspace_plans maps every saved profile name to its resolved assignments so read-only browsers can preview the same plan without reimplementing workspace strategies. displays adds supported modes, focus, DPMS, active workspace, internal/external type, and physical panel size for each connected output. source_profile is present only when the live state exactly matches one saved profile. Settings that Hyprland cannot report back reliably, such as ICC and HDR luminance overrides, are preserved from that profile or from the best hardware match so an editor does not erase advanced configuration it never displayed.
edit_profile applies one typed edit to a client-owned draft. Display mode, scale, VRR, transform, mirroring, position, enablement, color/HDR/ICC settings, and workspace settings are normalized and validated by the same profile geometry used by the bundled TUI. Resize edits move only displays attached to the resized display: its row beyond the old right edge, its column beyond the old bottom edge, displays on its corners, displays continuing those rows and columns, and any display a moving one would land on. Being stacked above or below a moving display in another row does not by itself move a display, and mirrors and modeless outputs never move; dragged position edits can request edge snapping with snap_distance, and every remaining collision is placed on the nearest clear outside edge. This also applies to enablement, typed positions, nudges, unmirroring, and resize edits. The edited display moves first, preserving unaffected displays; pre-existing collisions are cleared too. Disabled, mirrored, and modeless outputs occupy no independent area. The request and response schema is unchanged: existing panels consume the returned reflowed profile without frontend changes. Older daemons retain overlap rejection until upgraded. The method is stateless and does not touch the live displays until the returned profile is sent to preview.
scale_info describes one scale on one mode, so an editor never computes
sharpness itself. It is stateless and needs no displays. The result carries
presets (the Scale row’s pills for that mode), options (every sharp scale
from 1 to 4, plus the sharp scale closest to scale when that is outside the
list), scale as a profile stores it, sharp, logical (the logical width
and height; whole pixels when sharp), and apply, the scale typed entry
applies. A blurry scale also carries closest and closest_logical when a
sharp scale exists for the mode. A scale outside 0.25 to 4 is an error
(scale must be between 0.25 and 4), and so is a missing mode. Clients label
a scale that is not sharp Blurry. For example:
{"scale": 1.33, "sharp": false, "logical": [2887.22, 1624.06],
"closest": 1.33333, "closest_logical": [2880, 1620], "apply": 1.33333,
"presets": [1, 1.25, 1.5, 1.6, 2, 3], "options": [1, 1.06667, 1.2, "..."]}
An edit_profile scale edit may add snap_scale: true: the daemon then
stores the closest sharp scale instead of a blurry typed one, judged on the
output’s mode after any mode in the same edit. This is how typed entry
applies a scale in both editors.
Daemons older than scale_info answer it with an unknown IPC method error
and ignore snap_scale. The typed Go client refuses to send snap_scale to
such a daemon instead of letting it store a blurry scale. The Omarchy panel
treats the unknown-method reply as missing support: it shows no preset pills,
no ⚠ Blurry marker and no Custom… entry, and its More list falls back to the
editor display’s scale_options (the sharp list for the live mode), so it
never shows a sharpness verdict it did not get from Go. Editor displays
keep scale_options for those clients.
Connecting displays and query timeouts
Monitor and workspace-rule reads have a 750 ms deadline per query by default. A slow compositor or blocked DRM identity probe returns error.code = "compositor_busy" with a human-readable connecting message. No stale or partially enriched hardware snapshot is substituted for a successful response.
Status and editor-state responses include an additive monitor_set_hash. Treat it as an opaque equality token for the output keys and their current connector bindings; it includes the connector paths used to distinguish otherwise identical outputs. It excludes layout, focus and power state. These daemon reads check hardware before and after reading workspace rules and return compositor_busy if the bindings changed. They therefore perform two monitor queries and one workspace-rule query; the 750 ms limit is per query, not a total response-time guarantee.
Clients should retain the last visible snapshot while connecting, show the message, and retry while visible with at most one request in flight. Do not treat a failed refresh as an empty display list. Compare editor hashes with the latest status hash when both are present, and discard mismatches. Also track observed topology changes locally and reject requests from an older generation, including a change away and back to the same hardware. The hash is not an event counter or an atomic snapshot guarantee. Older daemons omit it; clients can fall back to their available identity/signature fields. Stateless edit_profile replies do not include a fresh hardware hash. Known-profile apply and rollback retain their existing serialized lifecycle.
Enabling a sleeping output
Preview apply wakes connected outputs that transition from disabled to enabled, using a targeted DPMS request and at most three attempts within the existing apply verification window. Confirmation starts only after those outputs report awake. Failure follows normal apply rollback, including restoring the previous disabled state. Already-enabled sleeping outputs are not woken by unrelated edits. The wire schema is unchanged; existing panel clients receive the existing preview success or apply error response. Older backends do not perform this wake check.