Hyprland Hot-Desking Configuration: Automatic Workspace-to-Monitor Assignment

Hyprland hot-desking configuration binds workspaces to specific monitors using workspace rules, automatically moving workspaces when monitors are connected or disconnected.

The hyprwm/Hyprland Wayland compositor implements hot-desking through dynamic workspace-to-monitor assignment, allowing workspaces to follow displays as they appear or disappear. This feature eliminates manual workspace management when switching between laptop screens, docking stations, and external monitors. The implementation relies on the Workspace Rule Manager and the CWorkspaceStateTracker class to persist and apply monitor bindings across hardware changes.

How Hot-Desking Works in Hyprland

Hyprland treats each physical output as a hot-desk. When you configure a workspace rule, the compositor stores a persistent mapping between a workspace ID and a monitor identifier. According to the hyprwm/Hyprland source code, the WorkspaceRuleManager parses these bindings during configuration loading and stores them in an internal map.

When a monitor connects, the onMonitorAdded function in src/output/Monitor.cpp queries the CWorkspaceStateTracker via rememberedWorkspaceForMonitor(). If a workspace is bound to that monitor, the compositor immediately moves the workspace to the new output. Conversely, when onMonitorRemoved triggers, the workspace becomes unassigned or migrates to a fallback monitor based on your configuration rules.

Configuration Syntax for Workspace Monitor Binding

The configuration uses simple key-value pairs in ~/.config/hypr/hyprland.conf. The general syntax follows:

workspace = [ID] monitor:[NAME]

Static Monitor Binding

Bind specific workspaces to named outputs for predictable placement:

# Bind workspace 1 to the monitor named DP-1

workspace = 1 monitor:DP-1

# Bind workspace 2 to HDMI-A-1

workspace = 2 monitor:HDMI-A-1

Dynamic Fallback Assignment

Use the wildcard * to assign workspaces to the first available monitor:

# Workspace 3 appears on whichever monitor is connected first

workspace = 3 monitor:*

Multiple Workspaces per Monitor

Assign several workspaces to a single output for dedicated screen roles:

workspace = scratchpad monitor:DP-1
workspace = term       monitor:DP-1
workspace = browser    monitor:DP-1

Source Code Implementation

The hot-desking behavior is implemented across four core components that handle parsing, storage, and event reaction.

Workspace Rule Parsing

The WorkspaceRuleManager class defined in src/config/shared/workspace/WorkspaceRuleManager.hpp processes configuration entries. It exposes getBoundMonitorForWS() to retrieve monitor assignments and getAllWorkspaceRules() for bulk operations. During initialization, this manager builds a lookup table mapping workspace IDs to monitor identifiers.

Monitor Event Handling

Physical display changes trigger the hot-desking logic in src/output/Monitor.cpp. The onMonitorAdded() function executes when the kernel detects a new display, while onMonitorRemoved() handles disconnections. These methods interface with the workspace state tracker to enforce the rules defined in your configuration.

State Tracking

The CWorkspaceStateTracker class in src/state/WorkspaceState.cpp maintains the runtime mapping. The create() method initializes the tracker by querying Config::workspaceRuleMgr(), while rememberWorkspaceForMonitor() stores bindings persistently. When monitors change, the tracker ensures workspaces migrate according to the stored rules rather than defaulting to arbitrary assignments.

Query Utilities

Helper functions in src/state/WorkspaceQueryCore.hpp support workspace validation and ID generation through newSpecialID() and nextAvailableNamedWorkspace(), ensuring that dynamically created workspaces respect the same monitor binding rules as static ones.

Runtime Modifications

You can override workspace bindings temporarily without editing configuration files using the Hyprland IPC:

# Move workspace 5 to DP-2 immediately

hyprctl keyword workspace:5 monitor:DP-2

This command updates the runtime state but does not persist after restart, making it ideal for temporary display arrangements.

Summary

• Hyprland hot-desking configuration uses workspace rules to bind specific workspaces to specific monitors or wildcard fallbacks.
• The WorkspaceRuleManager in src/config/shared/workspace/WorkspaceRuleManager.hpp parses and stores monitor bindings during startup.
• CWorkspaceStateTracker in src/state/WorkspaceState.cpp persists these mappings and applies them when hardware changes occur.
• Monitor connection events in src/output/Monitor.cpp trigger automatic workspace migration via onMonitorAdded() and onMonitorRemoved().
• Use hyprctl keyword to modify bindings at runtime without restarting the compositor.

Frequently Asked Questions

What is hot-desking in Hyprland?

Hot-desking in Hyprland refers to the automatic reassignment of workspaces to monitors as physical displays are connected or disconnected. The compositor maintains persistent workspace-to-monitor bindings, allowing your window layout to follow displays when you switch between laptop mode and docking stations.

How do I bind a workspace to a specific monitor?

Add a workspace rule to your hyprland.conf file using the syntax workspace = [ID] monitor:[NAME]. For example, workspace = 1 monitor:DP-1 binds workspace 1 to the display named DP-1. You can identify monitor names by running hyprctl monitors in your terminal.

What happens when I unplug a monitor?

When a monitor disconnects, Hyprland executes onMonitorRemoved() in src/output/Monitor.cpp, which detaches the bound workspace from that output. The workspace becomes unassigned or moves to a fallback monitor if configured with monitor:*. When you plug the monitor back in, onMonitorAdded() automatically returns the workspace to its original display.

Can I change workspace bindings without restarting Hyprland?

Yes, use the hyprctl keyword command to modify workspace monitor assignments at runtime. For example, hyprctl keyword workspace:3 monitor:HDMI-A-1 moves workspace 3 to HDMI-A-1 immediately. These changes are volatile and will reset to configuration file values upon the next Hyprland restart unless you persist them in hyprland.conf.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}