Develop

Build for Omarchy in a box, not on your desktop.

For people writing shell plugins, themes and apps for Omarchy, and for people changing Hyprland or Omarchy itself. You, or the agent you work with, test on a real Omarchy desktop that isn't the one you are using.

Plugins, themes and apps

Shell plugins

Your plugin in a bar that isn't yours

The plugin is mounted read-only and turned on where its manifest says. The box's bar has the built-in widgets plus the plugins you mount, nothing else, so your own bar never changes while you work.

$ omabox up --plugin ~/code/myplugin
$ omabox restart-shell   # after each edit

When it doesn't show

It says why a plugin isn't in the bar

When the shell doesn't load a plugin (a manifest it refuses, a QML error), up and restart-shell print why, with Omarchy's plugin validator's message when it has one. The box comes up anyway, and omabox log shell has the rest.

$ omabox log shell --grep qml -n 20

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

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, with your Omarchy look on top. 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

Apps

Rebuild, restart, look

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

Themes and how it looks

The stock bar, a theme switch, any screen

--stock-bar shows your plugin in Omarchy's default bar, as most people will see it. Switch themes and change the screen size without touching your own desktop.

$ omabox up --stock-bar --size 1366x768
$ omabox run -- omarchy-theme-set gruvbox

Services and alarms

A systemd user manager, if it needs one

For plugins 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 --plugin ~/code/myplugin

With an agent

Steps written for your desktop, done in a box

Your project's instructions say "link the plugin into ~/.config/omarchy/plugins", "edit shell.json", "run omarchy plugin add". The omabox skill has the agent do each of them in its box instead, where the guard can't help: those are file writes, and your bar would change at once.

Hyprland and Omarchy themselves

A Hyprland change

Your build, never installed

The box runs your Hyprland build instead of the installed one, with the Omarchy shell and your bar as usual. 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

An Omarchy change

Your checkout, as `omarchy dev link` would, without touching your system

The box runs that tree's Hyprland config, shell and bin/. An edit shows after restart-shell (the shell) or hyprctl reload (the config). The skill has a recipe for reviewing an Omarchy pull request: two boxes, the change and its base.

$ omabox up dev --omarchy ~/src/omarchy
$ omabox hyprctl reload

A box runs the compositor's logic for real: layouts, focus, input routing, the Lua config, IPC and protocols. It has no hardware, so real monitors, HDR and VRR, several GPUs, real input devices, audio, the system bus, suspend and lock never run in one: test those on a real machine. For the installer, system services or a reboot, omarchy-in-omarchy gives you a whole one in a VM. A box is also not a security boundary: for code you don't trust, use ai-jail.