GitHubInstall

How it works

A whole desktop for every agent, none of it on yours.

A box is a real Hyprland desktop: its own compositor, its own session bus, on a screen only it can see. On Omarchy it is Omarchy's, with your theme and bar. Here is what it keeps off your desktop, and how.

The agent starts a box, works in it, and the box goes when the agent does.

1

It reaches for a box

Whenever a task touches the desktop: a GUI app, a screenshot, a bar plugin, tests that need a tray or a keyring.

2

It starts one

A whole desktop only it can see, on one screen or as many monitors as the test needs. Up in a few seconds.

$ omabox up
3

It works in it

It launches, clicks, types and reads what changed. Your cursor, keyboard and focus are never touched.

$ omabox run -d -- ./build/app
$ omabox click 600 300 --wait
4

It goes with the agent

When the agent's session exits, its box goes too, notifications and tray icons included.

Every command and option: /commands. Several monitors in one box: /develop.

What it keeps off your desktop, and how

Everything an agent does to see and test its work happens in its box.

Windows out of nowhere

Its own screen

A box runs its own compositor on a private screen. Nothing it opens is drawn on yours.

Your cursor, your keys

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.

Stolen focus

Nothing opens on your session

No focus changes, no workspace switches. When you peek, the window opens on workspace 9 without taking focus.

Password prompts

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.

Leftovers

Its own bar

Notifications and tray icons land in the box's bar, and go when the box goes.

Accidents

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. It catches mistakes; it is not a boundary.

What a box gets

Enough of your setup to look and behave like your desktop, and nothing that would let it reach yours.

In the box

  • The repo you started it from, read-only, at the same path (from a git worktree too, so git works there)
  • Your theme, bar layout and terminal settings
  • Your fonts, read-only, so a theme's or a plugin's faces draw as on your desktop
  • 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
  • Sound: --audio, its own PipeWire, a speaker nobody hears and a silent microphone
  • Addresses of its own for an isolated box: --addr, documentation ranges only
  • A systemd user manager: --systemd
  • X11 apps: --xwayland
  • Your real desktop, one command at a time: omabox host

Never in a box

  • Your agents' and browsers' own stores (~/.claude, ~/.codex, browser profiles, ~/.pki), whichever way you try to mount them
  • Plugin settings that look like a key, token or password
  • api-keys.env, your hooks, or anything of ~/.config/omarchy but its plugins and themes
  • Your keyrings, ~/.ssh, ~/.gnupg and the rest of your secret stores

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 (keep ports from it below). To fence the agent in, pair it with ai-jail.

1.0.0

Rewritten in Rust, and tighter for it.

1.0 is one binary built from Rust. The commands are the ones you know. Underneath, a box reaches less of yours and leaves less behind.

Your terminal stays yours

A command in a box runs in a session of its own, with no controlling terminal. It can't read what you type, write to your terminal or signal it. Ctrl-C still reaches it.

Its display, and only its display

omabox env points at the box's Wayland socket through a hard link the box can't swap, so a host tool never lands on another display.

Nothing half-done

Stop omabox at any step, with Ctrl-C or a signal, and it undoes that step: an interrupted up takes its box down, a recording keeps the video so far, a half-made monitor goes, temporary files go.

No crash notifications from a box

The tools omabox runs against a box (grim, hyprctl, gdb) get the box's crash limits, so a crash in one doesn't reach your desktop's notifications.

Faster in

~3 ms

omabox enters a box itself, without nsenter: omabox run -- true in about 3 ms.

Name the ports a box must not reach.

A connected box reaches your network and your host's servers, like any app. If a database or an admin panel listens on your machine, protect its port.

protect-ports=5432,8080
127.0.0.1:3000your dev serverreached
127.0.0.1:5432your database, on loopbackprotected
5432 by a Docker bridgethe host's other addressesprotected
8080 by your VPN addressan admin panel, TCP or UDPprotected
$ omabox config protect-ports 5432,8080

No connected box reaches those ports, on loopback or through any of your host's other addresses (a Docker bridge, a VPN), TCP or UDP. None are protected by default; it needs nftables.

