# omabox: desktops of their own for your coding agents

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

**Your agents get desktops of their own. Yours stays untouched.**

omabox gives every coding agent a whole Hyprland desktop to test its work in: invisible, one per agent, gone when the agent is.

[See them work](https://omabox.app/#parallel) · [How it works](https://omabox.app/how-it-works)

Today on Omarchy 4 · Hyprland 0.56+ · AMD, Intel or NVIDIA · MIT · [Plain Hyprland is coming →](https://omabox.app/next)

- **No windows** popping up, no cursor jumps
- **No stolen focus**, no password prompts
- **Nothing left behind** when the agent is done

Works with

Claude Code · Codex · OpenCode · pi · Hermes

## Every agent gets a desktop. None of them is yours.

Without omabox, an agent testing a desktop app tests it on your desktop. With it, each agent takes a box of its own: four agents, four apps, four test runs, **all at once**, while you keep typing.

### On their own

Agents take a box when a task needs a desktop, wait until a window has settled instead of sleeping, and put it down when they exit. **No prompt stops them**: in a box, `pkexec` just says no.

### Checks side by side

Tests, visual checks and videos run in parallel, each on its own screen and session bus. **None sees another's windows**, and none sees yours.

### Handed on

A lead agent gives each subagent a box and `omabox brief`: about 15 lines with its windows and the rules, **not the whole skill**.

## You ask. Your agent takes a box.

Install once. A skill your agent already loads tells it when a task needs a desktop. You don't change your projects or your prompts.

- “Check the new settings dialog and show me.”
- “Start a box with the app and the dev server running. I want to try it.”
- “Try all three branches.”

Every command is yours to type too. But omabox is built to be driven by an agent: one call per step, answers in text, waits instead of sleeps. **Even to drive a box yourself, the fastest way in is to ask.**

## A desktop to spare, for whatever you're making.

Testing is where omabox started. Any job that needs a screen and shouldn't touch yours fits in a box too: these are a few we use it for.

### Film what you made

A demo of your app, plugin or feature, filmed in a box while you keep working. Your marks become captions; clicks and keys are drawn in.

```
$ omabox record start -o demo.mp4
$ omabox record mark "scene 2"
$ omabox record stop --show-input --captions
```

### Shots at 2x, or 4K

A box is whatever size and scale you ask for, whatever your monitor is. Crisp shots and videos for a README, a store page or a talk.

```
$ omabox up --size 3840x2160,scale=2
$ omabox shot --window app
```

### A clean setup, not yours

A stock bar and theme, a clock that never moves, nothing on screen but what you show. Keep a terminal out of the shot: its prompt still has your user and host names.

```
$ omabox up --clean --stock-bar --theme tokyo-night
```

### Monitors you don't have

Portrait, scaled, side by side or below. Plug and unplug them while the box runs, and see what your shell does.

```
$ omabox up --monitor 1080x1920 --monitor 2560x1440,scale=1.6,below
```

### Look at a web page, off your screen

Your agent opens a site in the box's browser, pages down and reads the shots. No browser window lands on your desktop.

```
$ omabox run -d --wait -- chromium --app=URL
$ omabox keys Page_Down
```

### Find the crash first

Unplug a monitor again and again until your shell or plugin falls over, then read the backtrace. Your session never notices.

```
$ omabox output drop --cycles 50
$ omabox gdb --shell
```

Every screenshot on this site was taken in a box, too. [More uses →](https://omabox.app/uses)

## New in 1.0. And before it.

What each release added that you would notice, newest first. Every fix is in the [changelog](https://omabox.app/changelog).

**1.0.0** · 2026-10-27 · everything from 0.6 to 1.0 you would notice · [changelog →](https://omabox.app/changelog#v1.0.0)

- **A contract your scripts can keep**

  Within 1.x, exit codes and `--json` fields stay or only grow. A change warns for one release first; `OMABOX_STRICT=1` makes it an error, for CI.

- **One binary, in Rust**

  Stopped mid-step, omabox undoes that step: an interrupted `up` takes its box down, a stopped recording keeps its video.

- **Ports no box reaches**

  Your database stays out of every box, on loopback or any of your host's addresses.

  ```
  $ omabox config protect-ports 5432,8080
  ```

- **The app answers in text**

  `tree`, `check`, `record` and `audio`: an agent asks the app, compares it with a baseline, films it and hears it.

**0.9.0** · 2026-10-20 · the last release before 1.0 · [changelog →](https://omabox.app/changelog#v0.9.0)

- **A brief for a subagent**

  About 15 lines a lead agent pastes into a subagent's prompt in place of the whole skill.

  ```
  $ omabox brief -b app-menu
  ```

- **Help that fits**

  `omabox help CMD` is the command's lines and options; `--long` has the prose.

- **Exit codes that mean one thing**

  Called wrong is exit 2, with the nearest option or command named, in every command.

  ```
  $ omabox help exit-codes
  ```

- **Holds in a video**

  `record hold` pauses a take on the video's own clock; `record --for` films something that moves by itself.

**0.8.0** · 2026-10-20 · visual checks · [changelog →](https://omabox.app/changelog#v0.8.0)

- **Visual checks**

  `check` compares an app's or a plugin's look with a baseline, in a box where only what is tested moves.

  ```
  $ omabox check run -- ./visual.sh
  ```

- **Your own Quickshell**

  Run the box's shell on a Quickshell build of yours.

  ```
  $ omabox up --quickshell ~/src/quickshell/build
  ```

- **Your fonts, in every box**

  Read-only, so an app draws in a box the way it draws for you.

- **Says what's in the way**

  `click --window` says when a toast or another layer covers the point it aims at.

**0.7.0** · 2026-10-16 · held keys, your binds · [changelog →](https://omabox.app/changelog#v0.7.0)

- **Hold a key across commands**

  Hold Shift, click three things, let go.

  ```
  $ omabox keys down:shift
  ```

- **Your binds, in the box**

  A box loads your Hyprland bindings and input settings.

- **A journal in every box, CPU per thread**

  Logs of what ran, and where the time went.

- **A crash says it crashed**

  With the signal, so an agent doesn't wait on a window that will never come.

**0.6.0** · 2026-10-14 · the app as text · [changelog →](https://omabox.app/changelog#v0.6.0)

- **A window as text**

  An app's controls as compact text, for a fraction of a shot's tokens.

  ```
  $ omabox tree --find 'dark mode'
  ```

- **Videos with sound and marks**

  `up --audio`, `record mark`, and every monitor in one video.

- **Your whole shell in a box**

  Every plugin and your `shell.json`, without touching your bar.

  ```
  $ omabox up --desk-shell
  ```

- **Boxes nobody will take down**

  `ls` names them; `down --orphans` clears them.

**0.5.0** · 2026-10-09 · several monitors in one box · [changelog →](https://omabox.app/changelog#v0.5.0)

- **Several monitors in one box**

  As many as a test needs, any size, scale and place, a bar on each.

  ```
  $ omabox up --monitor 1080x1920
  ```

- **A monitor that drops off and comes back**

  `output drop --cycles`, until your shell crashes; `gdb` gives the backtrace.

- **Your theme, live**

  `--theme-dir` puts the theme you are editing in the box, every save with it.

- **Only what changed**

  `shot --changed` sends only what an action changed: a menu opening is about 65 image tokens instead of 1.5k.

## Everything an agent needs to test its work, and nothing of yours.

### One box per session

Named after its worktree and session. Up in 3 to 5 s, about 400 to 600 MB, down when the agent exits. Subagents get a box and a brief each.

[How it works →](https://omabox.app/how-it-works)

### Answers in text

After a click, omabox says what changed, or that nothing did. `tree` reads the app's controls, where a shot costs far more.

[Develop →](https://omabox.app/develop)

### Checks and videos

`check` keeps what three runs agree on as the baseline, then names the button that moved. `record` films a take with captions and a contact sheet.

[Develop →](https://omabox.app/develop)

### A contract your scripts can keep

In 1.x, exit codes and `--json` fields only grow, and a change warns for one release first. Rewritten in Rust for 1.0.

[The contract →](https://omabox.app/commands#contract)

## Not a sandbox. Pair it with ai-jail.

omabox keeps an agent's windows off your desktop, but it is **not a security boundary**: a box shares your kernel, GPU and network. [ai-jail](https://aijail.io), by Fabio Akita, fences what the agent itself can read, write and reach. Together, a jailed agent tests in boxes of its own.

ai-jail decides what the agent can touch. omabox decides where it draws.

### A jailed app, drawn in a box

```
$ omabox up
$ eval "$(omabox env)"
$ ai-jail --gpu --rw-map "$WAYLAND_DISPLAY" \
    --env WAYLAND_DISPLAY -- ./build/app
```

### A jailed agent, driving boxes of its own

```
$ omabox broker on   # the lines for ~/.ai-jail
$ ai-jail claude
```

Tested with ai-jail 2.10.0 and 2.12.0 and omabox 1.0. A jailed agent can't use `host`, `peek` or interactive boxes.

[omabox and ai-jail →](https://omabox.app/compare)

## Fullest on Omarchy.

On Omarchy a box is your desktop: Omarchy's own config and shell, your theme and bar, your plugins with `--desk-shell`, and a widget in your bar that lists every box.

[omabox on Omarchy →](https://omabox.app/omarchy)

## MIT, every line. It's your computer.

omabox is built by builders, to make other builders' lives easier. All of it is MIT: read it, fork it, bend it to your machine, ship your own. Every fix someone sends makes it better for the next person. That's why it won't stay on Omarchy alone: **the builders on Hyprland are who it's for.**

- [btsouth](https://github.com/btsouth)
- [diogochaves](https://github.com/diogochaves)
- [overp0werj0int](https://github.com/overp0werj0int)

Your machine is the test we don't have: a GPU, a distro, a shell we never ran.

[Read the code](https://github.com/diogochaves/omabox) · [Contributing →](https://github.com/diogochaves/omabox/blob/main/CONTRIBUTING.md)

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

[Install guide](https://omabox.app/install) · [GitHub](https://github.com/diogochaves/omabox)

## omabox beyond Omarchy.

omabox was born on Omarchy, but it can help many more people, so it's growing. Here's what's coming next.

### Plain Hyprland boxes

Aimed at any distro with Hyprland 0.56+ (Lua config). For Hyprland plugin and compositor developers.

### Your own shell

One shell at a time, Dux Shell first.

### Your own Hyprland desktop, in a box

Your config, your binds, your shell: your agent tries a change to your desktop in a box first.

[Tell us your shell](https://github.com/diogochaves/omabox/issues/321) · [What has run, and what hasn't →](https://omabox.app/next)

![Dux Shell 2.0 in a plain box, its control center open: user at omabox, network not connected, no Bluetooth adapters, no output device](https://omabox.app/media/dux2-control-center.webp)

A spike, not a release: Dux Shell 2.0 in a plain box. No system bus, so network and sound read "Not connected" and the shell keeps running.
