Agents, off your desktop
Your agents get desktops of their own. Yours stays untouched.
omabox gives every AI agent a whole Omarchy desktop, invisible and in parallel, to launch, click, type and screenshot apps in. However much it does, it never takes control of your system.
- No windows popping up out of nowhere
- Your cursor never moves
- No focus stolen mid-sentence
- No password or keyring prompts
- No notifications or tray icons left behind
- No workspace switches
git clone https://github.com/diogochaves/omabox && cd omabox && ./install.shOmarchy 4 · Hyprland 0.56+ · a GPU render node · MIT
The problem
An agent testing a desktop app tests it on your desktop.
Ask an agent to check a GUI change and it runs the app where you are working. Windows land on top of your editor, your keystrokes go into its app, your workspace switches, your cursor jumps, a password prompt waits for you. Here is the same agent, twice.
The promise
The agent never takes control of your system.
Everything an agent does to see and test its work happens in its box. Here is what that keeps off your desktop, and how.
Its own screen
A box runs its own compositor on a private screen. Nothing it opens is drawn on yours.
Its own pointer and keyboard
Clicks and keys go to the box's own virtual devices, never through uinput, so your cursor and keyboard are never touched.
Nothing opens on your session
No focus changes, no workspace switches. When you peek, the window opens on workspace 9 without taking focus.
No system bus, a throwaway keyring
In a box, pkexec fails at once instead of asking for your password. Its keyring stores and reads secrets without prompting; yours is never asked.
Its own bar
Notifications and tray icons land in the box's bar, and go when the box goes.
The guard, if you want it
With omabox guard on, agents' shells get a display that doesn't exist, so a stray window fails instead of appearing.
A box keeps an agent's apps off your desktop and out of your config, and never gets your secrets or input devices. It is not a security boundary: it shares your kernel, GPU and, by default, your network. To fence the agent in, pair it with ai-jail.
Parallel boxes
One box per agent, the way you give each one a worktree.
A worktree keeps agents' code apart. A box keeps their screens, session buses and test runs apart. Each agent session gets its own box, named after its worktree and its session, so visual checks and desktop tests run side by side without ever seeing each other.
Separate screens
Each box runs its own Hyprland on a private screen of any size. One agent's window never covers another's screenshot.
Separate session buses
Tray icons, notifications, D-Bus names and the keyring are per box, so one agent's test never sees another's, or yours.
Separate lifetimes
One agent's omabox down never ends another's box. A throwaway omabox run -- ctest gets a box of its own, too.
Driving a box
The agent drives its box the way you drive yours.
Launch, type, click, wait and look, with commands that report what happened. 0.2.0 borrows the best ideas from computer-use agents and keeps them in the box.
Peek shows where the agent clicks and what it types, over the view only, never in its screenshots.
newWait, don't sleep
omabox wait returns when the screen holds still, a window shows up or a command passes. keys, click and run -d take --wait, and say so when nothing changed.
$ omabox wait window foot --focused satisfied: window foot focused after 0.17s
newWindows as targets
omabox windows lists them, covered or on another workspace. --window shoots, clicks and types in one window's own coordinates. A selector never guesses.
$ omabox shot --window foot $ omabox click --window foot 320 160
newSmall shots, exact clicks
shot --fit 1280 sends the model fewer pixels; click --in SHOT X Y maps a pixel of that shot back to the screen.
$ omabox click --in /tmp/omabox-app-….png 400 200newPasswords stay off the command line
omabox keys --pass VAR types one of your variables into the box, so a password never shows up in the process list.
newSee what it did
For a few seconds, peek draws a ring where the agent clicks and captions the keys it types, secrets as *.
newFaster, and on NVIDIA
Shots are about twice as fast. Headless boxes run on NVIDIA GPUs, without reaching the host's display.
Watch
Look inside any box, or take the wheel.
Peek
omabox peek opens a live, view-only window of any box on workspace 9, without taking your focus. It only copies frames out, so the agent never notices.
Interactive
omabox up --interactive makes a box a real window you drive with your own keyboard and mouse. SUPER+ALT+ESC sends SUPER keys into it.
The bar widget
The omabox mark in your Omarchy bar lists every box, with peek, screenshot and down for each. The copy here works: click a box, or focus the panel and use its keys.
Your desktop. The boxes are elsewhere, invisible, until you peek.
A working copy of the widget's panel. The boxes are made up; the screenshots are real.
Agents
Agents use it on their own.
Install once. Your agents reach for a box whenever a task touches the desktop, without you asking and without changing your projects.
A skill they already load
install.sh puts the omabox skill wherever Omarchy puts its own. Agents load it for GUI apps, screenshots, shell plugins and tests that touch the desktop.
The guard, for when advice isn't enough
Opt in with omabox guard on: agents' shells lose your display, so a window they forget to box fails with an error the skill explains. When you ask for your real desktop, the agent uses omabox host -- CMD, on the record.
Your projects stay as they are
| Your project says | The agent runs |
|---|---|
./build/app | omabox run -d -- ./build/app |
grim out.png | omabox shot -o out.png |
hyprctl -j clients | omabox hyprctl -j clients |
ctest --test-dir build | omabox run -- ctest --test-dir build |
omarchy-theme-set gruvbox | omabox run -- omarchy-theme-set gruvbox |
Better together
ai-jail fences the agent in. omabox keeps its windows out.
ai-jail, by Fabio Akita (AkitaOnRails), is the sandbox we point people to. It runs an agent inside bubblewrap, Landlock and seccomp on Linux, and sandbox-exec on macOS. It does carefully the one thing omabox doesn't do: limit what the agent can read, write and reach. The two answer different questions, so they stack.
- your project, at its real path
- ~/.ssh, ~/.aws, ~/.gnupg
- your shell's tokens
- network, unless you allow it
the box's
No window, no focus change, no prompt.
ai-jail answers: what can it touch?
A fence around the agent
- Your project read-write at its real path,
/usrread-only - A fresh home: no
~/.ssh,~/.aws,~/.gnupgor browser profiles - The environment cut to an allowlist, so tokens stay in your shell
- Network, display, GPU and Docker off until you allow them
omabox answers: where does it draw?
A desktop of its own
- Its own screen, pointer and keyboard
- Its own session bus, tray, notifications and keyring
- Your cursor, focus and workspaces untouched
- Not a security boundary: that part is ai-jail's
Try a build you don't trust yet
A contributor's branch, an app you just downloaded: run it in ai-jail, and give it the box's screen as its only display.
ai-jail keeps it out of your home, keys and network; its window opens in the box, where omabox shot and
peek see it.
$ omabox up $ eval "$(omabox env)" # Wayland clients now draw in the box $ ai-jail --gpu --rw-map "$WAYLAND_DISPLAY" --env WAYLAND_DISPLAY -- ./build/app
Tested with ai-jail 2.2.0 and omabox 0.2.0 on Linux.
Not yet: an agent inside ai-jail driving omabox itself. The jail has its own process namespace, so the
omabox command inside it can't see the box. For now, keep the agent under omabox's guard and put the apps it
runs under ai-jail. It's planned in issue #16, with no change
needed in ai-jail.
Compare
Is omabox what you need?
It does one thing: keep agents off your desktop while they test on a desktop of their own. If you want something else, these projects are good at it.
Your agents build and test GUI apps, plugins or themes on Omarchy, several at once
omabox
Parallel, invisible Omarchy desktops, and your own untouched.
You want an agent to use your own desktop, without fighting you for the cursor and focus
Cua
That's Cua's focus: computer-use agents that drive real desktops and apps, across macOS, Windows, Linux and Android, through MCP or a CLI. omabox does the opposite: it keeps agents off your desktop.
You want to limit what the agent itself can read, write and reach
ai-jail
A jail for the agent process: your home, SSH keys and cloud credentials out of reach, the project writable. omabox isn't a sandbox; ai-jail is one, and the two stack.
You need a whole machine: an installer, system services, audio, suspend, a reboot
omarchy-in-omarchy
A disposable Omarchy in QEMU/KVM. Heavier, and slower on its first start, but a real machine where a box has no system bus.
| omabox | Cua | ai-jail | omarchy-in-omarchy | |
|---|---|---|---|---|
| What it's for | Desktops for agents to test on, apart from yours | Agents that use computers: yours or theirs | Limiting what an agent can read and reach | A whole disposable Omarchy machine |
| Your screen, cursor, focus | Never touched | Designed to work beside you | Not its concern | A QEMU window |
| Several at once | Yes, one per agent session | Yes | One jail per agent | One VM |
| Start and cost | 3–4 s, about 500 MB | Depends on the desktop | A process wrapper | Minutes once, then seconds; 8 GB RAM by default |
| Security boundary | No | Depends on where it runs | Yes, that's the point | Yes, a VM |
| Platforms | Omarchy on Linux | macOS, Windows, Linux, Android | Linux, macOS (Windows through WSL2) | Omarchy in QEMU/KVM |
Written in September 2026 from each project's own site. They move on their own, so check theirs.
What a box gets
What goes in, and what stays off until you ask.
In the box
- The repo you started it from, read-only, at the same path
- Your theme, bar layout and terminal settings
- mise's toolchains, so node, python and uv work as on the host
- Its own screen, session bus and throwaway keyring
Off until you ask
- Network isolation:
--net isolated --allow 8081 - A systemd user manager:
--systemd - X11 apps:
--xwayland - Your real desktop, one command at a time:
omabox host
Install
Three minutes, then your agents take it from there.
What you need
- Omarchy 4 on Arch, with Hyprland 0.56+
- A GPU render node. Tested on AMD and Intel iGPUs and an NVIDIA RTX 4070 SUPER.
- A patched aquamarine until a release ships PR #415.
install.shbuilds it privately; your system's copy isn't touched.
Install
$ git clone https://github.com/diogochaves/omabox && cd omabox $ ./install.sh # asks before turning the guard on $ ./install.sh --check # starts a box, screenshots it, takes it down $ omarchy plugin enable chaves.omabox # the bar widget
Update with git pull && ./install.sh. To remove it, see the README.
Questions people ask first
Does it work without Omarchy?
No. A box runs your host's own Omarchy: its Hyprland config, its shell and your theme. That is what makes it faithful, and why it needs Omarchy 4 and Hyprland 0.56 or later.
Can two agents test at the same time?
Yes. Each Claude Code or Codex session gets its own box, named after its repo or worktree and its session. Anything else started with omabox guard exec gets one too.
Is it a sandbox?
No. It keeps apps off your desktop and never gets your secrets, input devices or seat, but it shares your kernel, GPU and, unless you pass --net isolated, your network. For a fence around the agent, use ai-jail, which pairs well with omabox; for hostile code, a VM.
Does it work with ai-jail?
Yes, for the apps an agent runs: ai-jail fences the app, and omabox env gives it the box's screen as its only display. An agent inside ai-jail can't drive omabox yet. See Better together.
Does it work on NVIDIA?
Yes. It was tested on an RTX 4070 SUPER with driver 615.71.09. With several GPUs, point a box at one with OMABOX_RENDER_NODE.
Does peeking slow the agent down?
No. Peek only copies frames out of the box.
Built by
Everyone who has shipped code to omabox.
btsouth
diogochavesYour machine is the test we don't have
omabox has run on a handful of setups. Another GPU, several monitors, a fresh Omarchy or a config nothing like ours:
run ./install.sh --check and tell us what happened. That helps as much as code. Bug reports, fixes, tests,
docs and ideas are all welcome, and your tile goes up here with your first merged change.