Develop
Test your app in a box, and Hyprland itself.
For app developers whose agents need to see their work, and for people changing Hyprland or writing plugins for it. Omarchy plugins and themes have their own page.
Monitors
Every desk you don't have.
A box can have as many monitors as a test needs, each with its own size, scale and place, and a bar on each: a portrait screen beside an ultrawide, mixed scales, a laptop with a monitor plugged in. Add and unplug them while the box runs, and see what your app does.
omabox shot.Monitors
Any size, scale and place
Each monitor goes right of or below the one before, or at the place you give it. remove is an
unplug: its workspaces move to the others. shot takes the whole layout or one monitor,
peek --monitor watches one, and clicks and waits work across all of them.
$ omabox up --monitor 1080x1920 --monitor 2560x1440,scale=1.6,below $ omabox monitor add 1366x768 $ omabox monitor remove HEADLESS-3 # an unplug $ omabox shot --monitor HEADLESS-4
When a monitor drops off
Find the crash before your users do
A monitor that sleeps, a KVM switch, a dock: output drop takes a screen away and brings it back under
its own name, and your shell and apps rebuild what they drew there. --cycles repeats it until
something crashes; it found a real crash in a shell plugin. omabox ls shows a shell that crashed, and
gdb prints the backtrace of a Hyprland or shell that hung.
$ omabox output drop --for 300ms --cycles 20 $ omabox gdb --shell
A box the agent drives is headless: every monitor at full size. In a box you drive
(up --interactive), each monitor is a window on your desktop, the whole layout scaled down to fit, so its
text is small. Your pointer and cursor go from one window to the next with omabox's own build of aquamarine
(omabox setup --aquamarine).
Visual checks
Visual checks, without looking at every screen.
Write a scenario: a script that drives the box and calls omabox check point ID where a shot
should match. check run --approve runs it three times in a clean box and keeps what most runs agree on.
From then on, check run says same or changed for each checkpoint. Each changed region is marked, and for an
app with an accessibility tree it names the element (moved +0,+6 button "Save"). One report image shows
every change, the baseline beside the new shot.
# visual.sh, the scenario
omabox run -d --wait -- ./build/app
omabox check point main
omabox click --window app 640 360
omabox check point settings
$ omabox check run --approve -- ./visual.sh # the baseline, from three runs $ omabox check run -- ./visual.sh # same or changed, each checkpoint $ omabox check run --json -- ./visual.sh # for CI

- Small changes caught. A 2 px spacing change is caught, and so is a colour a few levels off.
- Noise left out, and said. What the approve runs disagreed on is left out and said.
- Holes fail. The wallpaper showing through a window fails a check.
- For CI.
--json, and exit 4 when there is no baseline.
Accessibility trees
Text instead of a shot.
omabox tree reads a window's accessibility tree: each control's role, name, text, value and state, with
bounds a click takes. tree --find 'dark mode' prints the one line that answers the question. For GTK and
Qt apps, Chromium or Electron with accessibility on, and egui apps on eframe 0.37+. tree --layer reads a
shell's panel.
$ omabox tree --window app $ omabox tree --window app --find 'dark mode'
tokens, to read whether dark mode is on
tokens, the one line that says
omabox calibrate tells an agent whether its model needs --fit to click right, for
any model and harness.
Video and sound
Videos people can follow.
omabox record films a box, one monitor or all of them at once. --show-input draws in the
clicks and keys, --captions puts your marks on screen, --cut-idle cuts the still stretches,
and --glide makes the pointer travel instead of jump. record stop --sheet makes a contact
sheet, so an agent can check a take without watching it. With up --audio, the sound goes in the video.
It plays to a speaker nobody hears, never yours.
$ omabox up --audio $ omabox record start -o take.mp4 --monitor all --audio --glide 300ms $ omabox record mark "Open the settings" $ omabox record stop --sheet --show-input --captions --cut-idle
omabox audio 3s says whether the box made a sound in three seconds, when and how loud: a notification
sound checked without hearing it.
$ omabox audio 3sApps
Rebuild, restart, look.
Apps
A new build in one step
run -d --replace stops the copy it started before and launches the new build in one step, then waits
until it has drawn. Its output, Qt warnings and QML errors included, goes to a log.
$ omabox run -d --replace --wait -- ./build/app $ omabox log run
Saves
Sign in once, every box starts signed in
An app that needs an account, a PIN or a library: set it up in a box once and save its HOME, keyring included. New boxes start from the save. Close the app first for a clean save.
$ omabox save signed-in $ omabox up --from signed-in $ omabox run --from signed-in -- ctest --test-dir build
What you tested
The box says what it ran
omabox ls --json records each box's Omarchy version, its theme, and each mounted plugin's git commit,
with +dirty when there were uncommitted changes. A screenshot in a pull request can say exactly what it
shows.
$ omabox ls --jsonServices and alarms
A systemd user manager, if it needs one
For apps that manage a service or schedule alarms: --systemd gives the box a real systemd user manager.
Without it, a box has none.
$ omabox up --systemdAnd
keys down:KEY/up:KEYhold a key across commands, for a bind on release.omabox log journal: a box has its own journal sockets, so programs that log only there work.omabox cpu --threads: a Qt Quick app's main thread apart from its render thread.- Your fonts are in every box, so shots don't fall back silently.
Hyprland
Hyprland and compositor work.
A Hyprland change
Your build, never installed
The box runs your Hyprland build instead of the installed one. Start a stock box beside it to compare.
ls and windows name the build, so a box on it is never taken for a stock one.
$ omabox up patched --hyprland ~/code/Hyprland/build/Hyprland $ omabox up stock
Inside it
Lua, events and a backtrace
lua runs Lua in the box's Hyprland and prints what it returns. events marks a point and
reads what Hyprland reported after it. gdb prints every thread's backtrace of a Hyprland that hung.
$ omabox lua 'hl.get_active_window()' $ omabox events --mark m1 $ omabox events --since m1 --until 'openwindow>>' --timeout 5s $ omabox gdb
Plain Hyprland boxes, for Hyprland plugin and compositor developers on any distro, are coming. What's coming →
Limits
What a box can't test.
A box runs the compositor's logic for real: layouts, focus, input routing, the Lua config, IPC and protocols. Test these on a real machine:
- Real monitors: their modes, HDR and VRR, a real hotplug. A box's monitors are virtual.
- Several GPUs at once, real input devices, real sound devices, the system bus and suspend.
- The lock screen runs, but takes no real password.
- wgpu apps (eframe's default renderer, iced, Bevy) don't start in a box on NVIDIA: use a GL renderer, or a box on the AMD or Intel GPU.
- A box turns PipeWire's realtime module off for its clients.
A box is not a security boundary: for code you don't trust, use ai-jail.
Give every agent a desktop of its own.
git clone https://github.com/diogochaves/omabox && cd omabox && ./install.shToday on Omarchy 4 · Hyprland 0.56+ · AMD, Intel or NVIDIA · MIT