GitHubInstall
1.0New: a contract your scripts can keep →

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.

Today on Omarchy 4 · Hyprland 0.56+ · AMD, Intel or NVIDIA · MIT · Plain Hyprland is coming →

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

        
Your desktop0 windows opened0 focus taken0 cursor moves
Click a box to take it down.
Works with
Claude CodeCodexOpenCodepiHermes
2parallel boxes

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.

omabox ls · 4 boxes up
Your desktopyou, typing
1 2 3 4Tue 22:18
your keystrokes, typed into its app
workspace 7 · the agent's
build finished · 3 tray icons left
Password: ▍
to run /usr/bin/make as the super user
0windows0focus0workspace0cursor0prompts
app-sidebar-5cc72cdcClaude Code · lead
1 2box
app
Settings
☑ Dark mode

waiting for its build

app-menu-3b7a6c11its subagent
1box
ctest · tst_menu
omabox brief
-b app-menu-3b7a6c11
15 lines, not the skill

waiting for a brief

app-theme-71c0ea52Codex
1 2 3box
app · preferences

checking against its baseline

app-docs-e4d29b07pi
1box
docs
foot
RECscene 1

filming a take

No boxes. Every agent works on your desktop.

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.

3ask your agent

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.

1 2 3box · app-5cc72cdc22:18
app
npm run dev
ready in 412 ms
➜ localhost:5173
Settings
☑ Dark mode
☐ Compact rows

What the box shows, as omabox peek would. You never see it unless you ask.

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.

4uses

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 →

5new in

New in 1.0. And before it.

What each release added that you would notice, newest first. Every fix is in the changelog.

0.4 and earlier →

1.0.0 · 2026-10-27 · everything from 0.6 to 1.0 you would notice · changelog →

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

6built for agents

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.

$ omabox brief -b app-5cc72cdc
# the lines a subagent needs, not the whole skill
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.

tree --find~17 tok
a shot~1.5k
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 →

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.

0done
1it ran and failed
2called wrongly
124not in time
The contract →
7ai-jail

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, by Fabio Akita, fences what the agent itself can read, write and reach. Together, a jailed agent tests in boxes of its own.

your machine
ai-jail
the agentclaude, codex, opencode…

rw ~/code/app
its API, nothing else

~/.ssh ~/.config your LAN

omabox
broker
up · run · shot
its boxisolated
./build/app

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 →
8omarchy

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 →
on
omabox runs Omarchy's own config and shell in every box.
9mit

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.

main · diogochaves/omabox your fork: your machine, your rules a fix your machine found → a PR merged
MIT License
Copyright (c) 2026 Diogo Chaves

Permission is hereby granted, free of charge, to any person obtaining a copy of this software… to deal in the Software without restriction.
  • btsouth
  • diogochaves
  • overp0werj0int
  • +

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

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

10coming

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.

box · plain Hyprland · Dux Shell 2.0
Dux Shell 2.0 in a plain box, its control center open: user at omabox, network not connected, no Bluetooth adapters, no output device
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.