An address your host gains after a box started is not covered. It's still not a security boundary: for a box with no network but the ports you choose, use --net isolated --allow.

$ omabox up --net isolated --allow 8081

Ten rules, each with the code that holds it and the test that proves it.

omabox promises one thing: a box never reaches your real desktop. SECURITY.md lists each rule behind that promise, from "Hyprland never gets your seat" to "a connected box reaches no protected port", where omabox enforces it, and which test proves it. They keep a box from reaching your desktop by mistake or through an app that misbehaves. They are not a defence against code written to escape: a box is not a security boundary.

  1. S1Hyprland never gets your seat.
  2. S2The box HOME is fake and holds no secrets.
  3. S3Secrets and live sockets are never mounted or copied in.
  4. S4Host code is read-only.
  5. S5Each box has its own namespaces and network.
  6. S6Teardown kills the box and nothing else.
  7. S7The tools that drive a box never follow it out.
  8. S8Input never reaches your desktop.
  9. S9An agent in ai-jail drives only its own boxes, and gets no more than its jail.
  10. S10A connected box reaches no protected port.

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

omabox setup (install.sh runs it) puts the omabox skill wherever Omarchy puts its own. Agents load it for GUI apps, screenshots, shell plugins and tests that touch the desktop. It is about 2k tokens fewer since 0.9: the core every task needs, the rest in a reference the agent reads by section.

Claude CodeCodexOpenCodepiHermes

Subagents get a brief

omabox brief -b NAME prints what a subagent needs: the box, its windows, each with a word that finds it, and the rules. It costs a quarter of the skill or less.

$ omabox brief -b app-menu-3b7a6c11

It says what changed

After a click or keys with --wait, omabox says what changed: a window opened and took focus, a menu opened, or nothing did. The agent doesn't need a shot to learn that nothing happened.

$ omabox click 600 300 --wait

Small shots, so the context lasts

Screenshots are most of what a session spends. shot --changed sends only what changed since the last one: a menu opening is about 65 image tokens instead of 1.5k, 6.7 times less over 17 measured actions, and nothing at all when nothing changed. pixel reads a colour as text.

$ omabox shot --changed --window myapp
$ omabox pixel 40 12   # the colour there, as #rrggbb

A server that died is said

A run -d job that dies in its first 30 s is one warning on the box's next command, with its exit status and log.

$ omabox run -d -- npm run dev

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.

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 omabox save it. Boxes started --from the save open with it already set up, keyring included.

$ omabox save signed-in
$ omabox up --from signed-in

Opt-in

Report what omabox got wrong

omabox setup --feedback-skill adds /omabox-feedback. Your agent looks back through the session for omabox failures, takes your paths, names and tokens out, and files them on your yes.

$ omabox setup --feedback-skill

One box per agent session

A worktree keeps agents' code apart. A box keeps their screens, session buses and test runs apart. Each session's box is named after its repo or worktree and the session, like app-tray-5cc72cdc.

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.

One thing they share: their servers reach you on your 127.0.0.1, one box per port. A server on a port you or another box already use fails to start (address in use), and omabox ports says who has it. With --net isolated a box keeps its ports to itself.

Each box: up in 3 to 5 s, about 400 to 600 MB (it depends on the GPU), down when its agent exits or after 2 h idle.

Look inside any box, or take the wheel.

A box is invisible until you want to see it.

Ask for one

The easiest way in is to ask.

“Start a box with the app and the dev server running, I want to try it”

That gets you an interactive box: a window on workspace 9 that you drive, opened without taking your focus. Your agent can still click, type and take shots in it, and rebuild the app in place (run -d --replace) while you test. It starts one only when you ask.

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 once; with omabox keys-to-box on they follow focus and the pointer into it, and its border turns red while they do. omabox clip hands it your clipboard (a URL, a password), and --from-box brings the box's back.

An interactive box: a whole Omarchy desktop as a window with the app menu open, next to the terminal that drives it

The bar widget

On Omarchy, the omabox mark in your bar lists every box, with peek, screenshot and down for each. On /omarchy a copy works: click a box, or focus the panel and use its keys.

The widget on Omarchy

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 →