Install
Three minutes, then your agents take it from there.
omabox installs from its git repository, into your home. It asks for sudo only to install
packages it needs that you don't have yet.
What you need
Your machine
- Omarchy 4 on Arch, with Hyprland 0.56 or later
- A GPU: AMD, Intel or NVIDIA
- One of the agents the skill is installed for, if you want them to use it on their own: Claude Code, Codex, OpenCode, pi or Hermes
On NVIDIA
Headless boxes on NVIDIA, and the confirm-close setting, need a fix to aquamarine (Hyprland's backend library) until a
release ships PR #415. install.sh builds it
privately inside the clone; your system's copy isn't touched, and everything else runs on it.
An interactive box renders on the GPU your desktop renders on. With several GPUs, point a headless box at one with
OMABOX_RENDER_NODE.
Install and check
Install
$ git clone https://github.com/diogochaves/omabox && cd omabox $ ./install.sh # asks about the bar widget and the guard $ ./install.sh --check # then starts a box, screenshots it, takes it down
install.sh installs any missing packages, builds the aquamarine fix, then runs omabox setup.
What setup does
- Links
~/.local/bin/omabox - Puts the agent skill wherever Omarchy puts its own skills (
~/.agents,~/.claude,~/.codex,~/.pi/agent,~/.hermes) - Links the bar widget, and asks whether to put it in your bar
- Asks whether to turn on the agent guard
Later, by hand: omarchy plugin enable chaves.omabox, omabox guard on.
Update and remove
Update
$ git pull && ./install.sh
Run it after a Hyprland upgrade too. omabox --version says which aquamarine boxes use. After an
upgrade the bar runs the old widget until the shell restarts; its panel says so. What changed in each release is in the
changelog.
Remove
$ omabox down --all # every box $ omabox setup --remove # guard and broker off, widget off, links gone $ rm -rf ~/.config/omabox ~/.cache/omabox # settings, and box HOMEs a crash left behind $ rm -rf ~/.local/share/omabox # saves, if you made any
Run setup --remove before you delete the clone: once omabox is gone there is no guard off
left to run. Then delete the clone. The packages install.sh added stay; it printed them as
missing: if there were any. The README has
the details.
What a box can't do
Worth knowing before you hand it a task.
- Apps that need system services over the system bus (disks, NetworkManager, bluetooth, power) open with errors or not at all: a box has no system bus, by design.
- No real hardware: monitors, HDR and VRR, input devices, audio, suspend and lock never run in a box. For the installer, system services or a reboot, a whole machine in a VM is the tool.
- It is not a security boundary: it shares your kernel, GPU and, by default, your network. For a fence around the agent, use ai-jail with it.
- Of the agents the skill is installed for, Claude Code and OpenCode were checked end to end; Codex, pi and Hermes find the skill.
Something didn't work on your machine? Run ./install.sh --check and
tell us what happened. Another GPU, several monitors or
a config nothing like ours is the test we don't have.
Keep reading