# Develop with omabox: apps, plugins, themes, Hyprland

This is https://omabox.app/develop as Markdown, for agents. Every page: https://omabox.app/llms.txt

**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](https://omabox.app/omarchy).

[**Plugins and themes for Omarchy** · Your bar in a box, your theme live, a clean Omarchy for checks, Omarchy's own checkout, the bar widget. · omabox on Omarchy →](https://omabox.app/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 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](https://omabox.app/media/monitors.webp)

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

![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](https://omabox.app/media/check-report.webp)

A real report, from a box: a GTK window whose Save button moved 6 px down, the baseline beside the new run.

- **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'
```

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 →](https://omabox.app/next)

## 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](https://omabox.app/compare).
