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

> Master Hyprland hot-desking: Automatically assign workspaces to monitors with simple workspace rules. Effortlessly manage your setup as monitors connect or disconnect.

- Repository: [Hypr Development/Hyprland](https://github.com/hyprwm/Hyprland)
- Tags: how-to-guide
- Published: 2026-07-26

---

**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`](https://github.com/hyprwm/Hyprland/blob/main/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:

```ini
workspace = [ID] monitor:[NAME]

```

### Static Monitor Binding

Bind specific workspaces to named outputs for predictable placement:

```ini

# 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:

```ini

# 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:

```ini
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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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:

```bash

# 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`](https://github.com/hyprwm/Hyprland/blob/main/src/config/shared/workspace/WorkspaceRuleManager.hpp) parses and stores monitor bindings during startup.
- `CWorkspaceStateTracker` in [`src/state/WorkspaceState.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/state/WorkspaceState.cpp) persists these mappings and applies them when hardware changes occur.
- Monitor connection events in [`src/output/Monitor.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/hyprland.conf).