GitHubInstall

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.

Plugins and themes for OmarchyYour bar in a box, your theme live, a clean Omarchy for checks, Omarchy's own checkout, the bar widget.omabox on Omarchy →

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.

one box · three monitors
One box with three monitors, each with its own bar: the app menu open on a 1920x1080 screen, Neovim on a 2560x1440 screen at scale 1.6 below it, and a portrait screen beside them listing the three monitors
1920x1080, a 2560x1440 at scale 1.6 below it and a portrait 1080x1920 beside them. Taken in the box with 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
report.png
A real omabox check report: 1 of 1 changed; the tree line says button "Save" moved +0,+6; the baseline crop beside this run's, the Save button lower in the second, the region in red brackets
A real report, from a box: a GTK window whose Save button moved 6 px down, the baseline beside the new run.

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'
A shot~1.5k

tokens, to read whether dark mode is on

tree --find~17

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 3s

Apps

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 --json

Services 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 --systemd

And

  • keys down:KEY / up:KEY hold 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.sh

Today on Omarchy 4 · Hyprland 0.56+ · AMD, Intel or NVIDIA · MIT

What's comingPlain Hyprland boxes · Your own shell · Your own Hyprland desktop, in a box →