Experimental fork of Hyprland for compositor-native computer use.An AI agent can create a visible, temporary nested desktop on a chosen workspace, launch applications, see its pixels, and control its own pointer and keyboard while the human keeps control of the host desktop.
ChatGPT was used during the initial planning phase to turn the Agent Realms idea into a first milestone plan. That plan was then pasted into Codex. Codex inspected the Hyprland codebase, expanded the work into the 13 implementation milestones documented below, and helped implement the compositor, controller, MCP adapter, tests, documentation, and follow-up fixes.
The development loop was deliberately transparent: each capability was built as a small commit, tested before moving forward, and then exercised on the live fork under human supervision. The commit history shows the path from the first nested-compositor proof to reliable browser computer use; follow-up commits record the bugs found through real use rather than hiding them in a single generated patch.
An agent gets a visible Hyprland work surface—not your host desktop—where it can open apps, see, click, type, and work. You can watch it, take over, it, or stop it at any time.
This is not a VM. A realm is a compositor-managed nested Hyprland instance with its own Wayland display, application process group, virtual input devices, cursor, capture stream, lifecycle, and host window. The current prototype isolates the agent's display and input target; stronger filesystem, network, secret, and process isolation is future work.
Most computer-use agents either control the person's real desktop, where agent input can collide with human input, or run in a remote browser/VM that is detached from the local desktop experience. Desktop environments were designed around one human input stream and have no first-class place for several visible software operators.
Hypr Realm moves the computer-use boundary into the compositor. Each task gets its own visible work surface and coordinate space. The agent can operate there while the human works elsewhere, and two agents can work in separate realms on different workspaces without sharing pointer focus or keyboard state.
Codex / any MCP client
│ typed computer-use tools over stdio
▼
hyprland-realm-mcp-server
│ framed JSON + shared-memory frame descriptors
▼
Host Hyprland ── private, same-user .realm.sock
├── RealmManager lifecycle and process supervision
├── RealmWindowManager workspace placement and visible controls
├── RealmControlServer bounded commands and capability checks
└── RealmInputController capture + virtual pointer/keyboard
│
├── Realm A: nested Hyprland → Brave, terminal, editor…
└── Realm B: nested Hyprland → another independent task…
The default MCP adapter is a dynamic orchestrator. An agent can:
- create one realm or up to eight realms in one request;
- place each realm window on a numeric Hyprland workspace;
- launch validated application executables without a shell;
- capture a realm at its native dimensions without capturing the host monitor;
- point and click atomically, scroll, type text, and press named shortcuts;
- observe the distinct realm cursor and wait for visual changes;
- , resume, inspect, and clean up a temporary realm.
Input calls are acknowledged only after the nested compositor has processed them. Computer use follows an observe → act → observe loop, with per-realm capture and coordinate state so parallel tasks do not become mixed together. The realm window exposes Take Over, ****, and Stop controls that are owned by the host compositor, not the agent.
A prompt can therefore be as direct as:
Create a temporary realm on workspace 5, open Brave, find the first result for “Messi epic skills,” and clean up the realm when finished.
Computer use should be a desktop primitive, not a pile of global screenshots and synthetic input aimed at the user's only session. The compositor already knows which pixels belong to a surface, where input is routed, which workspace contains it, and when a window is visible. Making agent work surfaces a native compositor concept enables local, observable, parallel automation with a clear human control point.
Hypr Realm is a capability demo of that architectural direction: agents become visible participants in the desktop rather than invisible processes fighting the user for the same cursor. The longer-term path is to combine this compositor boundary with enforceable OS-level filesystem, network, secret, and resource policies.
Hypr Realm is experimental and does not yet claim hostile same-user tenant isolation. Applications in a realm currently run as the desktop user and may inherit the user's normal home directory, network access, and application profiles. Clipboard, filesystem, network, secrets, cgroups, and namespace fields are not presented as enforced protections until their corresponding isolation mechanisms exist. Realms are currently Wayland-only; X11-only applications are not supported inside them.
What is enforced today is the computer-use boundary: realm capture does not capture the host monitor, virtual input is addressed to the nested Wayland display, human and agent input ownership are exclusive, process lifecycle is supervised, control traffic is bounded, and the private control socket verifies same-user ownership and peer credentials.
The original ChatGPT plan covered the foundational vertical slice. Codex expanded it as implementation and live testing exposed the production and UX work needed to make the idea demonstrable end to end:
| Milestone | Result |
|---|---|
administration, inspection, errors, and lifecycle events.45678910111213See the computer-use contract for the MCP observe-act-observe workflow and completion semantics. The agent-realms commit history is the detailed engineering record.
Hyprland is a 100% independent, dynamic tiling Wayland compositor that doesn't sacrifice on its looks.
It provides the latest Wayland features, is highly customizable, has all the eyecandy, the most powerful plugins, easy IPC, much more QoL stuff than other compositors and more...
Install
Quick Start
Quick Start
Configure
Configure
Contribute
Contribute
- All of the eyecandy: gradient borders, blur, animations, shadows and much more
- A lot of customization
- 100% independent, no wlroots, no libweston, no kwin, no mutter.
- Custom bezier curves for the best animations
- Powerful plugin support
- Built-in plugin manager
- Tearing support for better gaming performance
- Easily expandable and readable codebase
- Fast and active development
- Not afraid to provide bleeding-edge features
- Config reloaded instantly upon saving
- Fully dynamic workspaces
- Two built-in layouts and more available as plugins
- Global keybinds passed to your apps of choice
- Tiling/pseudotiling/floating/fullscreen windows
- Special workspaces (scratchpads)
- Window groups (tabbed mode)
- Powerful window/monitor/layer rules
- Socket-based IPC
- Native IME and Input Panels Support
- and much more...
** wlroots** -
For powering Hyprland in the past
** tinywl** -
For showing how 2 do stuff
** Sway** -
For showing how 2 do stuff the overkill way
** Vivarium** -
For showing how 2 do stuff the simple way
** dwl** -
For showing how 2 do stuff the hacky way
** Wayfire** -
For showing how 2 do some graphics stuff