# How omabox works: a desktop of its own for every agent

This is https://omabox.app/how-it-works as Markdown, for agents. Every page: https://omabox.app/llms.txt

**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](https://omabox.app/commands). Several monitors in one box: [/develop](https://omabox.app/develop#monitors).

## 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](https://omabox.app/how-it-works#ports)). To fence the agent in, pair it with [ai-jail](https://omabox.app/compare).

## 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.

```
$ 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. [**S1** · Hyprland never gets your seat.](https://github.com/diogochaves/omabox/blob/main/SECURITY.md#the-rules)
2. [**S2** · The box HOME is fake and holds no secrets.](https://github.com/diogochaves/omabox/blob/main/SECURITY.md#the-rules)
3. [**S3** · Secrets and live sockets are never mounted or copied in.](https://github.com/diogochaves/omabox/blob/main/SECURITY.md#the-rules)
4. [**S4** · Host code is read-only.](https://github.com/diogochaves/omabox/blob/main/SECURITY.md#the-rules)
5. [**S5** · Each box has its own namespaces and network.](https://github.com/diogochaves/omabox/blob/main/SECURITY.md#the-rules)
6. [**S6** · Teardown kills the box and nothing else.](https://github.com/diogochaves/omabox/blob/main/SECURITY.md#the-rules)
7. [**S7** · The tools that drive a box never follow it out.](https://github.com/diogochaves/omabox/blob/main/SECURITY.md#the-rules)
8. [**S8** · Input never reaches your desktop.](https://github.com/diogochaves/omabox/blob/main/SECURITY.md#the-rules)
9. [**S9** · An agent in ai-jail drives only its own boxes, and gets no more than its jail.](https://github.com/diogochaves/omabox/blob/main/SECURITY.md#the-rules)
10. [**S10** · A connected box reaches no protected port.](https://github.com/diogochaves/omabox/blob/main/SECURITY.md#the-rules)

[Read SECURITY.md](https://github.com/diogochaves/omabox/blob/main/SECURITY.md) · [Report a way around one (privately)](https://github.com/diogochaves/omabox/security/advisories/new)

## 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 Code · Codex · OpenCode · pi · Hermes

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

### The bar widget

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

[The widget on Omarchy](https://omabox.app/omarchy#widget)
