Changelog
What each release added.
What you would notice, newest first. Every fix is in the changelog below.
New in 1.0.
Everything from 0.6 to 1.0 that you would notice, in one tab.
A contract your scripts can keep
Within 1.x, exit codes and
The contract →--jsonfields stay as they are or only grow. A command or option that has to change warns for one release first;OMABOX_STRICT=1makes that warning an error, for CI.One binary, in Rust
Stopped mid-step, omabox undoes that step: an interrupted
uptakes its box down, a stopped recording keeps its video. Entering a box is its own now, not nsenter's:run -- truein about 3 ms.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,8080Ports →The app answers in text
On /develop →tree,check,recordandaudio, from 0.6 to 0.9: an agent asks the app, compares it with a baseline, films it and hears it.
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-menuHelp that fits
omabox help CMDis the command's lines and options;--longhas 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-codesHolds in a video
record holdpauses a take on the video's own clock;record --forfilms something that moves by itself.
Visual checks
checkcompares an app's or a plugin's look with a baseline, in a box where only what is tested moves.$ omabox check run -- ./visual.shYour own Quickshell
Run the box's shell on a Quickshell build of yours.
$ omabox up --quickshell ~/src/quickshell/buildYour 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 --windowsays when a toast or another layer covers the point it aims at.
Hold a key across commands
Hold Shift, click three things, let go.
$ omabox keys down:shiftYour 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.
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-shellBoxes nobody will take down
lsnames them;down --orphansclears them.

omabox shot.Several monitors in one box
As many as a test needs, any size, scale and place, a bar on each. Add and unplug them while the box runs.
$ omabox up --monitor 1080x1920 --monitor 2560x1440,scale=1.6,belowEvery desk you don't have →A monitor that drops off and comes back
output drop --cyclesdoes what a monitor waking up does, again and again, until your shell crashes.gdbgives the backtrace.Your theme, live
--theme-dirputs the theme you are editing in the box, every save with it;--themestarts a box on the theme you name.Only what changed
shot --changedsends only what an action changed: a menu opening is about 65 image tokens instead of 1.5k.shot --burstcatches a transition in frames.
It says why a plugin isn't in the bar
up --pluginandrestart-shellprint why the shell didn't load it: a manifest it refuses, a QML error.The box says what it tested
ls --jsonrecords the Omarchy version, the theme and each plugin's commit, so a screenshot in a pull request says exactly what it shows.Steps written for your desktop, done in a box
The agent skill maps "link the plugin", "edit shell.json" and the rest to the box, where they can't change your bar.
On /develop →
Your Omarchy checkout, not installed
up --omarchy DIRruns a box on that tree's config, shell and scripts, asomarchy dev linkwould, without touching your system.$ omabox up dev --omarchy ~/src/omarchyOmarchy's own binds work in a box
The browser bind opens the browser in the box, and Omarchy's shell restart restarts the box's shell.
The bar widget, offered at setup
omabox setupasks to put it in your bar, and the widget says when it is older than the omabox installed.
One command to set up, one to undo
Install →omabox setuplinks omabox, the agent skill and the bar widget and offers the guard;setup --removeundoes all of it.Your system's aquamarine
Boxes run on the aquamarine you have, and use the private build only for what needs its fix.
Inside the box's Hyprland
omabox luaevaluates Lua in it,logreads its logs,eventsstamps what it reports: an agent checks without a screenshot.$ omabox lua 'hl.get_active_window()'Sign in once, every box starts signed in
omabox savekeeps a box's HOME, keyring included; boxes started--fromit open already set up.Agents inside ai-jail drive boxes of their own
ai-jail with omabox →omabox broker on, with no change to ai-jail: the jail's boxes get only what the jail has. omabox itself is not a security boundary.Your Hyprland build in a box
up --hyprland PATHruns a build of yours instead of the installed one, beside a stock box to compare.
Windows as targets
omabox windowslists where each window is and what covers it;shot,clickandkeystake--window.Wait for the screen, not a timer
omabox waitreturns when the screen holds still, a window opens or a command succeeds: no moresleep.A box per agent session
Two agents in one repo get a box each, named after the session, and each goes down when its agent exits.
A network of its own
Every box gets its own network: it reaches the internet and your servers, and you reach its. Much of this release is Tyler South's (@btsouth).
NVIDIA GPUs
Headless boxes on NVIDIA, thanks to Tyler South (@btsouth).
Boxes
omabox up: a whole Omarchy desktop, invisible, for an agent to launch, click, type and screenshot in.Tests that touch the desktop
omabox run -- ctestruns them against a box's own tray, notifications and keyring.Peek, or drive it yourself
omabox peekwatches a box;up --interactivemakes one a window you drive.The skill, the guard and the bar widget
Agents reach for a box on their own, the opt-in guard catches a window they forget to box, and the widget lists every box in your bar.
Every change, release by release.
omabox's CHANGELOG.md at omabox 1.4.1, the latest
release when this site was built. Update with git pull && ./install.sh.
1.4.12026-11-08
A fix for Omarchy boxes on a theme whose pictures are links into your HOME (a dotfiles or wallpapers folder): the box gets copies, so the folder path --home gives an agent no longer leads into your files, and the box shows those pictures. Also a short omabox help, one line a command, the skill's loop typing with --wait --tree, and ai-jail 3's config path. Update.
Omarchy: as 1.4.0, Omarchy 4.5 and, deprecated, 4.0 (dropped in the first release after 2026-12-04), on Hyprland 0.56.2; 0.57.1 also runs boxes.
Fixed
- An Omarchy box's HOME held links into your real HOME (#448): a theme of yours whose wallpapers are links into another folder of your HOME (a dotfiles or pictures repo) was seeded with those links, so on the host the folder
omabox path --homegives an agent's file tools led into your files, and in the box the pictures were missing. Each such link is now a copy of its file, as a desk box copies (no secret's name or content, 32 MiB a picture, 1 MiB other files, 128 MiB in all), or is left out andupsays so;up --froma save made before this fixes the save's links the same way.path --homewarns about a link into your HOME for every box now, not only a desk box.
Changed
- Bare
omabox helpis an index: each command once, with a few words on what it is for (#450). It printed every command's options, 147 lines, which agents cut withheadto find one name.omabox help --allprints those lines as before;help CMDandhelp --longare unchanged. - The skill's loop types with
--wait --tree(#449): the action's own line says what changed in the app's tree, instead of atreecall in a second turn; step 1 names--expect tree TEXT, andomabox briefsays the same to a subagent. - ai-jail 3:
omabox broker onsays to add itsro_mapsto~/.config/ai-jail/config.toml($XDG_CONFIG_HOME/ai-jail/when that is set), where ai-jail 3.0 moved its global config; ai-jail before 3.0 read~/.ai-jail, and 3.0 moves that file there on its first launch, so lines already added keep working.broker offandup's "this sandbox refuses new namespaces" say so too. Tested with ai-jail 3.3.0: the broker reads a 3.x jail as it read a 2.x one, and a real Claude Code in the jail drives its own box.docs/ai-jail.mdsays how to start Claude in the jail on Omarchy 4.5, where mise's command wrappers cannot take their lock in the mise folder ai-jail maps read-only.
1.4.02026-11-07
Your own desktop in a box: up --desktop desk runs your Hyprland config, your shell and your look at your HOME's path, on a copy of your files, held awake between an agent's steps. Also window --fullscreen and --maximize, which set a window's state instead of toggling it, and --net host for tools that scan your real LAN. Update.
Omarchy: as 1.3, Omarchy 4.5 and, deprecated, 4.0 (dropped in the first release after 2026-12-04), on Hyprland 0.56.2; 0.57.1 also runs boxes.
Added
up --desktop desk: your own desktop in a box (#321): your Hyprland config, your shell and your look, where an agent can drive them without touching your session. The box HOME is the same fake HOME every box gets, made in its own folder, but mounted at your HOME's own path (/home/you, not/home/sbx), so what keeps absolute paths (DankMaterialShell's wallpaper, say) finds them in the box; nothing of your real HOME is mounted at it or above it. - The copy:upcopies your~/.config/hypr, the config and state of the shell you run (found by--shell, by what yourhyprland.luastarts, or by its systemd unit), and the wallpapers they show (where the shell keeps its wallpaper's path, and what your config'sswww,swaybgor hyprpaper names; nothing else a copied file names), into the box's HOME before--seed. Links (stow, home-manager) are followed and copied as files, so nothing the box writes reaches yours; a link into a secret store, a secret's name or a file that holds a key's shape stays out, and so does what is over the caps.upsays what it left out; box.json'sdesk_copylists every file. A config the copy would refuse failsupbefore any box is made. - Its files from the host:omabox path --homegives the box HOME's folder as for any box; omabox's own links in it are relative, andpath --homewarns on stderr when the folder holds a link into your real HOME (following one from the host edits your file, not the box's). A mount inside another mount in that HOME (a font folder, the repo) is refused. - Your config runs: the box's Hyprland loads yourhyprland.luaas your desk does, your look, input and binds with it, omabox's settings over it (the screen and monitors, no red error bar, the cursor's buffer). What it starts goes through an autostart policy: idle and lock daemons, your systemd session, system-bus applets and what the box runs itself are dropped, the rest runs, and each decision is a line of the newomabox log autostart. Ahyprland.confalone is refused (hyprctl eval, which keys, click and the rest use, refuses it). - Your shell: DMS, Noctalia, Caelestia, Waybar or a Quickshell config, found in what your config starts (throughenv,setsid,uwsm app --andsh -c) or by its systemd unit, runs in the box's shell slot, as--shell CMDdoes on a plain box:upwaits for it and says which, andls(andls --json'sshell_cmd,shell_from),pid shell,log shell,restart-shelland the crash notes work on it. A second shell is dropped;--shell CMDruns another instead,--no-shellnone; a config that starts none omabox knows makesupfail at once, saying so. A shell found whose program is not installed (a unit link left after its package went) is never started:upsays so and the box comes up with no shell. - On an Omarchy desk (Omarchy installed and your config loading it; box.json'sdesk_base) the box is an Omarchy box running your config, its shell Omarchy's with your plugins andshell.json, on your wallpaper even when your backgrounds folder is a link into another repo (its pictures are copied; an intro video beside them is not). It takes--plugin,--theme,--theme-dir,--dnd,--no-dockand--omarchy, and refuses--stock,--stock-barand--keep(not your desk).--desk-shellis part of--desktop desknow: alone it still works, with a note, for this release. - Held awake: your shell's own idle timeouts (a lock, a blank screen) would fire between an agent's steps, so a desk box keeps an idle inhibitor on a bare surface with no role, which Hyprland counts on every monitor, under a fullscreen window too (tools/idlehold, new;install.shand the AUR package build it,doctorlists it), and turns a shell's timeouts off in its copy where it knows how (Caelestia). A shell's idle client that ignores inhibitors still goes idle. Inside a desk box labwc'sLABWC_PID, which a shell may take for a labwc session, isOMABOX_LABWC_PID. - Refused for now:--clean(the HOME path carries your login name),config desktop desk, a jailed agent's desk box,check run --desktop desk(a check needs the same box every run), and--net host(your own programs on your network namespace would reach your session's abstract sockets).window --fullscreenand--maximize: a window's state set, not toggled (#443):omabox window --window SEL --fullscreenmakes the window fullscreen (the whole screen, no bar: for a take or a shot of the app alone),--maximizemaximizes it (the bar kept), andoffafter either takes it out of that state. Asking again changes nothing, so an agent that does not know the window's state cannot flip it the wrong way, as the oldhyprctl dispatch fullscreentoggle did.windowsshows the state (on-screen,active,fullscreen), andwindows --jsonhas it asfullscreenMode(none,maximizedorfullscreen).--net host: a box on your host's network, for tools that scan the real LAN (#313): a connected box sits behind pasta, which answers for every address on its subnet, so a device scan there finds one at each.up --net host(orrun --net host) shares your host's network namespace and keeps the rest of the box its own: seat, session bus, runtime dir, HOME. Only when you name it: never the default, and noomabox configkey picks it. Its servers take your host's real ports, so they collide with your services and other host boxes (nothing is forwarded;omabox portssayshost-net), it sees your real interfaces (VPN, Docker bridges), and its ARP and ICMP reach your LAN. Not for code you do not trust. Refused with--allow,--addr,--xwayland(its X server would catch your X11 apps),--desktop desk, inside ai-jail, and whileprotect-portsnames a port.
Changed
--net hostwas a silent alias of--net connected(its name before every box had a network of its own); it is the mode above now, andup --net hostsays so in a note on stderr through the 1.4 releases. A script passing--net hostfor a connected box should pass--net connected, or nothing (the default).
1.3.02026-11-07
omabox beyond Omarchy: plain boxes (up --desktop plain, with your own shell by --shell), chosen by themselves where Omarchy is not installed; install.sh, setup and doctor on Arch without Omarchy, Debian, Fedora and openSUSE; and Hyprland 0.57 beside 0.56 (up --hyprland DIR, the aquamarine build for its soname). Also what an app notified (log notifications, wait notification), one run -d job's log (log run JOB), real drag-and-drop by drag, and record without libx264 and with every frame kept. Update.
Omarchy: as 1.2, Omarchy 4.5 and, deprecated, 4.0 (dropped in the first release after 2026-12-04), on Hyprland 0.56.2; 0.57.1 also runs boxes.
Added
- What an app notified:
log notificationsandwait notification RE(#430): every box records what reaches its notification server fromupon, whatever server that is (the shell's, a plain box's, none yet): each notice with its app, summary, body, hints, actions and the id the server gave (one it gave late too, up to D-Bus's 25 s), and each close, dismissal and action; GTK apps' GNotifications included.omabox log notificationsprints a line each (--json: a JSON object each);omabox wait notification REwaits for one whose summary or body matches. No moredbus-monitorin the box and grepping its output. up --hyprland DIRruns another Hyprland version whole (#424): besides a binary,--hyprlandtakes a folder: an unpacked package (usr/bin/Hyprland), an install prefix (bin/Hyprland) or a build folder (Hyprland). Its libraries load first (its aquamarine is the box's) and itshyprctlis the box's, so a box can run Hyprland 0.57 on a desktop that still has 0.56.OMABOX_HYPRLAND=PATHmakes it the default for everyup.up --desktop plain: a box without Omarchy (#247): its Hyprland runs omabox's own small config (Hyprland's defaults, your keyboard layout, a terminal on SUPER+RETURN) and sees no Omarchy tree; it has no shell and a HOME with git's name and email only. Options that need Omarchy are refused.lsandls --jsonsay each box's desktop; Omarchy stays the default.- Setting omabox up on a distribution other than Arch (#247):
install.shknows Debian and Ubuntu, Fedora, openSUSE and NixOS besides Arch. It checks that distribution's packages under their own names and, for what is missing, prints the command that installs them (sudo apt install …,sudo dnf install …,sudo zypper install …) and stops; it runs sudo itself only on Arch, as before. NixOS is not supported yet (a box looks for its programs in/usr/bin): it says so and what it would need. Hyprland 0.56 or later, compared without pacman. omabox doctoron a machine without Omarchy (#247): the Omarchy and theme checks are information (info, a new status in--json), not failures: plain boxes only. quickshell is information there too (only a shell in a box needs it); on Omarchy it is still required. Package names for NixOS, and Debian's quickshell and openSUSE's dbus packages corrected.up --desktop plain --shell CMD: your shell in a plain box (#247): the box's shell is CMD (dms run,qs -p DIR, ...).upwaits until it draws, says when it exits or crashes on the way,omabox log shellis its output,restart-shellstarts it again and its crash is said as the shell's;--quickshellmakes a build itsqs.lsnames it.- Plain boxes where Omarchy is not installed, and
--cleanon them (#247): without--desktop,upstarts a plain box on a machine without Omarchy (the same testdoctorandsetupmake) and says so; on Omarchy it is still Omarchy's.omabox config desktop omarchyorplainsets your default (--desktopwins).up --cleanworks on a plain box: its background is the#ff00ffsentinelcheckfinds holes on, with the locale, pointer, network, animations and fonts frozen as on an Omarchy box. up --cleanshows no name of yours: the box's user isuser(no full name, in its own/etc/passwdand/etc/group) and its hostomabox, so a greeting, a terminal's title or a prompt in a shot to publish carries neither.--keep identitykeeps yours. Baselines approved before that show your name or host name will differ once.log run JOBreads onerun -djob's log (#429): by its pid, aswait log JOB REtakes it, however many jobs were started after it (a terminal, anxdg-open) and after it ended;--grep,-nand-fas for any log.log runalone still reads the latest job's. A pid no job had is refused naming the jobs there are, bywait jobandwait logtoo.run -dnow prints the job's pid alone on stdout (under-qtoo;--print-logstill prints the log's path instead), soJ=$(omabox run -d -- app)keeps it forlog run "$J",wait job "$J",wait log "$J" REandstop "$J".
Changed
record stopstill makes a video when ffmpeg is stuck (#445): when the video's encode ran out of its time limit twice (ffmpeg 9.0.1 can deadlock, or a busy machine made it too slow),stopfailed and left the raw recording in the box. It now copies the recorded H.264 into the MP4 without re-encoding it, which takes seconds, and says in one line what that video lacks next to a normal one: a steady frame rate, and whatever else was asked for (the sound, the drawn input, captions, the cut of still stretches, a layout's monitors composed into one picture: each is its own track instead); it is also larger. Only when that copy fails too doesstopfail, keeping the raw files as before.
Fixed
up --interactivesays why its box never came up on aquamarine 0.15.1 (#406): on an aquamarine without the fix for nested Wayland outputs (hyprwm/aquamarine#415), such as the system's 0.15.1, an interactive box's window could lose its size as it opened, andupgave up with only "Hyprland not up after 30s". When the box's Hyprland shows that (its output at 0x0),upnow says so and points toomabox setup --aquamarine, which builds the fix.record stopkeeps every frame recorded before it, under load too (#444): wf-recorder drops the frames still waiting for its encoder when it is told to stop, so on a busy machine a video lost up to a second before the stop, even right after arecord holdthat had said those frames were there. Stop now waits for them to be written first (a few milliseconds when the encoder keeps up; at most 10 s, said if it runs out). The test suite's check of a stop whose ffmpeg hangs once no longer fails on a busy machine (#445): the short time limit it set for the hung run also cut off the real encode after it, and a failure there now keeps the stop's output and its raw recording.click --ina crop at a fractional scale lands on the pixel you read (#432): a pixel of ashot -gcrop at 1.25, 1.5 or 4/3 was turned into a layout point by the image's size over the region's, which could put it a layout pixel off the one under that pixel. It now maps asfind --imageandpixeldo, by its monitor's scale (drag,pointer,scrollandpixel --intoo);--fitand--zoomshots map by their size as before.- A box's HOME is no longer removed while its
upsets it up (#433): with several omabox commands at once (agents in parallel), adownand a newupof one name could meet anotherup's sweep of gone boxes' HOMEs, which removed the new box's HOME as it was seeded (up: could not write … in the box HOME). The sweep now checks again under the name's lock and moves a HOME aside in one step before removing it. Every HOME removal is logged in~/.cache/omabox/.removed.log, with the process and the reason. dragdoes real drag-and-drop in GTK, Chromium and Qt apps (#428): a drag in a GTK 4 app could stay a click (GTK starts one only on a motion 100 ms after the press), and one that began on the path's last step dropped at the window's centre (Hyprland's first word to the drop target), so a folder dragged onto a Nautilus bookmark gave "You cannot move a file over itself". The path now takes 150 ms at least and ends with a 1 px nudge and back, so the drag starts and drops where it ends; other drags end where they did.- A jailed agent's recording stopped outside the jail is no longer deleted at the next
up(#433): its video went to~/.cache/omabox/records, the folder of box HOMEs, whose sweep of gone boxes' HOMEs tookrecordsfor one. It now goes to~/.local/share/omabox/records; videos already in the old folder are moved there at the nextup, which says so. - A box ends with its pasta under SELinux too (#247): on Fedora, SELinux refuses pasta the death signal that ends a box when pasta does, so a box whose pasta died stayed up without its network. Its reaper now ends it within a second or two, the box then dead as anywhere else.
recordworks where ffmpeg has no libx264 (#247, #442): Fedora'sffmpeg-freeand openSUSE'sffmpegleave libx264 out, andrecord startfailed with wf-recorder's "Failed to find the given codec". There it now records with openh264, which both distributions install with their ffmpeg: still an H.264 MP4, about 1.7 times the bytes at the same quality,--crf Nits fixed quantiser, no--crf 0(lossless), and at most 4096x2304's pixels a frame (a larger monitor is refused, a larger--monitor alllayout scaled down to fit).recordsays so at start and stop, andomabox doctorsays which encoder record uses. With neither,recordrefuses before starting, naming the packages that bring one.- A crash inside a box no longer shows as a crash notification on your desktop where systemd's coredump socket is in use (#441): systemd 262's socket (a fresh install's default) records a crash whatever the box's core limit, and Omarchy's crash watcher announced it.
omabox setupoffers a filter for what the watcher reads (a drop-in for its unit in~/.config/systemd/user, Omarchy's script untouched),setup --removetakes it away, andomabox doctorsays whether a box's crash would be announced. doctornames the right file for the desktop session's PATH off Omarchy (#247): its fix for a session that cannot find omabox named Omarchy's~/.config/uwsm/enveverywhere; on other machines it now names~/.config/environment.d/, which the systemd user manager reads.- A plain box's first shots no longer catch its screen zooming in (#247): Hyprland's default animation for a new output zoomed a plain box's screen in for most of a second after
upreturned, so a shot right after it was mid-zoom andshot --no-pointercould still show the pointer. Plain boxes turn that animation off (also formonitor add's outputs). - A plain box's shell may be a launcher that starts it and exits (#438):
up --desktop plain --shell 'caelestia shell -d'(orqs -d, or any script that starts the shell in the background) was taken as the shell exiting. The shell is now all its command starts, gone once nothing of it is left:upwaits for a layer of the shell's own (not any process's),restart-shellstops all of it, andpid shellandgdb shellfind the process it left. - A plain box keeps the config it started with across an omabox update: its desktop (
plain.lua) is copied into the box as the rest of its config is, andomabox reloadrefreshes both, so an update no longer mixes an old copy with a new file. setupanddoctorno longer suggestsetup --aquamarinewhere it builds nothing: for a Hyprland whose aquamarine omabox has no build for, they say what boxes use and what they go without.trayon a plain box says it has no shell, not--no-shell.protect-portson Debian and openSUSE (#439): omabox looked fornftin/usr/binonly, where those distributions do not put it, souprefused every connected box once the setting was on, anddoctorkept asking for nftables after it was installed. omabox now runs/usr/bin/nftor else/usr/sbin/nft(never one found on yourPATH), and refuses one another user could change.- Boxes on Debian and openSUSE (#247): no box started there (
bwrap: execvp /opt/omabox/share/session.sh: No such file or directory): a box's/lib64led where Arch keeps its loader, not where they do. A box's/bin,/sbin,/liband/lib64are now your system's own links into/usr. A plain box also hides Hyprland's "hyprland-guiutils is not installed" notice, which kept its screen from settling for 10 s. install.shandomabox setup --aquamarineon Hyprland 0.57 (#48): omabox's aquamarine build was for Hyprland 0.56 only (aquamarine 0.15.1), so on Arch and openSUSE, whose Hyprland 0.57 links aquamarine 0.16,setup --aquamarinefailed andinstall.shstopped there. It now builds the version your Hyprland links: 0.15.1 with the fix for 0.56, 0.16.0 for 0.57, each with omabox's fixes for interactive boxes (on 0.57 Hyprland puts the pointer on the right monitor itself). For a Hyprland it has no build for, it says so and boxes use your system's;install.shgoes on when the build fails, saying what interactive boxes go without.keyson a Hyprland config that leaveskb_variant,kb_modelorkb_optionsunset: xkb was handed Hyprland's[[EMPTY]]as their value and built no keymap, so everykeysfailed.- No "XDG_CURRENT_DESKTOP set from outside" warning in a box whose config does not set it: the box's Hyprland no longer inherits labwc's
labwc:wlroots. - The system's aquamarine is found on Debian, Fedora and openSUSE (#247): omabox looked for it in
/usr/libonly; now in/usr/lib64and the multiarch dir too. Andomabox setup --aquamarineinstalls its build where omabox looks for it there too (lib/, not CMake'slib64). omabox setupwithout Omarchy links no bar widget (#247): it says it skipped it, instead of making~/.config/omarchy/plugins.- Hyprland 0.57: layers that hold the keyboard, and special workspaces (#434): 0.57 renamed a layer's
interactivity, sokeys --windowtyped into a launcher that held the keyboard andtree --layercould not tell two same-size layers apart; and a special workspace has no id any more, so a window on a hidden one was listed on screen. Both read on 0.56 and 0.57. - A
--hyprland DIRbox knows its Hyprland's version (#424): the version written to the box HOME was asked without the folder's libraries, so a folder's Hyprland wrote 0.0.0, and the next Hyprland started in the box opened its update news. --versionandconfig --jsondescribe OMABOX_HYPRLAND's Hyprland (#424): with it set they named the aquamarine of the installed Hyprland, not the folder's that boxes load. They now say the folder's (kindfolder), and name the Hyprland (hyprlandin both--jsons).- Hyprland 0.57: a shot of a window that keeps resizing (#436): 0.57 fails a window's copy all through its size animation, so
shot --windowof a window resized over and over failed nearly every time. It is now tried for up to 4 s while the window changes size, with the window's own animations off after half a second of it, and back after the shot. - Hyprland 0.57: a turned monitor in
shot --burstandrecord(#435): 0.57 hands a turned monitor's frames over upright already, and the burst and wf-recorder turned them again: the screen squeezed into a band, a portrait monitor recorded sideways. A frame that already has the turned size is now taken as it is, on 0.56 and 0.57 alike. - The keys come back when a focused interactive box goes (#437): when the box's window was focused and nothing else on its workspace took focus,
downleft your Hyprland in omabox's submap (every key but the toggle swallowed) while another interactive box was still up: on Hyprland 0.57 with keys-to-box on and the pointer over the window, and on 0.56 too after the toggle key. A closing window no longer counts as the focused box. windowsno longer names Omarchy 4.5's notifications layer while it shows no toast (#431): every listing ended with that layer "spans the screen, possibly over" the windows, with nothing on screen; it stays mapped while idle and takes no input then. It is left out while the box's shell counts no toast (click --windowtoo, and aclick --waitthat times out no longer says the click was "possibly on layer omarchy-notifications"); with one up it is said, worded for what it is: "is full height at the right edge", in the click's warnings too.windows --jsongives each such layer aspan.hyprctl dispatchin the old syntax says it dispatched nothing, and the Lua for it (#427): a box's Hyprland runs a Lua config, wheredispatch fullscreen 0is run as Lua and does nothing but print Hyprland's note; in a--batchit even exited 0.omabox hyprctlnow fails it (exit 1 for a batch, hyprctl's own status otherwise) and prints theomabox lua 'hl.dispatch(…)'line for it: fullscreen, togglefloating, setfloating, settiled, workspace, focuswindow, killactive, closewindow, movetoworkspace(silent) and exec are translated; the rest are pointed athl.dsp. A Lua dispatch Hyprland refuses (no such window), which also exited 0, is now exit 1 with its answer as it came:omabox hyprctl dispatch'swarning: …(with-qtoo, and in a--batch) andomabox lua 'hl.dispatch(…)''s{"ok":false,…}, or a dispatch given no dispatcher, whichluaprinted nothing for. And anomabox luasource whose request came to a multiple of 1023 bytes no longer stalls the box's Hyprland for 5 s and fails ("Hyprland IPC didn't respond in time"), as Hyprland read it 1023 bytes at a time.
Deprecated
- Omarchy 4.0 goes by date, not in 1.3 (#312): omabox drops it in its first release after 2026-12-04, a month after Omarchy 4.5.0 reached the stable channel.
upandsetupnow sayomabox: deprecated: Omarchy 4.0.x: omabox's first release after 2026-12-04 needs Omarchy 4.5 or later (omarchy update brings it).
1.2.22026-11-05
One fix on top of 1.2.1: at a fractional scale, find --image names a shot -g crop's region where it was cut, and pixel reads each point's own pixel. Update.
Omarchy: as 1.2.1, Omarchy 4.5 and, deprecated, 4.0, on Hyprland 0.56.2.
Fixed
- At a fractional scale a crop is found where it was cut (#425):
find --image(andclickandwait image) named ashot -gcrop's region a pixel off, in the screen or a-gregion around it (66,59 62x16for66,59 63x16at 1.25), andpixelcould read a neighbouring pixel. Every path now maps layout and pixels the same way.
1.2.12026-11-05
Fixes on top of 1.2.0: a crash of an app built on Quickshell is said as itself, a box started before a rebuild or an upgrade says its helpers are old, a desktop on a .conf Hyprland config gets a clear refusal, and a shot -g crop at a fractional scale is the screen's own pixels. Also the decisions left open in 1.1.0's work: a scaled image's near tie refused, gpu auto past a software-only render node, and what up --stock keeps said. Update.
Omarchy: as 1.2.0, Omarchy 4.5 and, deprecated, 4.0. Tested on Hyprland 0.56.2, which Omarchy's package mirror serves; Hyprland 0.57 comes with 1.3.0 (#424). A visual check approved at a fractional scale from a shot -g crop may now differ slightly: its crops are the screen's pixels, where grim blended them (approve it again).
Changed
- A scaled image's near tie is refused (#267): when a template shot at another scale has one match and another place scores within 0.05 of it (a look-alike: "MARK ore" for "MARK one"),
click --imagerefuses it (exit 2, both places named,--indextoo),find --imagelists the match and says the tie on stderr and in--json'snear_tie, andwait imageis not satisfied by it. Measured across scales 1, 1.25, 1.5 and 2, a scaled template's score does not tell the image from a look-alike, so the 0.8 it needs stays. gpu autotakes a render node that renders (#396): a VM's virtio-gpu without virgl comes after any other, and when it is the only oneuprefuses it before starting a box that would die there (OMABOX_RENDER_NODEor thegpusetting naming it still forces it).up --stock --from SAVEsays the save's HOME stays (#265), under its stock line; the--stockhelp says your git name and email stay.- A pre-1.0
downmarker is no longer ordered by its file's time (#404): one of its start alone, in a tie, counts as a down that came, so theupis cancelled.
Fixed
- A crash of another Quickshell in the box is said, and its dialog named (#420): when an app built on Quickshell crashes, the next command says
a Quickshell in the box crashed since the last command (not its shell: CONFIG; report: PATH), once, never as the shell's. A click orshot --windowthat its crash dialog covers calls it Quickshell's crash dialog, whose, with its report and how to close it (the dialog takes the app's id as its class andquickshellas its title). The shell's own crash warning names its report too. - A box kept its helpers from before a rebuild or an upgrade, unsaid (#421):
upbinds each helper as one file, which keeps the old one when the host's is replaced.upnow records which file it bound, and a command that runs a replaced one in the box (keys,click,wait still,tree,events…) warns once:box 'B' started with older omabox helpers (keyboard, still), replaced on the host since: omabox down B, then up again. Boxes up before this release say nothing. - A desktop whose Hyprland reads a
.confconfig gets a clear refusal (#422): interactive mode,peekand keys-to-box act on your Hyprland with Lua, which a.conf(hyprlang) config does not run, and they failed with Hyprland's raw answer. They now say that they need a Lua config (hyprland.lua) and that headless boxes work as they are;up --interactivesays it before it makes anything (it left a dead box), anddoctorwarns of it (host-config, read from Hyprland's status, nothing sent). - A
shot -gcrop at a fractional scale is the screen's own pixels (#423): at 1.25 or 1.5 a region that did not start on a whole pixel (30 at 1.25 is 37.5 px) was resampled by grim, sofind --image,click --imageandwait imagemissed a crop taken in the same box (GTK text 0.82-0.93 against the screen it was cut from, under the 0.95 it needs). Such a region is now taken from a whole pixel and cut there, byshot -g(--zoom,--burst,--grid --celltoo),find -g,pixelandwait change --sincea crop; the region it records, its image size andclick --inare as before, and a small crop's scale comment is its screen's.
1.2.02026-11-05
Omarchy 4.5.0 final, and Omarchy 4.0 deprecated: up and setup say so on a deprecated: line, and omabox 1.3 drops 4.0, not before 2026-12-02. Also omabox's test suite as a package installs it (/usr/lib/omabox/test/run.sh) runs on any machine, and a package build's cargo test passes in a container. Update.
Omarchy: 1.2.0 supports Omarchy 4.5 and, deprecated, 4.0. 1.1.0 planned to drop 4.0 here (#312); it moved to 1.3, four weeks after 4.5 reached Omarchy's stable channel (2026-11-04), so that users on stable have time to update (omarchy update).
Changed
- A clean box no longer binds its
shell.jsonover Omarchy's defaults on Omarchy 4.5 (#410). The bind kept the frozen clock from a race in Omarchy 4.0's shell, which 4.5 fixed; on 4.0 it stays.
Fixed
cargo testfailed in a container without user namespaces (a package build'scheck()):a_bound_home_is_usednow skips its namespace half whenunshareis refused, as when it is missing.- The installed test suite failed on any machine but omabox's own (#413, #414, #415, #416, #417): a fresh session's guard mark taken for a leak,
up's goldens holding that machine's facts, a fixture bind under /usr thatuprefuses, a wait check that compared two waits' answers, and a crash check that assumed which thread a signal lands on.
Deprecated
- Omarchy 4.0 (#411):
up(once the box is up) andsetupsayomabox: deprecated: Omarchy 4.0.x: omabox 1.3 needs Omarchy 4.5 or later (omarchy update brings it)on stderr when the box's Omarchy (yours, or--omarchy's tree) is older than 4.5. Not refused underOMABOX_STRICT=1: nothing in the call can change it. omabox 1.3 drops 4.0 (#312), not before 2026-12-02: four weeks after Omarchy 4.5.0 reached the stable channel, not in 1.2.0 as 1.1.0 planned.
1.1.02026-10-31
New ways to drive and check a box: run -d jobs listed, stopped and waited for (jobs, stop, wait job, wait log); waits and checks on the accessibility tree (wait tree, --expect tree, --wait --tree) and on a picture where there is none (find, click and wait --image); click --find; window --size; tray; dnd and dock; doctor; plugin add; up --stock and up --polkit; shot --grid; checkpoints with proofs and check run --only; record --crf and frame-by-frame sheets; omabox pid; and the skill pre-approves the commands that stay in a box. Also security hardening (S1, S8 and S10 held more tightly, signals through pidfds, a box's text made safe for your terminal, output paths a box cannot redirect, ImageMagick reading only PNGs) and many fixes, among them an up with another XDG_RUNTIME_DIR that deleted the HOMEs of boxes still running. Update.
Omarchy: 1.1.0 supports Omarchy 4.0 and the 4.5 release candidates. Dropping 4.0 waits for 4.5's release (#312, planned for 1.2.0).
Added
omabox jobs,omabox stop PID,wait jobandwait log: arun -djob is listed, stopped and waited for by its pid, with nopgreporkillon the host (where the same program may run on your desktop).run -dsays the job's pid;jobs [--json]lists the running ones (pid, age, processes, log, command);stop PID... | --allstops one as--replacedoes, its windows gone, by its pid or a window's;wait job [PID] [--gone]until it ends, with its exit status;wait log [PID] RE [-i]until a line of its log matches.--replacewith other arguments now says the new job starts beside the one still running, and theomabox stop PIDthat stops it (#299).wait log LOG RE [-i]waits for a new line in a box log, bylog's names (shell,hyprland,apps,journal, ...), aswait log [JOB] REdoes for arun -djob's: a plugin's line, Hyprland's own (from its rolling log, since its file is written late); RE also as--grep RE. A line already there does not count, and a 124 says when one was;--since OFFSETreads from a byte (--since 0: the whole log), and--json'soffsetis where the line found ends, for the next wait. A log begun anew meanwhile (restart-shell's) is read from its start.wait for DURATIONis a fixed wait that says it is one, for agents whose harness blockssleep: no morewait until -- falseas a sleep (#330).wait tree TEXT [--window SEL | --layer SEL] [--gone] [--shot FILE]waits for the accessibility tree to hold TEXT, matched astree --findmatches it: satisfied at the first read holding it (a toast or a sheet that lasts a second is caught),--gonewhen two reads in a row do not,--shot FILEa shot the moment it holds. A 124 says what the tree had instead. And--expect tree TEXTonkeys,click,scrollanddrag --wait: once the screen settled, the tree must hold TEXT, else 124, so a chain of steps stops when one's effect is not the one wanted.tree --find(and both of these) takes TEXT's[STATE ...]as a set:"Dark mode" [checked]finds a box that is[focused checked](#319).--wait --treeonkeys,click,scrollanddragsays what changed in the app's own accessibility tree: the window's tree is read before the input and again once the screen settled, and the line ends with "no change in the app's tree" or "the app's tree: N changes", one line each under it (20 at most):entry "Name": '' → 'hello',check box "Beta": +checked -unchecked,label "Idle" → "Saving",+ dialog "Confirm" (and 3 inside). Nodes are known by their ancestry, role and name, not their place, so a row put first is one row added. A password field's text is never shown.--jsonaddstree. Opt-in: it costs a read before the input (#288).find --image FILE,click --image FILEandwait image FILE [--gone]find what has no accessibility tree (the bar, the shell's panels, plugins, terminals) by its picture: a crop of a shot (shot -g "X,Y WxH" -o FILE). Each match is a lineX,Y WxH SCOREin the layout's coordinates, a text line where a shot cost ~1.5k tokens; several are all listed in reading order, andclick --imagerefuses them (exit 2,--index Npicks one);--offset DX,DYclicks beside the match.--similar(0.95) is a colour correlation that also falls with another contrast or tone, so a greyed or switched-off copy does not pass; transparent pixels are not compared, and the pointer's place is left out. Each shot records its scale in its PNG comment, and a crop shot at another scale is resized to the box's and said.-gor--window SELnarrow the search (#267).check point --expect-image FILEproves a checkpoint by a picture where there is no tree: it fails the checkpoint whenfind --image FILEfinds no match on the screen (or in--window's own pixels), as--expect-treedoes for a tree (#267, #266).click --find TEXTclicks what the accessibility tree names TEXT, with the real pointer at the middle of what of it is in view, read fresh on every call: notree --find, then working out the middle by hand. An exact name wins over a part of one, and a control over a label of its name; several in view is exit 2 with their lines, numbered for--index N. A hidden node, one with no bounds, one scrolled out of its container and a disabled one are refused, saying which, and nothing is clicked.--window SEL(none: the active window) or--layer SELfor the shell's layers. Thanks to @btsouth (#408, #318).treenames an unnamed control after its label (LABELLED_BY), so--find Emailfinds the entry its label names, and reads a node once when it sits under two parents (Qt WebEngine) (#318).click --in SHOTrefuses when the screen changed at its point since that shot: a click, scroll, drag or pointer move--ina screen shot is refused (exit 1, nothing sent) when what is at the point is not what was there at the shot (a menu or dialog over it, another window, the window moved or resized under it), saying what it was on then and now and what changed since; take a new shot. A change elsewhere on the screen (a toast, a clock, a window away from the point) is not refused. A window's shot follows its window as before (#333).wait change --since SHOTandwait still --like SHOT: the screen against an earlier shot.--sinceis satisfied at once when the screen (-g: part of it; a window's shot: that window) already differs from SHOT, so a redraw done before the wait started (after an edit to a file the shell applies, an IPC call) is no longer missed, else at the first change;--likewaits until it looks like SHOT again. The pointer, a caret blinking alone and--ignore's regions are no difference (#344).omabox window --size WxHfloats one window of the box at that size, centred, wheremoderesizes the whole screen: an app checked at a narrow width, again at another.--window SELtakes the same selectors asclick --window(none: the active window); it prints the window as it is then, and a size the app did not take (its smallest or largest) is exit 1, saying the size it took.--floatfloats a window as it is,--tiletiles it again,--jsongives the window aswindows --jsondoes (#362).wait layersays which monitor a layer is on:… at 0,0 1920x1080 on HEADLESS-2, each one when there are several (a bar on every monitor), and--json'sdetailhas it.wait layer NS --monitor NAMEwaits for one on that monitor (--gone: none left there); a monitor the box does not have is said, with the ones it has.windowsnames the monitor of each layer under its table, andwindows --json'slayershavemonitor(#316).omabox traylists the box's tray items and their menus, read over the box's own session bus: each item's id, title and status, and its rows astreewords them (check menu item "Sync" [checked], a submenu's rows under it, [disabled]);--jsonfor scripts.tray click ID LABELclicks a row by its label, as the bar's menu does, and prints it as the app has it after (several alike:--index N; a hidden, disabled or submenu row is refused).tray menu IDopens one item's menu as a host does,tray activate IDis a left click on its icon (--secondarya middle one). No pixels: Omarchy's bar publishes no place for its icons, so where a real click on one lands is still found from a shot.tray menu,activateandclickare actions forshot --burst --afterandrecord -- ACTION. What an item says of itself is printed plain (an escape sequence in its name or a label never reaches your terminal); one call reads at most 64 items, in 15 s at most, and says what it left out (#343).omabox dnd [on|off] [--clear]andup --dnd: the box's Do Not Disturb, in its own Omarchy shell, so no toast lands over a window between steps;--cleardismisses the toasts up.omabox dock [on|off]andup --no-dock: whether Omarchy 4.5's dock takes input in the box, per monitor, and its service off or on.windowsandclick --windowno longer name the dock where it is hidden (a workspace that is not floating), since it takes no input there (#309).- Input under a layer spanning the screen is narrowed to where it draws: Omarchy's notifications column and dock take input on their items only, and
click,scroll,dragandpointer --windowsaid "may go to it" at every point under them. Now the box compares the screen with the window's own pixels there: on a toast (or a dock icon) the layer is named as over the point, and--no-raiserefuses; far from one, nothing is said. A click at the screen's X Y names it on a toast too. Where the pixels cannot tell (a scaled output), the "may" stays (#283). - A click, scroll or drag at the screen's X Y says a layer over the window there, as
--windowdoes, when the layer certainly covers the point: a panel or menu over it is named on stderr before the input is sent (never refused). A layer spanning the screen (Omarchy 4.5's notifications column, its dock) is not said there, since it takes input on its items only (#361). omabox doctor [--json] [--smoke]says whether this machine can run boxes, changing nothing: Omarchy and your theme, Hyprland (0.56+, Lua), the aquamarine boxes use, labwc, quickshell, bwrap (0.11+), pasta, grim, the programs a box runs, omabox's tools, user namespaces, the render nodes and the one a box uses, socket path length, and which omabox your shell's and your desktop session's PATH find. Each failure or warning has a fix line for your distribution's family (Arch, Debian and Ubuntu, Fedora, openSUSE); exit 1 when something fails.--smokealso starts a box, takes a shot and takes it down (#320).omabox plugin add PATH|IDputs a shell plugin into a box that is already up, asup --pluginwould have: read-only, linked where the box has it at its own path or mounted, the shell made to know it and enabled, its state said (ls --json: plugin_status).plugin remove IDtakes one out. A link made by hand in the box HOME, thenomarchy plugin enable, said "is not known": the enable ran before the shell's rescan was done (#345).up --stock: Omarchy as a new user sees it, for a showcase or a shot for someone else: Omarchy's bar on tokyo-night (or--theme NAME) with the theme's own wallpaper, English in UTC, and nothing of your desktop's look (terminal configs and choice, branding, your themes and wallpapers, the plugins' settings, Hyprland toggles, fonts); the clock live, animations on, the network and pointer as in any box.--plugin,--theme-dirand the rest work on top;ls --jsonsaysstock(#265).up --polkit: a polkit agent can be tested in a box. The shell's polkit plugin (or a copy of it under test, or a GTK or Qt agent) registers and shows its dialog as on a desktop: the box gets a system bus of its own, never your system bus or polkitd, on which only polkit's name can be owned, taken by a stand-in authority.omabox polkit ask [--action ID] [--message TEXT] [--accept PASSWORD] [--timeout 60s] [--delay DURATION]makes a request and says how the agent ended it (authenticated, cancelled, timeout, the agent gone), with the passwords tried and how many were wrong;--acceptnames the one test password the box's helper takes.omabox polkit agentslists who registered;log polkitis the authority's log. It decides nothing for any service (pkexec and pkcheck get no answer from it). That bus is the box's (a process in the box can answer in the stand-in's place), so whatpolkitprints of its answers is bounded and plain: an escape sequence in it never reaches your terminal (#258).shot --grid Ndraws N lettered columns and N numbered rows over a shot, the labels in a margin so nothing is hidden, and names each column's and row's span on stderr: aim at a small target on a surface with no accessibility tree.--grid N --cell C3is that cell cropped, enlarged and gridded again (--cell C3:D3for a target a line cuts), andclick --in GRID.png --cell C3clicks a cell's middle;click --in GRID.png X Ytakes the margin off (#268).check run --only ID,GLOBchecks only the named checkpoints, while you work on one screen: the baseline's others are skipped (counted, not missing),check pointtakes no other, and a scenario skips whole sections withomabox check wants ID...(the list is also inOMABOX_CHECK_ONLY). A name that matches none of the baseline's is refused before a box starts.--approve --onlyreplaces those checkpoints and keeps every other one as it was (#376).- Proofs on a checkpoint:
check point --expect TEXTsays in words what that screen must show, kept with it and said under its line incheck runand--approve, on its cards inreport.pngandbaseline.png, and in--json, for whoever judges a change or a baseline.--expect-tree TEXT(atree --findof its--window) and--expect-cmd -- CMD...(run in the box) are checked: a failed one is its own result,proof ID: proof failed: ..., even where the pixels are the baseline's, and--approvekeeps no run where it failed, nor anything when it failed in every run (#266). --report-scale N(check run,check diff --report) also draws the report for people,[email protected]([email protected]at--approve): the same layout N times its size, crops at the shots' own pixels on a box of scale N.report.pngstays sized for an agent at any box scale (#402).record --crf Nsets the video's H.264 quality (18 by default) for footage that will be zoomed or encoded again:record start --crf 8, or with-- ACTIONand--for. It holds with--cut-idleand the overlays; 0 is lossless (a profile browsers do not play, said at stop) (#278).- A contact sheet of a stretch of a video, frame by frame:
record sheet(andstop --sheet) take--from T --to T,--every-frame,-g "X,Y WxH"(that region of each frame, small ones enlarged pixel for pixel) and--changed(the frames where the region changes), each tile labelled with its time to the ms and its frame number (#260). record sheet VIDEOneeds no box: with none named and none up, ffmpeg reads the video on the host in a sandbox of its own (no network, no display, only the video) and makes the same sheet (#279).omabox pid [hyprland|shell]prints the host PID of a box's Hyprland (the default) or its shell, for/proc/PID/maps, perf or strace;--in-boxthe PID as the box numbers it,--jsonboth. Nothing on stdout and exit 1 when it is not running (#331).- Who started a box, and who took it down (#295). A session's subagents share its default box name.
lsnow says under each box where it was started and by which agent session (and who used it last, when another);downof a box another caller started or used in the last 10 minutes warns that it may be another agent's (it still takes it down); and the name's next command says when another caller'sdowntook it and from where, not justno box is up(a caller's owndownleaves nothing to say: its nextrunstarts a throwaway as before). runsays when its command names a host path the box sees elsewhere or not at all, before it runs: the box HOME's host path (omabox path --home, the logrun -dprinted) with its path in the box (/home/sbx/…), a file in a--pluginfolder with where the box has it, a scratch file in the host's/tmpor a build dir inLD_LIBRARY_PATHwith the mount that brings it in (not the dirs ofPATHorXDG_*_DIRS, where a missing one is normal).run -dnames its log as the box has it too (/home/sbx/run-NS.log), andupsays where a--pluginfolder that is not at its own path is in the box (#301).- An app that died of a Wayland protocol error says so. Where omabox says a
run -djob ended (its first moments,run -d --wait, the next command's warning), a log holding libwayland's line for it adds "its Wayland connection was closed for a protocol error: xdg_surface#12: error 3: …". GTK and Qt apps, which write their own line instead, get theirs, said as a protocol error only when it says so, else as a lost or failed connection. Await windoworwait layerthat gives up now says a job that ended meanwhile itself, instead of leaving it to the next command (#335). - The skill pre-approves the omabox commands that stay in a box (Claude Code's
allowed-tools):shot,windows,tree,keys,click,wait,logand the rest that act only inside a box and read none of your files run without a permission prompt while the skill is in use.up,run,down,host,peek,configand the others that can reach your desktop, your files or other boxes still ask. The skill's reference says which, and what Codex and OpenCode take instead (#338).
Changed
up --cleanis--stockplus its freezes, so the two cannot drift apart: a clean box now leaves out your terminal configs, branding, themes, wallpapers, plugins' settings and Hyprland toggles too, and--keep wallpapergives the theme's own wallpaper, not yours for it (#265).- Only one part of omabox talks to your Hyprland, in words it builds itself (S8): the rest reads it through a fixed set of
-jqueries, and acts on it only by a window openedsilenton the configured workspace without focus, a box's own window floated, sized or moved by its address, or the passthrough's hooks; a focus is made only forpeek --focusandomabox host, which you ask for. Nothing omabox sends changed: what it can send is now held by construction, and the suite checks it (#366).
Fixed
- An
upwith anotherXDG_RUNTIME_DIRdeleted the HOMEs of boxes still running (a test's stand-in runtime dir, another login, with the same cache). A box HOME now records the box it was made for, and goes only once that box is gone where it was made and nothing uses the HOME; an older omabox's HOME only when nothing uses it. Anupof a name whose HOME is another box's is refused instead of taking it. up's check of the started box's own mounts (S1) looked only at where each mount is: a/dev/drifolder bound whole, a seat path bound somewhere else, and a mount inside the runtime dir's path got by it. It now also names each mount's source on the host (a seat path at any destination, or a folder that holds one, ends the box), lists the box's/dev/dri(every card there must be the empty placeholder file), refuses a mounted card or input device by its number, and refuses any mount under the runtime dir's path.upnever made such mounts (its binds refuse them as they are added): this is the second line behind that one. WithXDG_RUNTIME_DIRoutside/run,--ro-bind DIR:DESTwith DEST inside it is now refused (#363).downsignals the box's processes through pidfds: the continue it sends the commands that entered the box, and the kill of its PID 1, pasta and peek windows, went by pid number after the check that they were the box's, so a pid reused in between (a stopped job of yours) could be continued or killed; so didsave's pause of the box,run --replace's stop of the earlier job,shot's end of a stuck capture andlog -f/events -f's of their followers. Now each goes to the process that was checked, or to none (#377).protect-portsmissed an address the host gained after a box started: a server on all addresses on a protected port was reachable from a connected box through a VPN or docker network that came up later. The box's reaper now keeps the rule on the host's addresses as they change, within a few tens of milliseconds (a failed update is tried again after 250 ms, then up to every 2 s while it fails; a hung nft is killed), and drops the ones the host loses (#399).config protect-portssaid nothing about boxes up already: they keep reaching the ports they could reach at their start. Changing it now names the connected boxes that need a restart, and warns whennft, which the rule needs, is missing (#374).calibrate CARD --answerran what CARD's name told ImageMagick to: a card namedmsl:FILEran an ImageMagick script, which can write files. The card is now read as the PNG file it is (a link to one is no card), and every file omabox gives ImageMagick is read as a PNG (#338).shot -o FILEwrote over any file there, through a link too, as diddrag --shot,calibrate CARDand a burst's frames in-o DIR. They now write over only an earlier image or an empty file, and refuse a link, a folder or any other file, saying why, before anything is written; a new path is made as before (#338).shot -ointo a box's HOME could be sent elsewhere: a box that swapped a folder on the way for a link between omabox's checks and the write had the shot written where the link pointed. The shot is now made and renamed in the folder omabox checked, held open (#338).shot --burst --after -- run --env-file FILEread a host file into the box command's environment through a shot. The action now refuses--env-file(--env KEY=VALstill goes), so a pre-approvedshotreads none of your files (#338).- Inside ai-jail, a link in the project to a file outside it had that file opened before it was refused. It is now refused before anything outside is opened, and a plugin's manifest or a
.gitfile read there is read up to 1 MiB (#367). - An INT, TERM or HUP while
upmade its box dir could leave a box dir with no box.json: the stop's cleanup ran alongside up's own work instead of after it. It now waits for that step (at most 10 s, said as a stop that waits is said) (#367). - A
downfrom another pid namespace (a container of its own) could miss theupit raced: an up started a moment before it, but slower to get going, was taken for one started after it, and its box stayed up. The two are now ordered on one clock all pid namespaces share. A jailed agent'supnow counts from its own call, not from when the broker took it up, so yourdownin between cancels it; andup/downin a pid namespace that shows the host's/procread their own start, not the host init's (#404). - A
downby another omabox left the box's reaper running (a package'sdownof a box a checkout started, or another worktree's) until its next look. The reaper now records its pid in the box's folder, anddownends it whichever omabox started it (#383). - A
savekilled with SIGKILL (or by the OOM killer) during its copy left the box paused, read as hung until someone resumed it by hand. A watch the save starts in a session of its own now resumes the box when the save dies without letting it go (#369). - A box whose Hyprland crashed was sometimes said to be hung ("did not answer (hung?)"): on a loaded machine while the crashed Hyprland was still exiting, and when the box ended in the moment between two of a call's looks (
omabox lua, any call to its Hyprland). One whose exit is under way now reads as going, and the command says the box went down and how, with its signal (#222, #351). - A window shot failed with "grim failed: it ended with status 139" when the window changed size during it (just resized, or shown at a new size): Hyprland fails such a copy, and grim 1.5.0 then crashes. The window is now taken again, up to four tries, and one that keeps failing says why (#387).
- A click at the top of a fullscreen window was reported as on the bar:
--wait's answer and--json'stargetnamed a top layer (Omarchy's bar) over the point,certain, where a window in fullscreen covers it and takes the click. Overlays still count (#409). tree --layercould not read an Omarchy 4.5 bar popup: the popup is a full-screen layer, the size of the wallpaper (and of 4.5's bar), so it refused with "which one is the layer's cannot be told". The popup is the one of them that takes the keyboard (on demand, not exclusively, which was alltreelooked for), so its tree is read now, and the wallpaper's and the bar's say they publish nothing (#315).treeon a Chromium or Electron window started without--force-renderer-accessibilitysaid it was not on the accessibility bus with a reason about egui apps; it now says it is Chromium's or Electron's and to start it with the flag (#323).treeplaced a Qt dock widget's contents relative to the dock: Designer's filter field said@4,4, drawn at 4,88, so a click at its middle missed. They now have where they are drawn, as a Qt Quick dialog's contents do (#318).treeprinted no text for an editable combo box (an input with suggestions in Chromium or Qt WebEngine), so a typed value could not be read, found by--findor seen in--json. It is now its'text'; a closed select still says its choice as=value(#341).- A small blinking or pulsing dot timed every
wait stilland--waitout, and an--ignoreof it stopped matching once a re-layout moved it. A spot 48 px a side at most whose changes keep bringing it back to how it looked (a dot blinking or pulsing, a looping spinner) now counts for its first few changes and is then left out as a blinker, said on stderr and in--jsonasblinking, and learnt again wherever it moves. A counter or a progress bar never looks as it did before, so it still counts;--strictcounts blinkers too (#307). helpand the skill say thatshot --windowcuts off a menu past the window's edge: a window shot is the window's box, and Hyprland says nowhere where a window's popups (a GTK or Chromium context menu, a dropdown) are, so it cannot grow the shot to them. Take the screen around the window withshot -g, or a whole shot (#334).- A box has
/var/tmpand/var/lib, and its/runis 0755 as on a host:mktemp -p /var/tmp, a mount over/var/libin a namespace of the program's own and a check of/run's mode failed in a box only. Six of Omarchy's own tests that failed in a box pass now (#322). timedatectlanswers its read-only questions in a box (list-timezones,show -p Timezone): it failed for want of a system bus, so Omarchy's Elsewhen panel had no zone list and no local zone. Setting the zone still fails: the clock is not the box's to set (#322).- A Hyprland started inside a box opened Hyprland's update news over its first frames: the box HOME now records the box's Hyprland version, as a desk's does after its first session (#322).
- No "plugin X disabled: listed but not enabled" for a plugin that is running. A service with a bar widget, loaded from its own
plugins[]entry with its widget off the bar, now readsloadedwith no warning. A widget in no layout of the box's shell.json while another mounted plugin runs (one that may place it through its own config and IPC) gets a note naming that plugin, not a warning (plugin_status:off the bar); with none, the warning says "not in the bar's layout" and gives theputBarWidgetcommand that puts it there (#326). run's note "WORD is relative to DIR" fired on words that only share a folder's name: from a checkout with astashfolder,run -- omarchy-shell stash moduleswas told to restart the box with--overlay. A word now counts only when it reads as a path (a/in it, the command itself,cd's folder) (#325).- A
run -djob stopped withomabox run -- pkillwas still warned about when it exits with a code of its own on SIGTERM (foot exits 230). A job that ends while arunthat kills runs (or just after) is no longer said, whatever its status; the warning's hint now reads(log: omabox log -b NAME run)(#329). - A foreground
runand a plainpathskipped the session's box: run from another directory,runquietly started a throwaway box andpathprinted the folder of a box that was not there. Both now name the session's boxes, asrun -ddoes;omabox helpsays how the box is picked without -b (#327). - A bound folder deleted and made again on the host showed empty in the box, with every command succeeding.
runnow says so once, with what to do (#391). - Inside ai-jail, a project folder without
.gitsilently gave a box with no project:up(and a throwawayrun) started fine, the box had none of the folder's files, and nothing said why. It now says the folder is not a git repo and that--ro-bind DIR(or--overlay) brings it in (#394). - Ctrl-D at one of
omabox setup's questions ended it silently (exit 1). It is now a no, said so, and setup goes on; a Ctrl-D at the widget's question is not remembered as a no (#373). - The agent guard refused
omarchy plugin listnamingomarchy-shell, a command the agent never ran. When one of Omarchy's commands calls it, the guard now names that command, and foromarchy plugin listsays where the installed plugins are (#332). - A Hyprland notification looked missing from shots:
hyprctl notify(and Hyprland's own warnings, such as the monitor-layout one) draws at the top right of the focused monitor, so a shot of the screen's left never had it.omabox hyprctl notifynow says where, with theshot -gof that corner, and the reference says it (#359). omabox logmissed Hyprland's latest lines: Hyprland writeshyprland.log8 KiB at a time, so what a reload or a plugin just logged was often not in the file yet, andlog --grepfound nothing as if it never happened.log hyprlandof a live box now adds the lines past the file's end fromhyprctl rollinglog; when the file is further behind than rollinglog's last 4 KiB reach, it says so on stderr (#328).upon a GPU a box cannot render on said only "died while starting": on a VM's virtio-gpu without virgl the reason was only inlabwc.log. It now says a box needs GPU rendering and that the node renders in software only (or has no EGL), how to give a VM 3D, and another GPU when the machine has one (#396).
1.0.22026-10-30
Omarchy 4.5.0-rc2 support for click, windows and tree --layer (its bar now spans the screen), and a batch of smaller fixes: wait until with a command the box cannot run, tree names past 80 characters, check point regions, back-to-back runs. Update if you run the 4.5 release candidates.
Fixed
check point -gkept the region as typed:-g "010,010 400x300"went into the checkpoint as010,010, so the same region typed another way (10,10,400,300) read as a different one. It is now kept as read,10,10 400x300, asshotdoes (#384).shot -o x.ppmwrote a PNG without a word: shot writes PNG whatever the file is called. It now says so on stderr when the name is another image format's (.ppm,.jpg, ...), andhelp shotsays how to convert one (#346).check point --ignorepartly outside the shot was cut down without a word: a region given in the wrong coordinates was kept as a sliver. It now says what was kept, andcheck run --approve's "with regions left out" counts the checkpoints with--ignoreregions too (#342).tree --jsonand--findsaw names and text cut at 80 characters: a status line whose end mattered could not be found or read. They now see them whole (up to 4000 characters); the text view still cuts them at 80, ashelp treenow says (#314).- A box whose
usedfile was removed never went down for idleness, and a folder in the runtime dir that no box can be named madelsexit 2 with nothing listed. The reaper now counts the idle time from when it finds the file gone, andlsleaves such a folder out, saying so (#371). - Back-to-back
runs got slower: each kept a marker file for 10 s, and every run read them all. Runs close together now share one, so thousands in a row cost the same each (#392). wait untilwith a command the box cannot run retried it to the timeout, and never showed why. A command not found (127) or that cannot run (126) in the box now ends the wait at once ("unknown", exit 1); a wait that did not succeed shows the last lines of the command's stderr; and a command naming a host path the box cannot see (this box's folder, your$TMPDIR) is said before waiting (#400).- On Omarchy 4.5.0-rc2 every
clicksaid it "may go to omarchy-bar": the bar's surface now spans the screen, taking input on its strip only. omabox now takes the bar as that strip, along the edge it reserves (#407). Andtree --layer omarchy-barrefused as ambiguous (the bar and the wallpaper, one size): two frames with nothing in either now read as a layer that publishes no accessible items, as one does.
1.0.12026-10-27
Fixes for what an upgrade from 0.x runs into, and a security fix: a box could take a port on your protect-ports list while your own service on it was down (S10). Update.
Upgrading from 0.x: while ./install.sh builds the new omabox, the bar widget still running from the old one can notify "omabox: cannot list boxes". That goes away by itself once the install is done.
Fixed
omabox guard onandoffleft one moresettings.json.bak-*each time: they now keep only the newest backup of each file and say how many older ones they removed, also when the guard is already on or off, so the upgrade (whoseinstall.shturns the guard on) clears the ones earlier versions left. Backups of your own (settings.json.bak,.bak-mine) stay.setup --removenames the backups it leaves. Thanks to @btsouth (#403, #398).- A box could take a protected port while your service on it was down: pasta still forwarded the box's servers on
protect-portsto your127.0.0.1, so a box listening there took the port and your browser'slocalhost:PORTreached the box. Protected ports are now left out both ways. And a missing or failingnftno longer shows as "bwrap did not start" after 10 s:uplooks for it in/usr/bin, where the box's start runs it, and says at once when setting the rule failed, with nft's error (#364). run --passfrom an agent in ai-jail started before the upgrade exited 2, as if its command had: the jail still had 0.x'somabox-relay, which does not know how 1.0 hands it the values. It now exits 125,run's own, saying to restart the jail; the relay's own usage errors arerun's 125 too (#380).omabox broker offleft the broker's socket file behind in$XDG_RUNTIME_DIR/omabox/.broker/: the socket unit now removes it whenever it stops, andoffremoves it (and.broker/, when nothing else is in it) itself, so the firstoffafter upgrading also clears what an earlier version's unit left (#393).omabox setup'somarchy plugin enable chaves.omaboxline failed when run right after it ("plugin 'chaves.omabox' is not known"): the running shell had not yet seen the widget setup just linked. setup now has the shell rescan its plugins, asomarchy plugin adddoes, and waits until it lists the widget, so the line works at once; a shell that still does not know it after 4 s gets a line that names the rescan too (#397)../install.shwithout a terminal:--check's failure named box logs that its own cleanup had just removed; they are now kept in~/.local/state/omabox/install-check/. With missing packages and no terminal for sudo, it prints the exactsudo pacman -S --needed …line to run, then./install.shagain, instead of sudo's own error. A machine whose only render node renders in software (a VM's virtio-gpu without virgl) is told up front that a box needs GPU rendering, instead of the box dying "while starting" (#395).
1.0.02026-10-27
omabox is one Rust binary now, with the same commands, options, output and exit codes as before except where this section says otherwise ("Changes from the bash omabox" lists each). What scripts and agents branch on is kept from this release on: exit codes and --json fields stay as they are within 1.x, or change only by addition, and a command, option or variable that has to change warns for one minor release first (omabox: deprecated: …, naming the new form) before it is refused. README, "Stability", says what that covers and what it does not (message wording, help text, defaults and heuristics, image pixels, what other programs report through omabox). The forms 0.9.0 deprecated are refused now, and a region given beside --window is the window's everywhere. Also: protected ports no box reaches, boxes at home on Omarchy 4.5 (1.0.x keeps working on 4.0; 1.1 will need 4.5), and the fixes from a review of every rule in SECURITY.md.
Upgrading from 0.x: take your boxes down (omabox down --all), then git pull && ./install.sh in one go: it now builds omabox, and needs Rust (it installs Arch's rust when there is no cargo). Restart any agent running in ai-jail. Every path in your HOME stays where it was.
Added
- Protected ports:
protect-ports=8080,5432in~/.config/omabox/confignames host ports no connected box reaches, on the host's loopback or through any of its other addresses (a docker bridge, a VPN), TCP and UDP; an isolated box's--allowrefuses them. None by default. Needsnft(nftables) when set. A value that is not a list of ports refuses everyup(exit 2) rather than being ignored. Set it withomabox config protect-ports 8080,5432(checked asupreads it, kept sorted;defaultremoves it);omabox configlists it,--jsonasprotect_ports(#355). OMABOX_STRICT=1refuses a deprecated form at once (exit 2) instead of warning, for CI. Every deprecation warning from 1.0 on startsomabox: deprecated:and names what to write; 1.0 itself has none (#287).
Changed
- omabox is one binary, built by
./install.sh, which now needs Rust:bin/omaboxis a link tobuild/omabox, built fromcrates/omabox(install.sh installs Arch'srustwhen there is nocargo; the first build fetches its crates). Pull and run./install.shin one go: until it has run,omaboxis missing, new agent sessions start without the guard, and ai-jail with omabox's maps does not start. Take boxes down before the upgrade, and restart agents running in ai-jail. Every path in your HOME (~/.local/bin/omabox, ai-jail's maps, the broker's unit, the guard's hook) stays as it was; what changed beside it is under "Changes from the bash omabox" below (#324). - An interactive box's monitor windows have a class of their own:
aquamarine-omabox-<token>where it wasaquamarine(the box's first window keepsaquamarine), each with a host rule of its own that keeps it on the box's workspace, silent, and stays until your Hyprland next reloads its config, so those windows stay drawn while hidden. A rule of yours matching^aquamarine$no longer applies to them;^aquamarinematches both.monitor addon an interactive box andup --interactive --monitorneed omabox's own aquamarine build for this: on the system's aquamarine, or in a box started before you rebuilt it or by an older omabox, they are refused, saying so (omabox setup --aquamarine, then a new box). Twomonitor adds on one interactive box now take turns (the box's lock: the second waits up to 60 s, then says the box is busy) (#349). - Beside
--window,-gand--ignoreare the window's own coordinates everywhere (0,0 its top left corner), asclick's X Y,shot -gandcheck pointalready were:wait still|change --window SEL --ignore, and--wait's-gand--ignorebeside--windowonkeys,click,scrollanddrag. 0.9 took them in the screen's, with a warning. A 124's--ignore "X,Y WxH" if that is an animationgives the window's coordinates there too. To watch a part of the screen whatever the window,-gwithout--window. - The skill's reference says a box turns PipeWire's realtime module off for its clients, which hides a realtime-limit bug, and how to run one client without that (#305).
- The reference says plainly that wgpu apps (eframe's default renderer, iced, Bevy) do not start in a box on NVIDIA, and what to do: a GL renderer, or a box on the AMD/Mesa GPU (#306).
- Parallel subagents of one session share its default box name: the reference tells each to take a box of its own (
up --newor-ba name of its task), andomabox briefto take down no box it did not start (#295). - Where box windows open: the widget's Settings offers workspaces 1-10 and Its own (special:omabox), a special workspace of omabox's: full size, opened by the widget's Show, hidden by a workspace switch. It no longer offers the scratchpad, which Omarchy 4.5 made its Quake console (a half-height panel that starts the default agent when it opens empty).
specialstill works (--workspace,omabox config workspace), and a config that names it is kept and shown as it is; on 4.5omaboxsays what the scratchpad is now. The README gives a key binding forspecial:omabox(#292).
Removed
- The forms deprecated in 0.9.0 are refused (exit 2;
run's 125) with one line naming what to write, never read another way (#287): -wait cmd: writewait until -- CMD. -up --idle 45andOMABOX_IDLE=45, a bare number (minutes up to 0.9): write45m. -keys -s 300andpointer -- sleep 300, a bare number (milliseconds up to 0.9): write300ms. -up -i: write--interactive.save -f: write--force. -shotandcalibrategiven two files: name one. - A box name given with characters a box name cannot have, or past 40 of them (-b "my box"): the refusal names the one that fits (my-box). -keys --delay MS: for a pause,-s DURATION. - The JSON fields 0.9 kept beside their successors:
config --json's kebab-case keys (bar-icon,confirm-close-available,gpu-now...: readbar_icon...),ls --json'sallow(readallowed),ports --json'saddress(readaddresses).
Fixed
- Plugin settings that held what looks like a key, token or password were copied into every box:
~/.config/omarchy/extensionswent into the box HOME without the check your desk's other files get under--desk-shell. Such a file now stays on your desk, andupnames it ("not seeded: extensions/NAME ..."); a setting that only mentions one (maxTokens) still goes in. up --clean --from SAVEcould write its wallpaper outside the box, onto the file a link the save left at~/.config/omabox/clean-wallpaper.pngled to. It is written in the box HOME.- A monitor window of an interactive box could open on your workspace and take focus: when the box's Hyprland took more than 5 s to make it, when
monitor addwas interrupted (Ctrl-C, TERM, HUP) while the box made it, or when two adds ran at once; and an add cut short could leave its host rule on, sending every later aquamarine window (a nested Hyprland's too) to the box's workspace. The window now has its own class and rule from the start, so it opens on the box's workspace without focus whatever happens to the add, unless your Hyprland reloads its config between the rule and the window's first map (a theme change, a saved config: the reload drops the rule). An add cut short removes its half-made monitor, and a second Ctrl-C ends that at once (#349). - An
upinterrupted after its box started (Ctrl-C, TERM, HUP) left the box running, unseen and, for an interactive one, with no idle limit to take it down: duringup --interactive --monitor's add, or while it waited for the box's shell. It now ends the box, as any otherupthat fails, with the signal's exit code (130, 143, 129); a Ctrl-C toupalone no longer lets it go on. pixelleft a temporary file in $TMPDIR when grim's frame was cut short, its size unreadable, the point past its end, or a signal ended it; a failed update of a box'sbox.jsonleftbox.json.tmpin the box's folder, andoutputitsoutput.dropped.tmp. Scripts: nothing to change (#357).- A command in a box had your terminal as its controlling terminal when it had no terminal of its own (its output piped or in a file, from a terminal): it, and what it left running, could open
/dev/ttyand read what you typed there, write to it or signal its session. It now runs in a session of its own in the box, with no controlling terminal; a Ctrl-C, Ctrl-\ or Ctrl-Z at your terminal, or a signal torun's process group, still reaches it and everything it started, and nothing of it is left oncerunis stopped or killed. A command run at your terminal keeps the pseudo-terminal of its own it had. omabox envprinted a path inside the box's runtime folder, which the box can write: a link put there in its socket's place could lead a host tool to another display, your desktop's included. It now prints a hard link to the box's own socket in the box's folder, and refuses a socket that is not one.- The tools omabox runs against a box (grim, hyprctl, its input tools, gdb) could make a crash notification on your desktop: unlike a box's own commands, they kept your core limit. They get the box's 1-byte limit.
monitor removeon an interactive box returned before its screens had their new scales: right after it, the main screen could still be at the scale it had beside the monitor (0.825 for 1). It now waits for them, 5 s at most (#382).click --window(and--ina window's shot) could fail with "did not take focus in 3 s" on a window moved while its workspace was hidden: the window it had been over took the focus back. A window that had the focus and lost it at once is focused again.keys up:KEYof the last key held returned while the key holder was still letting go: its virtual keyboard stayed on the box's seat, and the holder in the box's process list, for some 30 ms more. It now returns once the holder has ended.- A monitor could come up at scale 2 where
--monitorormonitor addasked for another: one at the size an output starts at (1280x720 on NVIDIA) was now and then kept at Hyprland's default scale, which a reload kept too. Its scale is set before it exists, and the add waits until the box has it (rounded to whole pixels at most, asmode's); one Hyprland makes at another is removed, saying what it made, exit 1 (#379). check runfailed a checkpoint on holes its baseline already had: every hole was read as new, so an approved see-through design failed each run. Only holes the baseline has none overlapping count as new, as before the Rust omabox.- A call right after a box's Hyprland crashed could say it "did not answer (hung?)": the call that hit the crash said the box went down while the box was still ending. It now says so once the box is down (within a second), and the next call says the box is dead and why.
tree --windowprinted another window's tree for a window its app does not publish (#302). An app that puts only one of its windows on the accessibility bus (egui's root viewport, not its child ones) had that window's tree printed for every other one. Now the app's only window stands for one of another title only when it is that window's size and no other window of the app is; elsetreesays the window has no tree, or that which one it is cannot be told, exit 1.run -din a repo no longer says to start a box when your session has one up elsewhere (#296). Afteromabox upin a scratch folder,run -dback in the repo saidomabox up <repo>-…, and agents started a second box. It now names the session's box to pass with-b, as the other commands do there.up --desk-shellleaves omabox's own bar widget out (#304). It lists your boxes withomabox ls, which a box does not have, so the box's shell logged a warning for it (and would have notified).upsays it left it out;--pluginstill mounts it.up's line names every monitor (#308):box 'NAME' up (1920x1080@60 + 1080x1920@60)for a box started with--monitor 1080x1920, not the main screen alone.run -d --waitsaidsatisfiedfor a command that had already died (#297), when something else on the screen settled meanwhile (the last app's window closing, another agent's window), and its end only came as a warning on the next command. Now a command killed or ended with a status other than 0 by the time the screen settles makes the answerunsatisfied, says its end and its log's last lines, and exits with its status. One that ends with 0 having changed the screen stays satisfied.- A
run -djob's warning said "its words were not kept" for ordinary jobs (#298). The next command's warning about a job that ended lost what the job was when it died at once, when the box was slow to make it a session of its own, when--replaceor another command had looked at it first, or when another command touched the job records at the same moment. A job's record is now always kept until its end has been said, so the warning names the command and its pid. - The warning about a
run -djob that ended fired for jobs you stopped yourself (#300): afteromabox run -- pkill APP, the next command said the job "was killed by SIGTERM". A job killed (SIGTERM, SIGINT or SIGKILL) while anomabox runran in its box, or within 2 s of one ending, is no longer said; exits and crashes still are. - A box going down could show on your desktop as "Process crashed: Xwayland" (
up --xwayland). Hyprland starts Xwayland with-core, which raised its core limit back past the 1 byte everything in a box gets, so its abort when the box's compositor went was recorded as a crash. A box's Xwayland now keeps the 1-byte limit (unless you raised it yourself). - The shell-crash warning fired for any Quickshell in the box, and missed a killed shell. A Quickshell of your own crashing (to test its crash handling) was reported as the shell crashing, and omabox closed its crash dialog; now only the box shell's crashes count and only its dialog is closed. A shell killed outright (
kill -9) and started again by Omarchy's launcher is now said by the next command:the shell was killed by SIGKILL (137) since the last command and was started again. runprinted bash'sline N: PID Killed prlimit …for a command killed by a signal; it now saysthe command was killed by SIGKILL (137), with the same exit status.waitand--waitcould print a garbled answer under load (#310), such asunsatisfied: changingt=2002, when the screen watcher's answer arrived in two pieces split at a space. The space is kept now.- An interactive
monitor addcould open its window on your workspace, focused, when the box took more than 5 s to make it:hyprctlstops waiting after 5 s, and omabox took that for a refusal and turned off the rule that sends the window to the box's workspace. Now an answer that says nothing either way counts as "maybe made": the add removes the monitor again, waiting for the box to answer (about 20 s at most), and only then turns the rule off, also when the add is interrupted or its terminal hangs up;monitor addreturns only once the rule is off, whatever the signal. The add still fails, saying the box did not answer (#349). While the rule is on (about 35 s at worst), a nested Hyprland of your own opening a window is caught by it too, as before. - A shell a test starts itself, under
omabox run, no longer loses plugin hot-reload. The box's stand-in that keeps its own shell from reloading a mounted plugin on every save also caught other shells, so Omarchy's ownruntime-smoke-test.shfailed in a box. Now it applies to the box's session only (#317). - The first shot after
upcould be a black screen: 4.5's shell covers every screen for a new login until the theme's intro has played, which in a box (no OWE daemon) took up to 5 s pastup. A box's start is now marked as had, andupalso waits out the cover (#291). - A box's screen came up on workspace 11: 4.5 gives each monitor ten workspaces of its own, and Hyprland's stand-in output took the first ten. The main screen is on 1-10 again, monitors added after it on 11-20 and on; an interactive box closed with confirm-close and opened again keeps its workspaces (#292).
omarchy-theme-setreloaded Hyprland about a second after it returned in a box, on themes with intros: now before it returns, sowait stilland a shot see the new theme.- A desk's
centerAnchorand a plugin'scentersection are placed as 4.5 places them (centerBegin,center,centerEnd), also for a desk on an older Omarchy in an--omarchybox. up --clean --from SAVEshowed the save's notifications: 4.5 keeps them in the HOME; a clean box starts without them.up --omarchyof a 4.5 tree on an older host: the tree's xkb files go into the box (its keyboard option), andupsays which of owe, omasnap and the titlebars plugin the host lacks (#293).click --window --no-raisewas refused over 4.5's notifications column and dock with nothing there: both stay mapped while idle and take input only on their items. A layer spanning the screen's height or width (and not reserving its edge, as a bar does) is now said as one the input may go to, like a full-screen one, and never refused; the message says "a layer spanning the screen" where it said "a full-screen layer" (#311).
Changes from the bash omabox
omabox up Bright afteromabox down Bstarts the box: the bash omabox could cancel it as if the down had come while it was starting, when both began within the same 10 ms. A down that comes while its up starts (omabox up B & omabox down B) still cancels it, told by the order the two processes were made in. Scripts: nothing to change.- A host command omabox runs gets your
SHLVLand_as they came (guard exec,host, acheck runscenario); the bash omabox set its own. Neither is part of omabox's contract. Scripts: nothing to change. omabox --versionsays the version omabox was built from: a build older than its checkout (pulled without./install.sh) says its own, where the bash omabox read the checkout's file.- A jailed agent's
--passand--env-filevalues reach omabox-relay on a file descriptor, not its command line, as values everywhere else in omabox do.omabox-relay calltakes--env-fd N. A jail started before the upgrade keeps its old relay: restart it. - A jailed agent's
configleavesprotect-portsout, andconfig protect-portsfrom inside ai-jail is refused saying why ("protect-ports is not for a jailed agent"), not as a change of settings: which host ports are protected is the user's to know. Scripts: nothing to change. - Without
XDG_RUNTIME_DIR, omabox says so in its own words: "omabox: XDG_RUNTIME_DIR is not set" (exit 1, as before), where the bash omabox printed "bin/omabox: line 13: XDG_RUNTIME_DIR: XDG_RUNTIME_DIR is not set". Scripts matching that line: match "XDG_RUNTIME_DIR is not set". help WORDtakes WORD as written:omabox help 'u\160'is an unknown command (exit 2). The bash omabox handed the word to awk, which read escapes in it, so it printedup's help. Scripts: nothing to change.configandguardrefuse a settings link they cannot follow (into a folder not there yet, or a loop), saying so and naming it; the bash omabox exited 1 there without a word. The link is kept. A config that cannot be read stops everyup(exit 2) andconfigsays so; the bash omabox read it as empty, protecting no port. Scripts: nothing to change.- Entering a box is omabox's own, not
nsenter's (omabox run -b B -- truetakes about 3 ms on a box already up). What a failed entry says is in omabox's words, "omabox: cannot enter the box: REASON", where nsenter's own line was printed (and "dropped N bytes of other output on the box entry's stderr" where it said "nsenter's stderr"). A TERM or KILL sent to omabox alone, or to the process that waits for a box command (pkill -f 'omabox run'reaches it), ends the command and what it started, where nsenter (or omabox) died and left them running; that process is namedomabox-enter, andpgrep -f 'omabox run ...'finds it besides omabox; in the box,psshows the command's session led byomabox-session, its command line that name alone (nothing in the box has the words of your call, sorun -- pgrep -f WORDfinds only what is in the box). Scripts that matchednsenterlines or processes: match these. - A command in a box has no controlling terminal unless it runs at yours (then it has a pseudo-terminal of its own, as before):
/dev/ttythere is "No such device or address", and it runs in a session of its own, in a process group of its own. A command that needs a terminal while its output is piped: run it asscript -qc CMD /dev/nullin the box. omabox envexportsWAYLAND_DISPLAY=$(omabox path)/wayland, a hard link to the box's socket, where it exported$(omabox path --run)/wayland-1; it exits 1 when the box's socket is not a socket (a link in its place). Scripts that built the path frompath --run: useomabox env.downof a box it cannot see from this user namespace (a sandbox's) refuses, asupdoes: "cannot tell whether box 'B' is up from this user namespace ...", exit 1, the box left running and listed. The bash omabox said "box 'B' down", exited 0 and removed the box's dir while it ran on. Scripts: rundownoutside the sandbox.omabox confighas a sixth key,protect-ports: listed aftershot-fit(protect-ports=when none is set), in--jsonasprotect_ports, and named among the keys when one is unknown. A bad value of it in the file is said asupsays it and shown, not ignored. Scripts that readomabox configline by line or its--jsonkeys: expect the new one.hostandguard execsay a command they cannot run in omabox's words: "omabox: host: cannot run CMD: not found in PATH" (or "no such file", "permission denied"), where the bash omabox printed "bin/omabox: line N: exec: CMD: not found". Exit codes unchanged (127, 126).- A jailed agent's
downandupcheck whose the box is again once they hold its name's lock, and a jaileddownthat finds no box cancels only its own jail'supof that name, not yours. Scripts: nothing to change. - The idle reaper says how often it looks, once, in the box's
reap.log(omabox log reap): "box 'B': watching it every 60 s". The bash omabox said nothing of it. Scripts: nothing to change. saveandsaves rmsay what they could not remove in omabox's words ("could not remove all of save 'S': ..."), where the bash omabox printedrm's own line. Exit codes unchanged.upstopped by INT, TERM or HUP ends with the signal's code at every step (130, 143, 129), its box ended; the bash omabox could exit 1, its box left running, when the signal landed duringup --interactive --monitor's add. Scripts: nothing to change.up --no-seedand--keeptake their words as written:*,?or[in them are refused. The bash omabox matched them against the current folder's file names (--no-seed 'font?'wasfontsin a folder holding a file of that name). Name the words instead.upsays its own words:up --audionames the programs it lacks as "pipewire, pactl" (the bash omabox wrote "pipewire,pactl"); a desk with noshell.jsonno longer prints bash's "No such file or directory" line; a failure to make the box HOME is said as "up: could not ... in the box HOME". Exit codes unchanged.- An INT sent to omabox by another process (
kill -INT PID) stops the command like TERM, once the step in progress is over, with what a TERM would leave (a temporary file removed, a monitor half made removed, arecord --forstopped), exit 130. The bash omabox went on or stopped depending on the step it was in (cpu,gpu,peek --focus,gdb,record --forandcheck runwent on to their end). A Ctrl-C at the terminal is unchanged where a program takes it (the scenario ofcheck run): if that program carries on, so does omabox; any other step it lands on,gdb's among them, now stops the command (gdb's runs in a process group of its own, which a Ctrl-C never reached). Scripts that sent INT to omabox expecting it to go on: send nothing, or send it to the child. - A TERM or HUP lets the step in progress end before omabox undoes its work (at most ~20 s, then that step, with its process group, is stopped; after a second omabox says "stopping once the step in progress ends (at most 20 s)"):
check runstopped during a scenario takes down its boxes once the scenario's step is over, where the bash omabox took them down under it and left the scenario running. Exit codes unchanged. record --forandrecord -- ACTIONstopped by INT, TERM or HUP stop their recording: the video so far is made and said, the pointer shown again, then omabox exits 130, 143 or 129. The bash omabox left the recording running in the box, the pointer hidden, and said nothing (record stopended it later). Scripts that ranrecord stopafter such a signal: it now says the box is not recording; the video is already where-osaid.- The first INT, TERM or HUP decides how omabox ends, and what it was undoing finishes: a second signal no longer cuts its cleanup short, and the exit code is the first signal's (TERM then INT: 143; the bash omabox gave the lowest-numbered one's, 130). A signal during
record stopstops the step in progress: during--sheet's frames, no sheet is made (the bash omabox made it, then exited 130 or 143 all the same); during its encode, an INT sent to omabox alone stops it with 130 (the bash omabox went on). Scripts: nothing to change unless they relied on the second signal's code. - An interactive
monitor addends at any Ctrl-C or INT, its half-made monitor removed, exit 130. The bash omabox did so for a Ctrl-C to its terminal, but an INT sent to omabox alone (kill -INT PID) ended it with 130 while the add went on and kept the monitor. A script that sent omabox an INT and counted on the monitor being made should let the add finish instead. - A box name such as
-nis named in its refusal (OMABOX=-n, a repo of that name): "bad box name -n: ...". The bash omabox read the name throughecho, which took-n,-eor-Efor its own options, so its message showed an empty name. Exit code unchanged. Scripts: nothing to change. --modtakes its words as written (click, drag, pointer, scroll):*,?or[are refused as modifiers. The bash omabox matched them against the current folder's file names, so--mod '*'in a folder holding a file namedctrlheld Ctrl. Name the modifiers instead.run's command killed by a signal is said: "omabox: the command was killed by SIGTERM (143)" (any signal but INT and PIPE). The bash omabox counted its own "Terminated" line as nsenter's, said "dropped 50 bytes of other output on nsenter's stderr" for a TERM, and waited 2 s before answering; now only a SIGKILL (what a box's end sends) waits up to 2 s, to say whether the box went down. That wait and that word now come from every box step killed so (arecordoraudiostep that had to be killed after its time limit), where some said nothing. Exit codes unchanged. A script that matched "dropped N bytes" after a TERM: match "was killed by", or the exit code.- Errors omabox meets on its way are said in its own words, no longer in bash's or a tool's: a
check runscenario that cannot run says so in its run's log as "omabox: check: cannot run scenario X: its #! interpreter '/bin/sh^M' is not there (CRLF line ends?)" (was "bash: X: /bin/sh^M: bad interpreter: ..."), a file omabox could not write as "omabox: CMD: cannot write PATH: why" (was a bare "PATH: why"), a missing tool as "omabox: cannot run jq: not found in PATH" (was "jq: command not found"),pixelpast its image as "omabox: pixel: the point is past the end of grim's image" (was od's words), andclip's refusal names the process "omabox", not "bash". Exit codes unchanged (127 for a scenario not found, 126 for one that cannot run). Scripts that matched those texts: match the exit code, or the new words. - Where omabox ended without a word, it says why, with its usual exit codes:
pixelon a frame it cannot read (1),gdbon a box this user namespace cannot read (1, was 3) or a gdb that did not start (1, was gdb's status),checkon a folder or file it cannot make, write or copy (2, check's code for its own failures; was 1, check's code for "changed"),shot,recordandcalibrateon a path that cannot be resolved (1). A box's list of monitors that cannot be written to itsbox.jsonis said and the command carries on (some commands ended with 1 there, unsaid, and others went on). Scripts that tested for exit 3 from gdb, or exit 1 fromcheckfor those: test for non-zero, or for 2. - Box names, and every number and name omabox checks, are ASCII in every locale:
éor²are refused with the usual message. The bash omabox checked them in the caller's locale, where en_US.UTF-8 and most others takeéfor a letter and²for a digit: a process with OMABOX_BOX=é was named box é bywhich, andpixel 1 ²ended in bash's own words ("invalid integer constant", exit 1).events --grepand--untilstill read your pattern in your locale. Scripts: nothing to change. - Lists are in byte order, the same in every locale: a session's boxes in a message, run logs,
check run's checkpoints,portsandgpu's rows, andlsandsaves(table and--json). The bash omabox followed the locale's collation, so under en_US.UTF-8acame beforeB, under C after it. Scripts that sorted the output themselves: nothing to change. - Text is read as UTF-8 whatever the locale: the default box name of a repo with non-ASCII letters,
keys' notes (secret N) andrecord's--asand mark lengths come out the same under LANG=C as under a UTF-8 locale (the bash omabox counted bytes under C), and option words are lowered the same way in every locale (a Turkish locale refused--mod SHIFT). A monitor's scale and rate are written with a dot whatever LC_NUMERIC says, and a system error in omabox's message in English.events --grepand--untilstill read your pattern in your locale. Scripts: nothing to change. - Numbers with zeros in front are decimal:
--fps 010is 10 fps,-g 010,0,…starts at x=10,--frames 08is 8 frames. The bash omabox read them as octal (8), and08or09ended the command with bash's "value too great for base", exit 1. A number too big for 64 bits gets the option's usual refusal (it wrapped). Scripts that padded numbers with zeros get what they wrote. - JSON numbers are written in standard form:
1000, not jq's1E+3;1e+300, not1E+300(lua --json, a box'sbox.json). A number written without an exponent stays as it was. Scripts that read the JSON with a JSON reader: nothing to change. - Waits and timeouts run on a clock that a time change does not move:
wait --timeout,events --until's timeout,run -d --replace's grace before SIGKILL,shot --burst's spacing,cpuandgpu's sampling window, and the built-in waits (a window to appear, a mode to apply, peek's focus, gdb's attach,wait's 30 s notes), which also last their full time now. The bash omabox measured them on the wall clock, and the built-in ones in whole seconds, so they could end up to a second early. Scripts: nothing to change. check run SCENARIOalways runs the program found in PATH: a scenario named like a shell builtin or one of omabox's functions (test,true,say) is no longer run inside omabox. One that names a program in PATH (test,true) runs that program; one that names none (say,shopt) fails as a scenario not there does: "omabox: check: cannot run scenario say: not found in PATH" in its run's log, its status 127,check runexit 3. The bash omabox ran its own builtin or function there. Scripts: nothing to change (give a path, as before, for a scenario of your own).- A Ctrl-C (or a TERM or HUP) during
omabox upclears the box: the box was ended either way, but the bash omabox kept its folder once it was written, soomabox lslisted itdeadand its idle watcher ran untilomabox down. Now it goes as adownwould. Anupthat fails still keeps the box's folder and logs, as before (#388). Scripts: nothing to change. - A signal no longer leaves temporary files behind:
omabox shotstopped during its capture left an emptyOUT.partand grim's error file in$TMPDIR(#386; with--no-pointertheOUT.partstill can), and a signal in the instant between making and registeringcpu's,gpu's orrecord stop's working files left those (#360). The bash omabox did the same.
0.9.22026-10-20
A fix to the agent guard for hosts on Omarchy 4.5 (its release candidates and the edge channel): without it, a guarded agent could reach your desktop's shell through omarchy-shell. Run omabox guard on once after updating. Also: a box's shell is no longer killed now and then as it starts under load.
Fixed
- The agent guard let Omarchy 4.5's
omarchy-shellreach your desktop's shell (#290). On Omarchy 4.5 (its release candidates and the edge channel today),omarchy-shellfinds your session's display when the one it is given does not exist, which the guard's never does, and then talks to your bar's shell directly, so a guarded agent'somarchy shell …, menus or theme hooks could act on your real desktop. The guard now leaves a file in your runtime directory that keepsomarchy-shellfrom looking further, and its ownomarchy-shellrefuses with a reason. Runomabox guard ononce to renew the hooks (sessions say theirs is outdated until you do). - A box's shell was now and then killed as it started, under load (
the shell exited after starting; its log:exited with status 137). PipeWire, asking a box's portal for realtime limits it cannot give (a box has no RealtimeKit), set the shell's realtime time limit to zero, and the kernel kills such a process the moment a thread of it is boosted to a realtime priority, which happens under load. PipeWire's clients in a box no longer load that module, so the limit stays unlimited.
0.9.12026-10-20
The release candidate for 1.0 (planned for 2026-10-24). The skill's core is about half its size, the rest in reference.md. An action's --wait says what changed on the desktop, and where the input went when it timed out. A run -d job that dies in its first 30 s is said on the box's next command. A full-screen layer such as Omarchy's notifications is only "possibly" over a point, so --no-raise goes on. And up --clean's frozen clock no longer slips under load.
Added
--waitsays what changed on the desktop (#274). Afterkeys,click,scroll,dragandrun -dwith--wait, the line (still startingsatisfied:orunsatisfied:) adds what changed since just before the input:window opened, focused: zenity "Save as",window opened on workspace 2: ...,window closed: ...,layer omarchy-menu opened,focus: none,foot title now "...",workspace now 2; three at most, then+N more (omabox events --since OFFSET). A 124 says where the input went (the focused window, a layer holding the keyboard, what was under the click, in the window's own coordinates) andno window, layer or focus changedwhen nothing did, so it needs no shot to learn that nothing happened.--jsonaddschanges,targetandevents_since. Exit codes are unchanged; it costs ~25 ms a call (~40 ms on a 124).- A
run -djob that dies a few seconds in is said by the next command (#286).run -dcatches a job over in its first 0.3 s; a server that died a second later was said by nothing. Now a job that ends within its first 30 s with a status other than 0 is one warning on the box's next command, whatever it is (omabox: warning: run -d job ./server (pid 115) exited with status 1 after 2.1s, since the last command (omabox log -b NAME run)), once. A job--replacestopped, onerun -dalready reported, one that ran longer, a one-shot that exited 0 and a launcher whose app still runs are not said. No cost to a command while no job has ended.
Changed
- A full-screen layer is said as possibly over a
--windowpoint, not refused (#263). Omarchy's notifications sit in a layer covering the whole screen that takes input on its toasts only, so while a toast showed every click counted as under it:--no-raiserefused clicks far from the toast. Such a layer is now said as one the input *may* go to (a full-screen layer "omarchy-notifications" … is up …: input at X,Y may go to it if one of its items (a toast) is there),--no-raisegoes on,windowslists it as possibly over the windows, and an action's 124 names the window under it,or possibly on layer omarchy-notifications. A layer smaller than its screen (a panel, a menu) is still over the point for certain and still refused, and wins where both are.--jsonaddscertaintowindows'layersand to--wait'starget. - The agent skill's SKILL.md is the core every task needs, about half its size (8 kB where it was 14 kB, ~2k tokens fewer each time an agent loads it): what never to do, the project instructions table, the loop, driving an app, waiting, coordinates, and a line for each section of
reference.mdbeside it. The rest (the guard andomabox host, ai-jail, mounts, showing the user, what a box cannot test, reporting) moved toreference.mdsections the core names; nothing was dropped. A text question (a label, a checked box, a field's text) now goes totree --findbefore a shot (#270).
Fixed
up --clean's bar clock showed the real time in about one start in six under load, soomabox checkread the bar as changed with nothing changed. Omarchy's shell reads its defaults and the user's shell.json each on its own, and when the defaults came first the frozen "Friday 12:00" was lost while the bar was being built. In a clean box the shell's defaults are now the box's own shell.json, so either order draws the same bar.
0.9.02026-10-20
The last release before 1.0. omabox help CMD is short, the command's lines and options (--long for the prose), and omabox brief prints what a subagent needs in place of the whole skill. New: wait until (the new name of wait cmd), path --home, tree --layer for the shell's bar and panels, record --for and record hold, and the time on each log shell line. Every duration option takes one grammar, every option takes --opt=value, --json is there where it was missing, and exit codes mean one thing in every command (omabox help exit-codes): called wrong is exit 2 with the nearest option or command named, and run's own failures are 125. The forms under Deprecated still work, with a warning; 1.0 refuses them.
Added
omabox brief -b NAMEprints ~15 lines a parent agent pastes into a subagent's prompt instead of the subagent loading the whole skill (a quarter of its size or less): the box's name, size and windows, each window with a--windowword that finds it alone, then the rules (-b NAMEon every call, one literal command per call, look, act once, look again, never resend unseen input, no sleep, never the real desktop, the box HOME's host path for file tools, scripts there for several shell steps, stay in your worktree) and when to load the skill after all. The skill tells a parent that delegates box work to use it (#271).--opt=valuewherever an option takes a value, in every command (shot --window=firefox --fit=1456,omabox --box=x windows,pointer move X Y --steps=5): as--opt value. An option that takes none refuses one (--json=1, exit 2); a value given as a separate word stays as it is (log --grep --x=ylooks for--x=y), and so does everything after--.omabox wait until -- CMD: the new name ofwait cmd, waiting until a command run in the box exits 0 (the same flags, exit codes and--json, whoseconditionisuntil). Claude Code refuses any call holdingwait cmdfrom a subagent working in its own git worktree, since it reads the word as a shell;wait untilpasses (#272).omabox path --homeprints the box's HOME (/home/sbxinside) as the host sees it, a plain path for an agent's own file tools, in place of$(omabox path)/homeinside a command.- The skill's reference has a section for subagents in an isolated worktree: five rules that keep every omabox call one the worktree check lets through.
omabox record --for 5srecords the screen for that long with no action: something that moves by itself (a panel cycling on a timer) no longer needs a dummy action that moves the pointer. The video is that long, a frame or two more (#259).omabox record hold 2s, betweenrecord startandrecord stop, is a pause in a scripted take: it returns once the video has 2 s more from when it was called, measured in the video's own clock (its frames' times), so a slow box or a slow script never shortens the pause the viewer sees; it prints the span ("held 4.210s to 6.210s"). With nothing recording it exits 2, namingrecord start.record mark TEXT --hold 2smarks, then holds from the mark. The skill names both as the way to let time pass in a recording (#280).omabox tree --layer SELreads the accessibility tree of a layer surface: the Omarchy shell's bar, panels and menus, a plugin's panel. SEL is a namespace (omarchy-bar),address:0x...orpid:PID;--find,--jsonand--allwork as for windows, and the bounds are the screen's, so a plainclick X Yat a node's middle lands on it. It needs Quickshell 0.3.2 or later (orup --quickshella build), and shows only items that set anAccessible.role: a layer without any says it "publishes no accessible items", as Omarchy's own bar does today (#254).--jsonon what lacked it (#273):check runandcheck diff(each checkpoint's result, regions, holes and tree changes, the report; for CI),shot(the path, what it covers, in which coordinates, the image's size and scale, and what--changedfound),record status,mode,path --logs,calibrate --answer,which,--versionandevents --mark.ls --jsonaddsscale,dirandallowed(the ports as numbers),ports --jsonaddresses,saves --jsonsize_kb,windows --jsonx, y, w, hbeside Hyprland'satandsize. The skill's reference lists each command's fields under "JSON": from 1.0 they only grow.omabox portslists an isolated box's--allowports asallowed(pasta's, in the box): pasta listens on each inside the box, leading to the host's, so a box server on one fails at once with "address in use", and before, it just never appeared.help upand the skill's reference say so: an--allowport is for reaching that host port from the box; serve on another (#286).
Changed
omabox help CMDis short: the command's lines and its options, one line each (30 lines at most;help up2 kB where it was 19 kB), ending withmore: omabox help CMD --long, which prints the whole text as before: what each option does, defaults, limits.omabox CMD --helpis the short form too.omabox helplists every command's lines (11 kB);omabox help --longis all of it, asomabox helpwas (60 kB) (#269).config --jsongives its keys in snake_case (bar_icon,shot_fit,gpu_now), as every other--jsondoes; the bar widget reads them.windows --jsonis one line, as the others are.omabox help CMDnames every option the command takes, aliases too:--box,--output,--follow,--detach,-l,-wand--activewhere they go,scroll --no-raise.- Exit codes mean one thing in every command, in one table:
omabox help exit-codesand the skill's reference (#273). Called wrong (an unknown option or command, a value missing or not of its form, a word too many or too few) is exit 2 everywhere, where most commands gave 1; 1 stays "it ran and failed", 124 "not in time". Each such refusal names the nearest option, subcommand or command when one is close (shot: unknown option --widnow (did you mean --window?)), the form a missing value takes (-g needs a value: -g "X,Y WxH"), andomabox help CMD. A script that tested for 1 after a bad call should test for non-zero, or 2. omabox runexits 125 for its own failures (no box, a bad option, a throwaway that did not start, the box going down while the command ran, the broker out of reach from ai-jail), so they are never read as the command's status, which passes through as before (126 and 127: the command could not run, or was not found, in the box).- Refusals that did not say what to do now do: a bad box name says what one is; a box's name where
windows,wait,recordand others take no word says it goes with-b;click,dragandscrolllist what goes where a word was not understood;keyswith nothing to send gives examples;config,monitor remove,guardandeventssay what goes there; a window that will not take focus is named, with the way round;mode,gdb,peek --focusandrestart-shellsay what to look at next; messages that lacked their command's name have it. keysrefuses an unknown--option(exit 2) where it handed it to the keyboard tool (--holdthere never returned).- One duration grammar for every option (#273):
300ms,2s,1.5mand now1h; a bare number is seconds.gpu,cpuandaudiotake their length as one (omabox gpu 500ms,cpu 1m --settle 2s), where they took plain numbers only, and so does$OMABOX_READY_TIMEOUT. --active(--window active) goes withkeys,click,scroll,pointer,dragandwaittoo;check run,check pointandcheck difftake--outputbeside-o;events --grep -i REignores case, aslog --grep -i REdoes;check pointrefuses a bad--timeoutbefore the scenario gets there.omabox log shelllines carry their time, to the millisecond (2026-10-20 14:03:07.512 WARN qml: ...): the box's shell runs with Quickshell's--log-times, and the launcher'slogger -t omarchy-shelllines have the same stamp. Timing what a shell plugin does (a retry's backoff) no longer takesquickshell log --log-timesby hand;--grepand-fwork as before (#276).record start,stop,statusandsheetrefuse--hold(exit 2), which they ignored: it goes with-- ACTIONormark.omabox help tree --longand the skill's reference say what an egui/winit app needs for a tree on at-spi2-core 2.61 and later (Arch's now): accesskit_unix 0.22+ (eframe 0.37+). An older one waits only for a property those versions dropped, so it never joins the accessibility bus, and nothingtreesets helps; they no longer saytreeturns it on (#282).test/run.shprints a long failure's first 100 and last 200 characters, where it printed its first 300 and lost the reason at the end, and keeps the newest 10 runs with a failure besides the newest 5 that passed: runs that pass no longer prune a failed run's evidence (#285).omabox run -dsays a command that ended at once (in its first 0.3 s, leaving nothing running) instead of "started": its exit status and its log's last lines, and it exits with that status (0 stays 0, said; with-q, not said). A server on a port already taken was "started" and never seen again. A job still running after 0.3 s is "started" as before;--waitkeeps its own answer (#286).
Fixed
- A jailed agent's
shot --monitor NAMEtook NAME for the output file, and the broker refused it (#284). - A jailed agent's one-action
record -- ACTION(and--for) gives--show-input,--captionsand--cut-idleto its stop, where they belong; its start refused them.
Deprecated
omabox wait cmdstill works, with a warning namingwait until; 1.0 refuses it.- Each of these still works, with a warning naming what to write instead, and 1.0 refuses it (#273): -
up --idle 45andOMABOX_IDLE=45, a bare number read as minutes: write45m. -keys -s 300andpointer -- sleep 300, a bare number read as milliseconds: write300ms. -up -i: write--interactive(-iis ignore-case inlogandevents). -save -f: write--force(-fis follow inlogandevents). -shotandcalibrategiven two files: the last was taken without a word; name one. - A box name given with characters a box name cannot have, or past 40 of them (-b "my box"): it was written to fit without a word (my-box),upaside; write the name that fits. -keys --delay MS, the keyboard tool's own time between keys, read only as the first word and never documented: for a pause,-s DURATION. - With
--window, every coordinate is the window's own (click's X Y,shot -g,check point), except the regionswait still|change --windowand--waittake beside it (--ignore,-g): those are still the screen's, now with a warning, and 1.0 takes them in the window's own. A script that wants the screen's watches with-g(the window's place) instead of--window. - Fields that 1.0 drops, each with its successor beside it now:
config --json's kebab-case keys (bar-icon,confirm-close-available,gpu-now...),ls --json'sallow(a comma string; useallowed),ports --json'saddress(useaddresses).
0.8.02026-10-20
Visual checks: omabox check compares an app's or a plugin's look with a baseline, in an up --clean box where only what is tested moves. up --quickshell PATH runs the box's shell on a Quickshell build of yours, your fonts are in every box, and click --window says when a toast or another layer covers the point it aims at. A config error no longer hangs a box, reload says when Hyprland stopped answering, record stop no longer waits forever on a stuck ffmpeg, tree puts what is inside a Qt Quick dialog where it is drawn, and down names your session's box when the directory's name has none.
Added
- Visual checks:
omabox check. An app's or a plugin's look compared with a baseline, so nobody has to look at every screen. A scenario (a script of yours that drives the box and callsomabox check point IDwhere a shot should match) runs in a fresh clean box;check run --approve -- SCENARIOruns it three times and keeps what most runs agree on as the baseline, saying what was not the same from one run to the next (and leaving that out from then on);check run -- SCENARIOthen says, for each checkpoint, same or changed: each region that changed, marked on a copy of the shot, and, for an app with an accessibility tree, which element moved, resized, changed its text or state, appeared or vanished (moved -6,+0 button "Save"), and one report image of every change, each cropped from the baseline beside the new shot and labelled, a fifth of the image tokens of looking at each changed shot or less. Shots are compared exactly, as users see them, leaving out only specks: stray parts smaller than what that checkpoint's approve runs differed by (twice their largest, 16 px at least; Qt Quick's text varies by a few pixels a glyph from one start of an app to the next), and under 8 px where the runs agreed to the pixel (the bar, most apps), so a 2 px spacing change in a bar widget or a vanished sort arrow is caught, and a colour a few levels off too;samesays what it left out.--approvealso writes one image of the whole baseline, what is left out marked, to look at before keeping it (what most runs showed is kept, a wrong screen too).check point --window SEL -g "X,Y WxH"checks a part of a window, in its coordinates, with the tree of that part. The last line counts same, changed, new and missing checkpoints, each run says how long its box took to start, and a check with no baseline exits 4; one called wrongly or that cannot run (an unknown option, a missing file, no box, no magick) exits 2, never 1, its "changed". Checkpoints are shot full size whatever yourshot-fit, so a baseline is the same image on every machine, and--ignore "X,Y WxH"is in-g's coordinates: the window's with--window, else the screen's. Each checkpoint is searched for holes too: the clean wallpaper showing through inside a window, the bar or a popup (a transparent part, a gap, a surface that did not draw), not around them or at rounded corners;--approvesays each, and a check fails on any the baseline lacks.check diff A.png B.pngcompares two shots of yours the same way (--reporttoo). up --clean: a desktop where only what is tested moves. Omarchy's own bar on tokyo-night, a solid#ff00ffwallpaper (any of it inside a window or the bar is a hole), the bar's clock frozen at "Friday 12:00" by its format (in its place, at its width; nothing is preloaded into the box's processes, which keep the real clock: seed an app's dates relative to now,--ignorea time it shows), English (en_US.UTF-8, or C.UTF-8) in UTC for the whole session whatever your locale and timezone (a Portuguese LC_TIME made an app's dates "Há 9 meses"), no pointer, no network, none of your fonts and no animations (over reloads too).--keep animations,bar,clock,fonts,locale,pointer,wallpapertakes any of them back, for a test of Hyprland or the shell that needs them;--themeand--net connectedchoose their own.runtakes it for a throwaway box too.up --quickshell PATH: the box's shell on a Quickshell build of yours (andrun --quickshell PATHfor a throwaway), for a Quickshell fix your installed package does not have yet, such as 0.3.2's accessibility tree. The box's shell,restart-shell, Omarchy's own restart and anything callingquickshell/qsin the box run the build; its folder is mounted read-only. Quickshell uses Qt's private API, so a build against another Qt than the installed one is refused (naming both versions), as is one needing a library the box lacks.ls,ls --json,windowsandsavename it. Every box'sls --jsonnow hasquickshell_version; it is the last release's number even for a build of a newer commit, so it is no proof that a fix is in.- Your fonts are in every box.
~/.local/share/fontsand~/.fontsare mounted read-only at the same place in the box HOME, so a theme's or a plugin's own faces draw as on your desktop: without them the box drew them in a fallback family, silently, and shots looked plausible but wrong.upsays it;ls --jsonhasdesk_fonts.--no-seed fontsleaves them out; anup --cleanbox has none (Omarchy's look),--keep fontsbrings them. A box HOME with its own folder there (a--fromsave's, a--seedinto it) keeps it, said, and a link in them that leads out of them is said too: it leads nowhere in the box.
Fixed
click --windowover a notification toast says so. A layer surface (a notification toast, a panel, the bar over a float) over the point aclick,scroll,dragorpointer--windowaims at takes the input there, and nothing said it: the click went to a toast and the app seemed flaky. Now it is said on stderr, naming the layer, and--no-raiserefuses (raising the window would not help);windowslists the layers over windows under its table, and--jsonhas each window'slayers. Only a layer's rectangle is known, not where it takes input: while the Omarchy shell shows a toast, its full-screen layer is named over every point.omabox wait layer omarchy-notifications --gonewaits toasts out.- A config error no longer hangs a box. Under load,
hyprctl reloadin a box whose config had an error could freeze its Hyprland for good while it drew the red "Your config has errors" bar (a Hyprland deadlock in that bar's text). A box now draws no such bar, even when yourlooknfeel.luaasks for it;up,reloadandhyprctl reloadstill print the errors, andomabox hyprctl configerrorslists them. reloadandhyprctl reloadsay when the box's Hyprland stopped answering after the reload. They printed nothing more when Hyprland answered the reload and then hung, which read as a clean reload. Now they say it did not answer (withomabox gdbandomabox downto go on) and exit 1; so doesup, which leaves the box up.loggerreaches the box's journal by name. 0.7.0 saidlogger --journaldlands inomabox log journal, but in a boxloggeris omabox's own stand-in, which wrote~/logger.log, so the journal stayed empty unless you typed/usr/bin/logger. Nowlogger --journaldand a plainlogger [-t TAG] MESSAGE(or its stdin's lines) go to the journal, as on your desktop;logger -t omarchy-shell, the shell launcher's, still goes toomabox log shell.systemd-catby its bare name still writes~/IDENTIFIER.log(the box's shell relies on it): use/usr/bin/systemd-catfor the journal, as the help now says.upsays when the box's bar is your desk's, not Omarchy's. A box copies your bar's layout andshell.toml(its sizes and fonts), and--themeleaves both as they are, so a shot or a measured icon size taken "on a stock theme" came out of your bar without a word. Nowupsays "seeded the bar from your desk: its shell.json layout and shell.toml [font], [bar] (--stock-bar starts from Omarchy's default)" when they differ from Omarchy's (names only), and the skill's row for theme-dependent results says--theme NAME --stock-bar.--stock-barfrom a save now drops the save'sshell.tomltoo.runsays when the command runs in the box HOME because the box lacks your current dir. Outside a repo a throwawayrunmounts nothing of the current dir, soomabox run -- python3 tests/x.pyfrom a scratch copy failed with "can't open file '/home/sbx/tests/x.py'", which read as a wrong path. When a word of the command (or of ansh -cscript) is a path in your current dir and the box does not have that dir,runnow says so first, with the mount that brings it in (run --overlay DIR, or--ro-bind DIR; for a box that is up,down, thenupwith it). A plainrun -- appsays nothing.record stopno longer waits forever on a stuck ffmpeg. ffmpeg 9.0.1 now and then deadlocks (about 1 run in 100 of the same encode), andrecord stop(orrecord sheet) then hung. Each ffmpeg and ffprobe step a recording runs now has a time limit, 60 s and 5 s more for each second of 1080p at 30 fps it recorded (so a long recording still has the time to encode); one that runs out is killed and run once more, and a second timestopsays so and fails, keeping the raw recording in the box as its other failures do.omabox audio's ffmpeg is bounded too.treeputs what is inside a Qt Quick dialog where it is drawn. A Qt Quick popup with the dialog role (a settings or add sheet) read@0,0, and everything in it relative to the sheet, not the window (Qt measures from it), so a click at a row's middle landed on what was behind the sheet, andcheck point --window SEL -gon a sheet compared the elements behind it instead of its own.check's--ignoreholds for the tree too. A region left out of a checkpoint (a time the app shows) still changed its tree, so--approvesaw every run differ and named the wrong cause for an app whose layout moved in one start of three, and a check a minute later read changed. An element wholly inside an--ignoreregion is now left out of the tree's comparison and the report; anunstabletree line says the element's box, so the region can be made to hold it.baseline.pngstays readable with many checkpoints. It fitted every checkpoint into one image, so 28 of them came out 40-70 px wide each. Each shot now keeps a size you can read a screen at (about 400x225 for a window), and what does not fit one look goes on more pages,baseline-2.pngand on, all named when--approveends.- One change seen in many checkpoints is said once. A margin that moved the same rows in 17 checkpoints of one sheet listed its regions and tree lines 17 times, and the report showed the same card until it ran out of room. A checkpoint whose change an earlier one had (the same tree changes and no other pixels; without a tree, the same regions) is now one line,
changed ID: as FIRST, still counted as changed (18 changed (16 as another)), and the report names it on the first one's card. treeprints no warning on every call with at-spi2-core 2.61 or later. That version droppedorg.a11y.Status.ScreenReaderEnabled, and eachtreesaid it could not set it, a line that broke--find's one-line answer and--jsonread with its errors.treenow leaves it alone where it is gone and says why only when an app is not on the accessibility bus: an egui/winit app on AccessKit before accesskit_unix 0.22 waits for that property, so it has no tree there. libatspi's warning about such an app's missing cache, whichtreedrops, is dropped under libatspi's new log name too.- A plugin that loaded is no longer said to have a warning on Quickshell 0.3.2. That version warns about every plugin folder outside the shell's config folder, as all of Omarchy's are, and
upandrestart-shellprinted it as each plugin's own warning ("plugin ID loaded, with a warning in the shell log: Module path ... is outside of the config folder"). That message is left out now; any other line naming the plugin still shows. - Omarchy's idle-spawn test passes in a box. The box's stand-in for the plugin registry's
inotifywaitstarted asleep 5every 5 s for as long as the shell ran, so Omarchy's own "an idle shell starts no processes" test failed in every box (6 sleep 5). It now waits on its stdin, which the shell holds and never writes, and starts nothing; it still ends with the shell. downremoves a box's HOME even when an app in the box left a read-only folder in it. The HOME (~/.cache/omabox/BOX) stayed behind,downprinted only rm's "Permission denied", and the next box under that name started with its leftovers. A HOME that still cannot be removed is now said on stderr, bydownand by the clean-up at eachup.run -d --replacewith other arguments names the job it leaves running.--replacestops only the job started with the same command and arguments, so relaunching./build/app --demo tableafter./build/app --demo detailsleft both running, while the note said "no earlier job of this command". It now says which job of that program still runs and how to deal with it:--replace: no earlier job with these arguments; ./build/app (pid 115, --demo details) still runs: stop it, or --replace with its arguments. The skill's line says "the same command and arguments".omabox downnames your session's box when the directory's name has none. A box is named after the directory a command runs in, so a box started in a scratch folder and adownrun later in a worktree said only "no box '…'" and exited 0, leaving the box up. When your session has boxes up under other names,downnow names each, where it was started and the command that takes it down (this session has 'default-…' (started in ~/…): omabox down -b default-…), and exits 1.
0.7.02026-10-16
Hold keys across commands, a journal in every box, CPU per thread, and an opt-in skill for reporting what omabox got wrong. Print no longer kills a box on NVIDIA, tree reads egui apps, a box loads your Hyprland bindings and input settings, and a crash says it crashed, with the signal. A box refuses the coding agents' and the browsers' own stores, as it does other secrets. Includes 0.6.2's security fix. The guard's hooks changed and now say when an update changes them: run omabox guard on (or omabox setup) once.
Added
keys down:KEYandkeys up:KEYhold a key down across other commands.keysonly tapped, so a bind on a key's release, or anything that happens while a key is held, could not be tested: nowomabox keys down:XF86Tools, thenomabox pointer move …, thenomabox keys up:XF86Toolsfires the press bind, then the release bind, as a held key does. A held key joins the others as on a real keyboard (down:super, thenkeys ais SUPER+A;down:shifttypes capitals), and a held letter repeats in the app until let go. Pressing a held key again, or letting go of one that is not held, is an error, before any key of that call is sent; anything still held goes with the box, and a key whose holder was killed outright is let go, once, by the nextkeys.- A box has a journal:
omabox log journal. A program that logs only to the journal failed in a box: a test harness that starts its own accessibility bus from a cleaned environment got "at-spi-bus-launcher exited with 1", because the dbus-broker it launches exits when it cannot reach/run/systemd/journal/socket. Every box now has its own journal sockets there (the native one and the stdout stream; never your host's), and what comes in goes toomabox log journal, one line per message with the sender's name and pid: dbus-broker,logger --journald, a--systemdbox's units' output. The log keeps at most 4 MB, then starts again (the one before asjournal.1.log). Still no journald:journalctlreads nothing in a box. omabox-feedback, an opt-in skill for reporting what omabox got wrong. Off unless you runomabox setup --feedback-skill(--no-feedback-skilltakes it out; a plainomabox setupnever adds it). Then/omabox-feedbackhas your agent look back through the session (in Claude Code, every subagent's transcript too) for omabox failures, refusals, workarounds, missing commands and misleading docs, check them against the issues, and file them on your yes, after a short list you can ask to see in full or change. Your paths, names, hosts, tokens, projects and the session's content are taken out of every draft first; a safety problem is never filed, only pointed to SECURITY.md. It runs only when you ask;/omabox-feedback autofiles without the question.--windowtakes a hyphen-separated part of the class.--window portal(orgtk) finds a window of classxdg-desktop-portal-gtkwhen nothing matches the word as a whole class, a last dotted part or part of a title; those still win, and a word matching several windows is still refused with each one listed.upsays when a plugin under test gets your desktop's settings, and--no-seed extensionsstarts without them. A box gets a copy of your~/.config/omarchy/extensions, where shell plugins keep their settings (an on/off switch for their key binds, say). A--pluginwhose switch was off on the desktop bound nothing in the box, and the test failed with only a timeout. Nowupprints "seeded extensions/NAME.json from your desk: plugin ID reads it" for each such file, and--no-seed extensionsgives the box a new Omarchy user'sextensionsinstead. The skill now lists everythingupcopies from your desktop.upandrunsay when a path in the repo links out of it, to what the box does not have. A build cache that turnstarget/into a link to~/.cache/…left it dangling in the box (your HOME is not mounted), andrun -- target/debug/appsaid only "No such file or directory". Nowupnames each such link at the top of the repo, andruneach argument that goes through one, with the--ro-bindthat mounts its target when that is a cache, outside your HOME or in no hidden folder of it (a repo's link may lead anywhere: elsewhere no mount is offered).- A box refuses the coding agents' and the browsers' own stores, as it does the other secret stores:
~/.claude,~/.codex, OpenCode's, pi's, Hermes' and Gemini's, the browser profiles (~/.mozilla, Chromium, Chrome, Brave, Vivaldi, Edge) and~/.pki, whether by--ro-bind,--seed,--overlayor a plugin. cpu --threads: CPU per thread. With--app NAMEor--pid PID, each of the app's threads is listed under it by name, over the same window: a Qt Quick app's main thread apart from itsQSGRenderThread, each thread of a pool on its own row.--jsongives them asprocesses[].threads[](tidas the box numbers it,host_tid,name,cpu). Without--appor--pidit is refused: every process's threads would bury the app's.- The guard's hooks say when an omabox update changed them. What
omabox guard onwrites into Claude Code's and Codex's settings changes now and then, and the old hook kept working, so nobody was told: onlyomabox guardread it as outdated. Now each hook carries a stamp, and at session start, when its omabox ships another, it adds one line to its note: "this hook is outdated (omabox changed it): tell the user to run omabox guard on to renew it". This version changes both hooks itself, so runomabox guard on(oromabox setup) once after updating: the last time a change to them goes unannounced.
Fixed
omabox treereads egui and other winit (AccessKit) apps. An egui app on eframe 0.36 or older never joined the box's accessibility bus: its AccessKit waits for a screen reader (ScreenReaderEnabled), andtreeonly turned on what Qt waits for.treenow sets both, and libatspi's "Unknown object '/org/a11y/atspi/cache'" warning, printed after every such app's tree, is gone.- Print (Omarchy's screenshot) no longer kills a box on NVIDIA. The screenshot turns hardware cursors on while it runs, and Hyprland then wrote the cursor into a buffer NVIDIA cannot map: the box's Hyprland crashed at the next cursor change (the selection going away, a pointer move). A box now draws hardware cursors on the GPU; nothing changes on other GPUs.
- A box loads
~/.config/hypr/bindings.lua,input.luaandlooknfeel.luafrom its HOME, as Omarchy does. An edit there, thenomabox hyprctl reload, did nothing: a box never loaded them, so a plugin's "add this line tobindings.lua" (or its own Set up button) bound nothing, and the reload still answeredok. A new box's are Omarchy's comment-only files, so nothing changes until you write to them.monitors.luaandautostart.luastay unloaded: the box's screen is the one--size,--monitorandmodegive it, and nothing autostarts. A file with an error does not stop the rest of the config loading, andup,reloadandhyprctl reloadnow print the config's errors (what the red bar at the top of the box's screen says) instead of answering onlyok. A box started before this update loads them afteromabox reload. run -- wl-copy TEXTreturns. A command that left a process running (wl-copy's server, adaemon &) keptrun's output open, so$(omabox run -- wl-copy TEXT), or a run whose output went to a pipe, waited until that process ended, and everyrunwriting to a file paid a second for it. Nowrunreturns as soon as its command exits, with its status and all of its output; what the process it left writes after that is dropped (that process keeps running). For a process you want to keep the output of, userun -dand its log.- A call that crashes the box's Hyprland says it crashed, with the signal.
omabox lua(andhyprctl,windows,shotand the rest) said "its Hyprland did not answer (hung?)" when Hyprland had just segfaulted. Now: "went down: its Hyprland crashed (SIGSEGV)", with how to get a backtrace (omabox gdb --watchbefore the call, in a new box: boxes keep no core dumps), or where it is when one was watching (omabox log gdb --crash). A later call to that box says it too. omabox log gdbputs the thread a crash hit first. Aftergdb --watchcaught a fatal signal, every thread's backtrace followed it with Hyprland's main thread last, after its worker threads. The thread the signal hit now comes right under the signal line, then every thread;omabox log gdb --crashprints only that thread's backtrace for each crash.shot -gpast the window or the screen is cut to it.shot --window SEL -ga few pixels past the window was refused ("not inside window"), and-gpast the screen gave an image padded with transparent pixels. Both now take the part inside and say so on stderr, by edge (-g clipped to 1380,40 474x330 of window …: 6 px past the right edge), exit 0; only a region with nothing inside is refused.omabox ls --jsonhas the Hyprland version of every box.hyprland_versionwas null for a box on the installed Hyprland, the usual one; it was recorded only withup --hyprland. Now it is the first line of the box's ownhyprctl versionfor each boxupstarts. The skill names the keys to report from (omarchy_version,hyprland_version).omabox lsrefuses arguments it does not take.ls -b NAME --jsonprinted the table and exited 0, as didlswith any unknown flag. Now-bafterlssays "ls takes no -b", as before it, and anything else but--jsonis an unknown argument; both exit 2.omabox savestoo:saves --json --bogusprinted the JSON and exited 0. Andomabox --version(version,-V):version fooprinted the version and exited 0.omabox treeno longer prints libatspi's warnings after a tree it read. A warning about another app on the box's accessibility bus came out as a strayomabox: tree:line; now they show only whentreefails.omabox lsno longer calls a box whose Hyprland just crashedhung. In the moment before the box goes down it sayscrashed(orgoing), inls --json'sstatetoo. An interactive box's crash now names its signal at once, as a headless box's does.- The skill shows
wait changeagain, for an app that redraws later by itself (a sync, a timer):omabox wait change --window APP, thenwait still. Without it agents slept withwait cmd -- false.omabox help waitsays whatchangewaits for. - The guard no longer piles its line into Claude Code's session environment. Its hook added the line again on every resume and compaction, so a long session sourced it many times before each command. It is written once now, an older omabox's replaced.
omabox guardreads the hook as outdated:omabox guard onrenews it.
0.6.22026-10-16
A security fix over 0.6.1, and nothing else. A process in a box could write into what omabox printed of nsenter's own messages on a call into the box (any amount, control characters included), and reach files the caller of omabox gdb or restart-shell had open above fd 2 through omabox's own steps in the box. Update.
Fixed
- nsenter's own messages are read through a bounded pipe and printed only when they look like nsenter's. What nsenter (and the shell it starts in the box) said before a command's own stderr took over was held in a temporary file and printed whole; it is now held in a pipe, read up to 4 KiB, and only nsenter's own lines, without control characters, are printed; anything else is dropped and counted.
gdb's andrestart-shell's own steps in a box now get only the files they are meant to have, asrun's commands do, not every one omabox had open.
0.6.12026-10-14
Security fixes, and a fix pass over 0.6.0. A process in a box could reach the host files you gave omabox run as stdin, stdout or stderr, your terminal, and other files the caller had open, through the box's own view of /proc; omabox's own helpers in a box ran from the box's PATH; and a jailed agent's shot --to-fd took its own /proc files. Update. Also omabox record for agents inside ai-jail, and four fixes from a review of 0.6.0's new features.
Added
- Videos people can follow:
record stop --show-input,--captions,--cut-idle,--glide.--show-inputdraws what omabox's clicks, pointer moves, drags and keys did into the video, aspeekshows them, at the times they happened: a ring over the pointer, a ripple from each click, key captions at the bottom (a--passas*).--captionsputs therecord marktexts at the top.--cut-idle [1s]cuts every still stretch (no change on screen, no input, no mark, no sound) down to that, and moves the marks and captions with it.record start --glide 600ms(or--glideonclick,pointer,drag) makes the pointer travel there in that time instead of jumping, while agents' clicks stay instant otherwise (#176). omabox recordinside ai-jail. A jailed agent'srecord start -o demo.mp4,mark,stop,record -- ACTIONandrecord sheetwork as outside: the video, its marks, captions and contact sheet land in the jail's project, written there by the agent's ownomabox; the broker writes and reads them only through the files it was handed, never at a path the jail names (#224). A video is at most 16 GiB (an hour of 4K):record stopsays so and keeps a larger one in the box.
Fixed
record --no-pointer -- ACTIONended by Ctrl-C while the action ran showed the pointer again although the recording went on; it stays hidden untilrecord stop, as a plainstart's does.--show-inputdrew the pointer's ring 40 ms early for each scroll or drag pause in a line.up --desk-shellkept a plugin's config out of the box when a setting's name only contained a word like token or password ("maxTokens": 4); only a key of that name with a value is a secret.omabox tree --findpaths lost an ancestor past 64 printed levels.- What omabox runs in a box for itself is the system's. Its own steps there (recording, the clipboard,
up's checks) run the box's/usr/bintools by their paths, not what the box's own PATH would pick, and what omabox reads back from a box is bounded on its side. A command in a box (omabox run) gets stdin, stdout and stderr, and no other file the caller has open. - A box command's stdin, stdout and stderr are never your files. They reach the box as pipes held on the host (a terminal of its own when you run a command from one), so no process in the box can open them again through
/procand read or write a host file you redirectedomabox runto, or your terminal. Since 0.1.0 it could, while the command ran. A command run from a terminal with its output elsewhere (omabox run -- cmd > log,| less) no longer reads the terminal.
0.6.02026-10-14
Agents can read a window as text (omabox tree), check how their model reads click points (omabox calibrate), and make videos with sound, marks and every monitor (up --audio, record mark, record --monitor all, --no-pointer). A box can mirror your whole shell (up --desk-shell), ls names boxes nobody will take down (down --orphans), and fast shot --burstes no longer stall what they record. Fixes for scaled and turned screens, video colours, and the Codex guard. Packages: two new tools, omabox-burst (libpng) and omabox-tree (at-spi2-core, glib2).
Added
- Text instead of a shot:
omabox tree. A window's accessibility tree as compact text: each control's role, name, text, value and state (checked, focused, selected...) with its bounds in the coordinatesclick --windowtakes. Ask first:omabox tree --find 'dark mode'prints the one line that answers "is Dark mode checked?" (~17 tokens against a shot's ~1.5k), and the middle of its bounds is where to click. For GTK and Qt apps (treeturns Qt's tree on), and Chromium or Electron started with--force-renderer-accessibility; a terminal or the Omarchy shell says "no accessibility tree" (#178). omabox calibrate: does this model need--fitto click right? It draws a test card the size of a full shot of the box, six lettered crosses at random points; the agent reads it as it reads a shot and answers where it sees them (omabox calibrate --answer "A X,Y B X,Y ..."). omabox fits the readings and says whether full-size shots read 1:1, else the--fit Nwhose shots, withclick --in, land within a few pixels, and theomabox config shot-fit Nto suggest to you (it never sets it), or that no one scale fits (read again). For any model and harness, without knowing either (#188).- Your desk's whole shell in a box:
omabox up --desk-shell. Every plugin in~/.config/omarchy/plugins(read-only, as--pluginmounts one; a--pluginof the same id wins, for your working copy), yourshell.jsonas it is (only idle held off), and the other files in~/.config/omarchyyour plugins read, such as a plugin's JSON or a folder of profiles, copied into the box. Neverapi-keys.envnor anything named or holding a key, token, secret or password, your hooks, a git dir or a backup; regular files only, with a size cap, and a link only to a file inside the folder.uplists what went in and what did not, and why (ls --json:desk_shell), so a widget can be checked against the bar you really have (#206). - Sound in a box, and in its videos.
omabox up --audiogives a box its own PipeWire (Pulse apps too) with a speaker nobody hears as its only output and a silent microphone: an app's sounds play, and never reach your speakers or your audio server.omabox audio 3listens for three seconds and says whether the box made a sound, when and how loud (--jsonfor every 100 ms), so an agent can check a notification sound or a player without hearing it.omabox record start --audioputs the sound in the video (AAC), in step with the picture to about 15 ms, with--monitor alltoo (#226). - A video of every monitor at once.
omabox record start --monitor all(andrecord --monitor all -- ACTION) records a box's whole layout as one video, laid out asomabox shottakes the screen: each monitor at its place, a lower-scale or turned one as it is shown, the gaps black, the video the size of the shot. The monitors are kept in step by their own frame times, so something drawn on two of them at once shows in the same frame; marks and contact sheets work as for one monitor. A layout too big for H.264 is scaled down to fit, and said (#225). - Marks and contact sheets for
omabox record.omabox record mark "scene 2", while a recording runs, notes the text at that moment in the video's own clock (milliseconds from its first frame, exact to a few ms), andrecord stopwrites them beside the video:demo.marks.tsvanddemo.vtt, captions any player loads orffmpeg -vf subtitles=demo.vttburns in. They also show where a script of omabox calls and sleeps drifts from its plan.record stop --sheet(oromabox record sheet demo.mp4) makesdemo.sheet.png, a contact sheet of the video's frames with their times and the marks under them (--frames N,--every 2s,--fit N), so an agent can check a take without watching it (#176). - Shots and videos without the pointer.
shot --no-pointerandrecord --no-pointerleave the pointer out, for stills and videos meant for people: no arrow on the app, and none parked on something with a hover state. It is shown again afterwards, as it was, also when the shot or recording fails or is stopped (#228).omabox pointer hide(orup --no-pointer) hides it in a box untilomabox pointer show, and it stays hidden over config reloads and theme switches, so a series of stills across themes needs it once. Hidden, the pointer still moves, clicks and gives focus as before. lstells a box nobody will take down. A headless box at--idle 0with no agent session to go with has nothing to end it, and when the script or agent that started it was gone it stayed up for good, listed like any box in use (#220).upnow records what started a box;lssaysorphanunder IDLE for such a box once that is gone (ls --json:orphan, andstarter), the bar widget says it on the box's row, andomabox down --orphanstakes those down, naming each. Nothing takes one down by itself, and a box you start at a terminal is never one.up --idle 0says, to a caller that is not a terminal, that nothing will take the box down butomabox down.- Addresses of its own for an isolated box.
up --net isolated --addr 203.0.113.10 --addr 203.0.113.11puts those addresses on the box's loopback, for apps that judge their network by where a peer comes from: a BitTorrent client reads "firewalled" until a peer connects from a non-local address, and in an isolated box every peer was on 127.0.0.1. A server on one sees a client bound to another come from there. Nothing in the box could add one itself. Documentation ranges only (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32), so they never stand for a real host;--allowforwards are unchanged.lslists them under the box,ls --jsonasaddrs(#229).
Fixed
omabox shot --burstno longer holds up what it records. Each frame was a grim of its own, and each grim four Hyprland events: a shell or widget that works on every event (as widgets do to refresh) was held up by a fast burst, so its timers and animations stalled in the very frames meant to show them. A burst is now one capture client in the box for all its frames, four events in all, so--every 0(back to back, ~15 ms a crop) shows an animation as it runs. Frames are the same imagesomabox shottakes. A box started before this update still takes a frame at a time until it is started again (#196).omabox record's colours. Every video came out washed out: pure green as #0cea0d, white as #e8e8e8, black as #101010. wf-recorder wrote its frames' values in TV range (16-235) but marked them full range, and every player believed the mark. Videos now come out in the standard form players and browsers all read the same (H.264 4:2:0, limited range, BT.709, and marked so), a pure colour within 2 levels of the screen's;--monitor alland contact sheets alike. Videos made before keep their muted colours.- Turned (portrait) monitors. A monitor turned by its transform (
hl.monitor({ ..., transform = 1 })) was taken at its unturned size: a 1280x720 one turned upright counted as 1280 wide and 720 high. The screen's size was wrong (shotsaid 2560x1080 of a 2000x1280 layout), soclick,pointer moveandpixelwere refused or landed elsewhere below its old height, andshot --monitorof it took the wrong part, partly black. Every monitor's size in the layout now follows its transform:shot,shot --monitor,--fit,click --in,pointer,pixeland an interactive box's windows on a turned host monitor. - A
runkilled while its throwaway box starts takes the box with it at once. Killed outright (SIGKILL, a harness's timeout) before its box was ready, the box'supwent on to the end, waiting for the bar, and the box went only once its reaper got the box's lock after that: seconds later under load. Theupnow notices its run is gone and ends the box itself (#222). omabox gpuexits 0 when no process has GPU figures. On a GPU whose driver keeps no per-process counters (a VM's virtio GPU) it printed its header and ended with 1, before saying "(no GPU time)". It says so now, and exits 0.shot --fit Non a scaled screen. It compared N with the layout's size, not the image's: at--size 2560x1440,scale=2,--fit 2000gave the full 2560x1440, and a window's shot came out at twice N. The longest side is N now on any screen, window, region or mix of scales.shot --window -gandpixel --windowon a scaled monitor. They read the window's buffer pixels as its own coordinates: at scale 2,-g "10,10 300x200"took the window's 150x100 at 5,5,click --inthat shot missed by the scale, andpixel --window X Yread X/2,Y/2. Both take the window's own coordinates now, as the help says.- The bar widget's mark keeps its size beside the box count. On Omarchy with fitted bar icons (after 4.0.4) the count was scaled down with the mark, and the mark shrank from 12 px to about 7 px as soon as two boxes were up. The count is drawn beside the mark now; on 4.0.4 the widget looks as it did, except that the mark no longer moves up a pixel when the count shows.
- A bare "shot: grim failed" says how grim ended when grim gives no reason of its own: an empty image, nothing in 10 s, or the status it ended with. A shot grim gives an empty image for, which happens now and then under load, is taken once more.
- The Codex guard works with your own
shell_environment_policy.set.guard onrefused a~/.codex/config.tomlthat already had one, and told you to add its keys by hand, after whichomabox guardsaidoutdatedforever. It now adds its keys to your table between its markers, andguard offtakes out only those. Keys you merged by hand read as on, andguard onmarks them. Your own value for one of the guard's keys is never overwritten:guard onsays which one.
0.5.52026-10-14
Sharp, high-resolution screenshots and videos of a box: a scale for the main screen (--size 3840x2160,scale=2) and a new omabox record. On NVIDIA, apps in a box now draw on the GPU instead of in software, and omabox gpu gives per-process figures there.
Added
- A scale for the main screen:
up --size 3840x2160,scale=2andomabox mode 3840x2160,scale=2. The box lays out as 1920x1080, with the bar and apps at their usual size drawn in twice the pixels, so ashotis 3840x2160 and stays sharp when you zoom or crop it. Scale 1 to 4, as--monitor's; coordinates stay the layout's, andclick --inmaps a shot's. Headless boxes only. omabox record: a video of a box's screen.record start [-o FILE] [--monitor NAME] [--fps 30], thenrecord stop, which prints the file: an H.264 MP4 at a steady frame rate, at the screen's own pixels (4K from a box at--size 3840x2160,scale=2).record -o FILE -- ACTIONrecords one action (keys super+space,click X Y, ...). Needs wf-recorder and ffmpeg. Not yet for agents inside ai-jail (#224).omabox gpuon NVIDIA. NVIDIA's driver reports no per-process DRM counters, sogpulisted nothing there. It now takes the driver's own per-process sampling throughnvidia-smi pmon, for the box's processes only: whole seconds, each process's share of the GPU as sampled once a second (--jsonhassource).
Fixed
- Apps in a box on an NVIDIA GPU draw on the GPU (#204). They fell back to Mesa's software renderer (llvmpipe): NVIDIA's Wayland EGL looks for the GPU's card node, which a box never has, and gave up without trying the render node the box does have. An NVIDIA box now has an empty read-only file at that path (never the device), and its apps and bar render on the GPU. Vulkan in an NVIDIA box is unchanged (
vulkaninfostill crashes).
0.5.42026-10-13
A security fix for agents inside ai-jail driving boxes through the broker: update if you use omabox broker on. A jailed agent's box now has its project even when the jail hides files in it. Also new: back and forward mouse buttons, and up, ls, gpu and cpu say when a box's apps render in software.
Added
- Back and forward mouse buttons (#216).
click X Y back,forward(alsoside,extra), indragandpointer -- click|down|up BTNtoo: a mouse's thumb buttons, which apps take as back and forward. - A 0x0 output on NVIDIA is said (#213). In a box on NVIDIA an output the app makes itself (
hyprctl output create headless) comes up 0x0 with no error.monitor listandshotnow say so, why, and which box to test it in instead (one on your AMD/Intel GPU,OMABOX_RENDER_NODE). - Apps rendering in software are said (#204). In a box on NVIDIA, apps get Mesa's software renderer (llvmpipe), so their CPU and frame cost there is not the GPU's.
upnow says so once, with a box on your other GPU to use instead;ls,gpuandcpushow anapps:line, andls --jsonaclient_renderrecord (fromeglinfo, when mesa-utils is installed).
Fixed
- A jailed agent's box has its project even when the jail hides files in it (#210). An agent in ai-jail whose project had a path the jail hides (an
ai-jail --mask, or the project's own.ai-jailfile, which ai-jail hides by default) got a box without its project:runstarted in the box HOME. Now the project is mounted with those paths hidden in the box as in the jail (empty), checked before the box starts. So are--ro-bindof such a folder and a git worktree's main.gitwith a hiddenconfig. Plugins, themes,--omarchy,--hyprlandand--overlayinside such a project are still refused, and so is--seedfrom one whose hidden paths sit below its folders. The check needs/usr/bin/python3(packagepython): without it the project stays out, as before, andupsays why. If you replace a hidden file on the host while the jail runs, ai-jail stops hiding it, andupfrom that jail is refused until the jail restarts. - A frozen shell reads as
hung, notrunning(#209). A shell whose pid lived but which answered nothing (a crash whose handler hung, its bar left frozen with no report and no relaunch) was taken as healthy bylsand every command. Nowls(andls --json'sshell_state) sayshung,shot,windows,keys,click,scroll,pixelandwaitwarn, andrestart-shellkills it at once and says so (it waited 10 s on it before). - No hidden X server in a box without
--xwayland(#211). The box's parent compositor kept a lazy Xwayland on:0: an X client that setDISPLAY=:0itself ran, but its window was on a screen nobody sees (windowsnever listed it,wait windowtimed out). Now there is no X server unlessup --xwayland, so such a client fails with "unable to open display", and--xwayland'sDISPLAYis:0(it was:1). - The bar widget keeps the theme's colours on Qt 6.12. Qt 6.12's QtQuick brings its own
Colortype, which shadows Omarchy's palette singleton, so the widget'sColor.foregroundandColor.urgentfallbacks no longer reached the theme. It readsCommons.Colornow, as Omarchy's shell does since its b83d3df. - CUDA works in a box on an NVIDIA GPU (#149). The box had the GPU's node and
/dev/nvidiactlbut not/dev/nvidia-uvm, which CUDA allocates through, socuInitfailed (999). It is bound now when the driver has made it. Wayland EGL and Vulkan in an NVIDIA box are unchanged (#204). run -d --waitsays when the command already exited (#215). A command that ended at once (say, on a file under/tmp, which a box does not mount) was reported as "started all the same" with 124, pointing at the screen. Now it says the command exited with status N, names any argument that is a host path the box does not have, shows its log's last lines, and exits with that status (124 still when it was 0).scroll --source fingerandtiltarrive as a touchpad and a tilt (#214). Hyprland dropped the source omabox sent first in each frame, so a finger scroll reached apps as a wheel's small notches (no kinetic scrolling, Qt with no scroll phases) and fired a wheel bind per frame, and a tilt's first notch came as a wheel. It is sent last now.help scrollalso says why a Qt QuickWheelHandlerat its defaults ignores every wheel, a real mouse's too (a Qt bug), and what to set.
0.5.32026-10-10
Security fixes for agents inside ai-jail driving boxes through the broker: update if you use omabox broker on. Also new: omabox cpu, omabox path --run and omabox config shot-fit.
Added
omabox path --run: where a box's /run/user/$UID is on the host (#208):<dir>/run, the box'sXDG_RUNTIME_DIR, where an app's runtime state (astatus.json, a socket) is read from the host. The host's own/run/user/$UIDis your real session's:omabox help pathand the agent skill now say so, after an agent read a desktop app's state there instead of the box's.omabox cpu: CPU and memory of a box's processes (#205),gpu's twin.omabox cpu [SECONDS] [--settle S] [--pid PID | --app NAME] [--json]gives each process of the box (never the desktop's, whichtopandpgrepmix in), or one, its CPU over the window as % of one core, RSS and PSS, and a total. A process that starts or exits during the window is counted for what was seen of it, and says so. No more hand-written samplers of/proc/PID/stat, or asleepbefore them.omabox config shot-fit N: a default size for every shot (#188). Some models read click points in the smaller image their API scales a big shot down to (Haiku 4.5: hundreds of pixels off on a 1920x1080 shot); whoever runs one setsshot-fit 1456once, and everyshotgiven no--fitcomes out as with--fit 1456,click --inmapping it as usual.OMABOX_SHOT_FIToverrides the setting (an agent inside ai-jail's too),--fit Non a shot wins, and the new--fit 0takes one full size. It reaches what--fitreaches (window shots,-g,--monitor,--burst,drag --shot), not--changedor--zoom.
Fixed
output backon an NVIDIA box brings the main screen back at its mode under load (#200). When the box's labwc was slow to size the new window, the screen came back at 1280x720,output backfailed, and the box listed it twice (on screen, and as dropped):modeand the nextdropthen refused it as away. Its mode is now set again until it holds, and a screen made again is never kept as dropped.- A peek window survives its monitor dropping (#200).
omabox peek --monitor NAMEof a monitor thatomabox output droptook away kept asking the box for the dead screen, and its window died (or froze on the last frame); afteroutput backit never showed the monitor again. It now lets the screen go: its window turns dark, saysNAME is gone, and its title ends(gone); when a monitor of that name comes back it shows it again. keys --windowno longer types into a launcher that has the keyboard (#201). With Omarchy's launcher (or another layer that holds the keyboard against any window) open,keys --window SELexited 0 while the text went into the launcher's search field. It now refuses before sending or focusing anything, exit 1, naming the layer:a layer (omarchy-menu) has the keyboard. It also focuses the window when it is already the active one, the pointer left where it is: a window can be active without the keyboard (after such a layer closed with the pointer over no window, or with a panel that takes the keyboard on demand clicked), and the keys went nowhere or to the panel.- Git works in a jailed agent's box from a git worktree (#193). Inside ai-jail, a box started from a linked worktree still had no git (
fatal: not a git repository): the main checkout's.gitwent in only outside a jail, where git itself is asked. omabox now reads the worktree's.gitfile andcommondirinstead, never running git on the jail's files, and mounts the main checkout's.gitread-only when the jail has it as a folder of its own (ai-jail --worktreemaps it so). - A box starts on the wallpaper the desk has, one of your own too (#184). A wallpaper added with Omarchy's background install (
~/.config/omarchy/backgrounds/THEME/) gave a box with no wallpaper: its background link led to a path the box does not have, and the shell started withOMARCHY_STARTUP_BACKGROUNDempty. The box now gets a copy of your wallpapers for its theme (images only, none followed through a link, up to 64 MiB each and 256 MiB in all) and its link leads to the copy;up --theme NAMEbrings NAME's, and the box picks from them as Omarchy does. A background set from elsewhere gives the box's first, never a link to a host path. - A theme installed from git stays one in a box (#184). The box's copy left out the theme's
.git, so the box'somarchy-theme-settook its Lua and app configs, which the desk ignores. The copy now has an empty.git(nothing of the real one), and the box treats the theme as the desk does. - Security: a jailed agent's
upsays nothing of host paths outside its jail (#198).uplooked at each path it was given before checking the jail, and its refusal named where the path led: from ai-jail,up --seed /etc/localtime:xanswered with the zoneinfo file it links to, and "no such path" for one not there, so an agent could learn whether any host file exists, or where a host link leads (nothing was copied or mounted).--seed,--theme-dir,--overlay,--ro-bind,--plugin,--hyprlandand--omarchynow follow a jailed agent's path only inside the jail's folders, through links in its project too, and refuse one that leaves them with the same words whether anything is there or not, naming the path as written. Outside a jail nothing changes. - Security: a jailed agent's
upruns no host program or git on paths the jail can write (#198). A jailedup --pluginorup --omarchyhad the broker rungit statuson the agent's own plugin dir and--omarchytree to read their commit, andcore.fsmonitorin a.git/configthe jail writes runs a program ongit status;up --omarchyalso ran that tree's ownbin/omarchy-plugin-validate, both on the host, outside the jail. The commit is now left unknown for a jailed caller (no git is run), and a jailed caller's plugins are checked with the host's installed Omarchy validator, never the tree's. - Security: a jailed agent's
up --seedrefuses a file ai-jail masked (#198). ai-jail's--mask/--deny-pathput an empty file over a path while the real one stays on the host, and the box seeds from the host, soup --seed SECRET:xcould copy the masked host file into the box. A jailedupnow refuses a--seedat, under or holding a path the jail masks, where the jail's mounts have it now (a folder the jail renamed included), and refuses every seed if it cannot tell which paths are masked. A jailed agent's box from a git worktree no longer gets the main checkout's.gitwhen the jail masks a path inside it (itsconfig, say). Outside a jail nothing changes. - A jailed
up --omarchywith a relative path works../treewent to the broker as written, so it was refused as outside the jail. - A git worktree of omabox runs headless NVIDIA boxes on its main checkout's aquamarine build (#182). A fresh
git worktree addhas nobuild/prefix, so its boxes on NVIDIA were refused for lacking aquamarine's fix the main checkout had built. A worktree with none of its own now uses the main checkout's (omabox --versionandomabox gpusay so), andupfrom a worktree whose tools are not built says to build them with make, not to runinstall.sh(which would link your omabox to the worktree). uprefuses a--seedinto a--plugin's or--theme-dir's folder (#199). The plugin's or theme's place in the box HOME became a folder holding only the seeded file: the plugin silently not in the box (whilels --jsonstill saidvia: linked), or the theme gone; under a mounted plugin the file was hidden.upnow says so before the box starts, naming the plugin or theme: write the file in its folder instead, or seed outside it.wait still(and every--wait) sees a thin change that is no caret (#180). Any change 4 px thin was taken for a blinking caret and ignored, however long: a tab's underline appearing or a 2 px progress bar could leave it "still" while the screen changed. A caret is now 40 px long at most, as forshot --changed, and blinks in place: a short thin segment that moves (a "working" sweep) is a change too.- A box has an accessibility (AT-SPI) bus (#177). It never started (its launcher's dbus-broker needs a journal a box lacks), so GTK apps showed no accessibility tree and any AT-SPI client, dogtail or a toolkit's a11y tests aborted.
upnow has it run on dbus-daemon, in the box's own runtime dir; it adds ~18 MB to a box.up --env ATSPI_DBUS_IMPLEMENTATION=dbus-daemonis no longer needed. - Inside ai-jail, the guard's hook no longer says omabox is gone and that it can be removed from settings.json (#203). It looked for omabox only in its checkout, which a jail sees only as the
~/.local/bin/omaboxthe broker maps in. A jailed agent got the guard's usual note instead. Runomabox guard ononce to update the hook. - omabox's bar widget stays quiet inside a box (#207). A box that mounts every plugin of your desk brought the widget along, and with no
omaboxin the box it notified "cannot list boxes: cannot run omabox" and kept the error in the box's bar. Inside a box it now draws nothing until anomaboxruns there. Restart the shell to load the new widget.
0.5.22026-10-09
omabox shot works again from a directory you cannot read, as up does since 0.5.1.
Fixed
omabox shotworks from a directory you cannot read too (ansuorrunuserthat kept root's): it wrote the image, then exited 1 with onlyfind: Failed to restore initial working directory, asupdid in 0.5.0.
0.5.12026-10-09
Fixes from a review of 0.5.0. Security: a jailed agent's up --seed could have copied a file it swapped in after the check, and a box could hang omabox ls --json (so the bar widget) with a FIFO in its runtime dir. up works again from a directory you cannot read. Update.
Fixed
omabox upworks again from a directory you cannot read (ansuorrunuserthat kept root's), where 0.5.0's ended with onlyfind: Failed to restore initial working directory.- Security: a jailed agent's
up --seedcopies what was checked. The source was resolved and checked once and copied by path later; a path swapped for a link out in between (one the agent can make in its own project) would have been followed. The copy now reads from inside the folder checked and refuses one that is not what it was. - Security: a box cannot hang the host's reads of its runtime dir. The shell's pid, the monitor list, the box environment and the parent display are read only as regular files: a FIFO a box planted there would have hung
omabox ls --json(so the bar widget) andrestart-shell; a link would have read a host file. omabox downoutside any repo takes the session's box, as the help said and the other commands do; it saidno box 'default-…'and left the box up.modeandmonitor removewait for Hyprland to move the monitors before saying which moved; the line was empty when read too soon.pixelnames a point in a gap with one monitor left, instead of "no frame from box";monitor add --namerefuses the main screen's names andFALLBACK;up --ownermust be a pid;shot --burst --after run -d -- CMD -b …passes-bto CMD;output drop NAMEnames the ones dropped before it; a jailed agent may runomabox monitor(it couldup --monitoralready).- A jailed agent's call turned away by a busy broker says so (exit 1) instead of dying of SIGPIPE (#197).
- Interactive multi-monitor boxes keep their layout file when a monitor lands on a fractional position;
wait -gignores a monitor moved out of the region;omabox peekon a stopped box gives up after 10 s instead of hanging with no window.
0.5.02026-10-09
Several monitors in one box, a box on the theme you name or the one you are editing, and new ways to see what a box did (shot --changed, shot --burst, pixel, gdb, which). Security fixes: files from ~/.config/omarchy, such as api-keys.env, could reach a box through links in your current theme or a --ro-bind inside that folder, and a box started without pasta inherited its caller's open files. Update.
Added
- A box on a theme of your choosing:
omabox up --theme NAMEstarts the box on that theme (Omarchy's, one of yours or a--theme-dirone) instead of your desktop's current one, so a test gets the same start whatever your desktop is on; with--from SAVEit wins over the save's look. An unknown name is refused before anything is made (#173). - A theme you are editing, live in a box:
omabox up --theme-dir DIRlinks the box's~/.config/omarchy/themes/NAMEto DIR, so edits afterupreach the box andomarchy-theme-set NAMEthere applies the theme as it is then. A DIR the box already has at its own path (in the repo, a same-path--ro-bindor an--overlay) is linked to there; any other is mounted read-only at its own path. Your other themes are still copies made atup, andupnow says so when one is a link into the repo you run it from, or into another checkout of it (a worktree's main one) (#170). - More monitors in a headless box:
omabox up --monitor 1080x1920 --monitor 2560x1440,scale=1.6,below, andomabox monitor add SPEC | remove NAME | liston a running one: any size, scale and place, a bar on each, kept over a config reload,removeas an unplug; one placed right or below moves with the one before it (omabox mode, an unplug).shot --monitor NAME;peek --monitor NAME, a peek window per monitor, each marking the clicks and pointer on its own monitor,downclosing them all (#164);drag --shottakes--shot-fit,--shot-g,--shot-monitor;pixelrefuses a point in a gap between monitors. On a box rendering on NVIDIA too, where they are named WAYLAND-1, WAYLAND-2, ... (#122, #165). In an interactive box each monitor is a window on your desktop, on the box's workspace without focus; together they are the box's layout scaled as a whole, as display settings draw it, laid out again at eachmonitor addandremove, and each window is a view of its monitor, which keeps the size asked for (the main screen--size's) at the window's scale: resizing a window scales its view. Closing one unplugs it. Your pointer in a monitor's window lands on that monitor, and your cursor stays shown as it goes from one window to another, with omabox's aquamarine build (omabox setup --aquamarine, then a new box);monitor addsays when a box's build lacks either (#123, #161, #174, #175). omabox output drop [NAME] [--for DURATION] [--cycles N]andoutput back [NAME]: a headless box's screen goes and comes back under its own name, mode and position, as a monitor that drops off on wake does; cycles stop at the first shell crash. It found a real shell plugin crash (#146). With--monitors, the main screen by default or a monitor by its name, each kept apart until it is back (backalone brings back all of them); while the main screen is awaymodesays so and a seconddropis refused (#163). On NVIDIA boxes too (#165).omabox up --seed SRC:DEST(andrun --seed): a file or folder copied into the box HOME before its session starts, for a plugin that reads its config once at start, where a box needed a second shell start after writing it in (#80). It gets--ro-bind's refusals (#159).omabox up --autoreload: the box's Hyprland reloads its config when a file it loaded changes, as a desktop's does, so a project can see what a file change does (a helper that rewrites a file the config loads, on a Hyprland event, reloads a desktop for ever). Boxes keep autoreload off otherwise (seeomabox reloadunder Changed).--ignore "X,Y WxH"onwait still,wait changeand every--wait, and-gon--wait: an animation that never stops (a spinner, a glow) no longer keeps them from their answer. A 124 "still changing" names the region that kept changing as an--ignoreto add (#131).omabox pixel X Yprints the colour of a screen or window pixel (#rrggbb, several points in one call,--json,--in SHOT), andshot -g … --zoom Nshows a small crop with each pixel N x N, unblended: colours and 1 px details without an image tool of your own (#133).shot --burst N [--every DURATION] [--diff] [--sheet] [--after -- ACTION]: frames of a transition into a folder, each with its time and (--diff) what changed from the one before, in the screen's coordinates (the window's with--window) whatever the crop or--fit, the action (keys,click,scroll,monitor add...) sent after the first frame, and one contact sheet of them all. A folder of its own each time, or-o DIR, cleared of an earlier burst's frames (#132, #167). Frames are 100 ms apart unless--everysays otherwise (--every 0: back to back): each grab is four Hyprland events, and faster grabs froze the animation of a shell or widget that works on each event, so frames identical to the one before are now counted on stderr (#191).shot --changed [--window SEL]: only what changed since the last whole shot of that window or screen, cropped with a margin andclick --in-able: a menu opening is ~65 image tokens instead of ~1.5k (a median 6.7x less over 17 measured actions). Nothing changed: no image, said so. A caret blinking alone and where the pointer was are not changes;--ignore "X,Y WxH"leaves out an animation;--since SHOTcompares with an earlier shot (#145).omabox scroll X Y DY [DX] [--source wheel|finger|continuous|tilt] [--mod MODS]andpointer -- hscroll DX: horizontal scrolling, a mouse wheel's notches (a DY that is not whole notches said) or a touchpad's smooth scroll with its stop, and Omarchy's SUPER+wheel binds with--mod super, wherepointer -- scroll DYwas one vertical event only (#134, #167).omabox gdb [--shell | --pid PID] [--watch]: every thread's backtrace of the box's Hyprland (or shell, or any process of the box), hung or stopped too;--watchcatches a crash intoomabox log gdb. A gdb started in the box was refused by the kernel's ptrace rules (#135).omabox config gpu auto|nvidia|amd|intel|SLOT: the GPU headless boxes render on, kept in the settings (a jailed agent'supand every terminal get it), falling back to the first GPU when that one is gone, whereOMABOX_RENDER_NODEnamed a node that could vanish or change number;omabox config gpulists the GPUs, their slots and the one in use (#156). The widget's Settings has it as a picker,lsandomabox gpushow each box's GPU (renderinls --json), andomabox gpu release GPUtakes down the headless boxes on a GPU before it goes to a VM, once anyupin progress is done (#118). A driver's name (config gpu amdgpu) is taken; a box that fell back says why and on which GPU, inup,ls,gpuand the widget (#168).omabox lshas a SHELL column:running,restarting,gone(a bar that crashed for good mid-test),+Nfor the crashes sinceup(shell_stateandshell_crashesinls --json), andshot,wait,windows,keysandclicksay when the shell is gone, and once when it crashed since the last command, where a box with no bar read as up (#147).omabox which PID: the box a host process is in, ornot in a box(exit 1). A box's bar has your desktop's command line, so a hostpgrep quickshellshowed what looked like two desktop shells. Every process a box's session starts also carriesOMABOX_BOX=<name>in its environment (--envcannot set it) (#172).- The bar widget says whether a box is up, for a rail that hosts bar widgets. It exposes
consoleAwakeandconsoleState(runningwhile a box is up), so the rail no longer reads the widget's own box count. - The README says how to open a box's server from another machine on your tailnet (
tailscale serveon your host), and what that shares.
Changed
- A
--plugininside the repo you runomabox upfrom (or a same-path--ro-bind, or an--overlay) is a link in the box, as on your desk. It was mounted at~/.config/omarchy/plugins/<id>, so a helper that finds the rest of its repo throughreadlink -ffailed in a box and worked on the desk. Any other plugin is still mounted;ls --json'splugin_statussays which (via:linkedormounted). From ai-jail, a plugin inside the jail's project no longer has to be a folder the jail was given whole (#171). - A running box keeps the Hyprland config it started with. Every box loaded omabox's config live, so a pull, a branch switch or an upgrade of omabox reloaded every running box at once and wiped the binds, rules and Lua state an agent had added; an Omarchy upgrade could do the same. A box now runs its own copy, with autoreload off (
up --autoreloadkeeps it on), andomabox reloadgives it this omabox's config and reloads it once. omabox's other scripts in a box are still the new ones from their next start (#140). - A box's shell runs under
omarchy-launch-shell, as Omarchy starts it since 4.0.4: a shell that crashes is started again, as on your desktop, where a box was left with no bar (#151). - A command run outside any repo uses your session's box, said once, when it has exactly one,
omabox downincluded; agents no longer need-b NAMEon every call from a scratch directory, and "no box" names the session's box first (#136). up --env,run --passand--env-filerefuse the variables the session sets itself (PATH,HOME,XDG_RUNTIME_DIR, theXDG_*_HOMEdirs, the display variables,LD_PRELOAD...), which only broke the box 30 s later ("Hyprland not up after 30s"). A plugin's manifest id must be letters, digits,.,_and-, and--allowports 1-65535, kept sorted (--allow 8082,8081matches a box up with8081,8082) (#106).keys -tand--passrefuse control characters other than newline and tab (exit 2, nothing typed): a backspace or escape in the text was pressed as that key, and a password with a trailing\rsubmitted the form. A--passvalue's one trailing\r(a Windows line ending) is dropped (#104).omabox hostshortens only long arguments in the line it prints before it runs a command (env PATH=$PATHprinted ~900 characters ahead of what mattered); the record stays (#150).- A system aquamarine patched with the fix for nested Wayland outputs is used as fixed. omabox told the fix (hyprwm/aquamarine#415) by the version, so a package that patched it into 0.15.0 would still have refused headless NVIDIA boxes and turned confirm-close off. It now looks for what the fix added to the library;
omabox --versionsays "patched with the fix" for such a one.omabox setup --aquamarinestill builds with such a one, for omabox's own fixes for interactive boxes, which no system aquamarine has (held keys, the pointer and cursor in monitor windows); it builds nothing only when boxes already use this omabox's build, andomabox setupsays what yours lacks (#48, #186). - The bar widget's list holds still while the pointer is over it: a box that goes stays in its row, greyed and marked gone, and a new one is counted in the header until the pointer leaves, so a click never lands on a box that slid under it (#117). A list taller than the screen scrolls, the New button and the keys staying in view, and stays where the wheel left it (#121, #168). Every row has its buttons in the same places, so a click from habit on an interactive box's row no longer pastes your clipboard into it, and a double-click on Down no longer shuts a box down (nor
d d,n n) (#120). - The agent skill is a third of its size (SKILL.md 29 KB → 12 KB, ~4k tokens a load): what every task needs stays, every safety rule included; the rest is in
reference.md, named by section (#143). - The agent skill says what agents worked out by trial (waits sent to
/dev/null, screens that never stop moving, compound commands refused in worktree subagents, the plugin registry's reloads, Lua state lost on a reload) (#138), thatup --newstarts the box and takesup's options on that call (#148), and that Omarchy's lock screen runs in a box, with a recipe for unlocking it with a test password (a real one cannot work there). - The test suite checks the box safety rules on every kind of box it starts, not one, covers fourteen flags no check used, and no longer passes checks that could not fail or fails ones that ran late under load (#91, #110, #111, #116).
- The agent skill no longer says a full-size screen shot is read 1:1. That held for Opus and Sonnet; Haiku 4.5 reads points in the smaller image the model API shows it (0.76x of a 1920x1080 shot), so its clicks landed hundreds of pixels off, and other providers' models scale images with limits of their own. To click off a whole screen or a big window the skill now says
shot --fit 1456(16:9 on Claude) andclick --init, which worked for every model measured (#188). It also namesomabox gpufor a box's rendering cost, which agents had been summing by hand (#190).
Fixed
- An interactive box's window resized just after a config reload is followed. The box's bar and wallpaper kept the old size when the resize came in the quarter second after a reload (#174).
- A link inside your current theme no longer brings the file it names into a box. omabox copied your theme into each box HOME following its links, and
omarchy-theme-setkeeps the links of a theme you made: a link toapi-keys.envput your keys in every box (and in its saves). Links in the theme now stay links, as in the rest of the box HOME. If a theme of yours has links to files outside it, update (#97). - Nothing inside
~/.config/omarchygoes into a box butplugins/andthemes/, nor a link there or in a secret store to a file elsewhere:--ro-bindmounted a file or folder inside it (api-keys.env,hooks/), refusing only the folder itself. If you or an agent mount anything from~/.config/omarchy, update. The new--seedgets the same refusal, never writes through a link already in its DEST (an earlier seed's, or a save's: it overwrote the host file the link named), and takes a relative SRC from inside ai-jail (#159). - A box started without pasta gets none of its caller's open files. A nested box, or one started from a process that cannot gain privileges, inherited every file descriptor omabox's caller had open (a harness pipe, a lock, a log), readable or writable from inside it (#112).
- omabox's input tools tell a box from your desktop by what only a box has. The keyboard, pointer, still and events tools refused outside a box by checking that
/opt/omabox/shareexists, so on a machine with that folder they would have driven your real desktop. They also give up after 10 s on a compositor that stopped answering, wherekeysandclickwaited for ever (#108). - A box can no longer make
gdb --watchwrite to your files: it appended its header to whatever the box'sgdb.loglinked to; the header is now written from inside the box, as the rest of the log is, andrun -d's log is opened in the box too.gdbruns in the box's network namespace, and prints a process name the box set with escapes or newlines as?(#160). - Under the agent guard,
quickshell/qskillandipcare refused, with bundled options too (qs -np PATH kill --any-display):omarchy restart shellfrom an agent stopped your desktop's shell and could not start it again, leaving you with no bar (#141, #166). The guard's note and the skill say that your own!commands in Claude Code are guarded too, and send desktop commands to your own terminal (#142). The note changed, soomabox guardcalls an installed hook outdated:omabox guard on clauderenews it. wait stilland every--waitend on a box whose Hyprland stopped answering (stopped, or deadlocked by a plugin under test): "its Hyprland did not answer (hung? …)", exit 1, where they waited forever whatever--timeoutsaid (#124).- A box whose Hyprland stopped answering is said so in a few seconds, with the same words, by
windows, every--window,shot -g,wait windowandwait layer, where they printed jq's errors or "grim failed" after 10-15 s.omabox lsshows such a box ashung, andls --jsonhas"hung": true(#125).omabox hyprctlandomabox luaend there in 10 s with the same words, exit 1, where they could wait for ever or print hyprctl's "IPC didn't respond in time" (#139, #166). - A box that goes down while a command reaches into it is said in words by
keys,clickand every other command, and byrunin place of nsenter's "cannot open /proc/…" or a bash "Killed" line (#166).omabox run -- pkill -x labwcno longer ends the box (its own labwc isomabox-labwc), andrunsays when the box went down while its command ran (#128). restart-shellandupsay when the shell crashes as it starts, naming Quickshell's crash report, and exit 1;restart-shellsaid "shell restarted". Quickshell's crash dialog no longer appears in a box, where it took the keys meant for the app under test (Return on it opened a browser); the report is kept (#126).upgives up at once on a box that dies while it waits for the bar, where it retried until its timeout, holding the box's lock (#157).- A box whose
upis killed still goes down at its idle limit: anupkilled after the box started (a harness's timeout, a suite run ended with its process group) left a box that nothing would take down. The reaper now starts before the box (#137, #168). waitand every--waitno longer exit 1 "lost the box's screen" for an answer that came at a whole second of the wait, as whole-second--timeoutvalues make it do (in 0.4.8 too).wait still,wait changeand every--waitwatch every monitor of a box, in the layout's coordinates asclickandshot -gtake them: a change on another monitor (a spinner, typing into a window there, an app opening at scale 1.6) went unseen,-gor--windowthere was "not on the screen", and afteroutput drop/backthe regions named were another monitor's own pixels. An--ignoreoutside the region watched is said, andhelp scroll/help dragshow--wait(#162).drag --waitignores the cursor along the whole path, not only at its ends: a drag across an empty screen reported "settled" on its own arrow (#102).- Omarchy's plugin registry no longer reloads a mounted plugin in a box on every save in your checkout (about four times a save), so a shot or
wait stillnever catches it half-reloaded (#129). - A bar widget kept in another mounted plugin's layout is
hosted, its host named inplugin_status, whereupandrestart-shellwarned it was disabled every time (#127). - A box's session bus is at
$XDG_RUNTIME_DIR/bus, and its runtime dir is 0700, as in a session: helpers that check their bus refused the old one (a socket in/tmp, a 0755 dir) (#153). - A jailed agent gets
omabox portsandomabox config KEY: the ai-jail broker refused both (config KEY, a read, as a change). The host side ofportsis a state only, with no process of yours named, and a port a box outside the jail serves on reads as taken (host), without naming that box. A caller outside any jail that reaches the broker is told why (#93, #114, #168). - Three edges agents tripped on:
log --grep -i REtook-ias the expression (both orders work now);luareturning a dispatcher printedHL.Dispatcher, exit 0, and nothing ran (it now says on stderr that it was returned, not run, and how to run it);run --env K=Von a box that is up was dropped (#130). omabox windowskeeps its columns for a window with no class, and shows a quoted title once ("hi", not\\"hi\\") (#105).downno longer fails without a word, leaving the dead box's dir and HOME, when the box's reaper exits at the same moment (#115).- An
omabox downthat comes while anupof the same box is starting always wins: two narrow gaps let theupstart the box anyway (#168). - The runtime dir no longer keeps a lock and a marker for every box name ever used (4443 lock files two days after a boot, for one box up): they go with the box, a
down's marker after ten minutes, an idle box's note after a day (#158, #168). - Small edges said in words:
events --mark v1.0no longer removes the markv1x0;click,pointeranddragpast the screen name the point and the screen;keys üsuggests-t;shoton an interactive box gives grim's reason;up 'bad name!'says the name as written (#107). peekgives up after 10 s on a box that never draws ("the box sent no frame in 10 s"), where it left a peek with no window;peekandwaitname a frame format they cannot read, where peek's view froze; the ai-jail relay serves at most 64 connections at once (#109).- In a box, a test's stub
hyprctlin~/.local/bincan no longer end an interactive box without asking (confirm-close);luaprints bytes that are not UTF-8 as\u00XX, where they came out as U+FFFD; the box'ssystemd-cat,systemd-runanduwsm-apptake--level-prefix VALUE,--shelland a desktop file's path with an action as the real ones do; the guard's hook no longer adds its folder to PATH again at each session start (#113). - The guard's Codex check runs the system's Python, not a mise shim first on PATH that could exit instead;
install.shlistspython(#152). - The bar widget no longer logs
TypeErrors while a bar rebuilds (abar.layoutedit with the widget inside another plugin): it falls back to the theme's colours while its bar is gone (#155). - git works in a box started from a git worktree. The box mounted the worktree but not its git dir, inside the main checkout's
.git, sogit status,git describeand an installer that runs git there failed with "not a git repository". That.gitis now mounted too, read-only at its own path (not the rest of the main checkout): git reads work, writes (a commit, a tag) fail. The same for a submodule (#183). - A GPU moved to the nvidia driver while the machine runs (from vfio-pci, after a VM) gets both its device nodes. omabox asked NVIDIA's helper for the GPU's node only, so
/dev/nvidiactlstayed missing, every headless box on that GPU was refused, and the error suggested a command that could not make it. A GPU on nvidia from boot is not affected (its udev rule makes both). Each missing node is now made, and the error names the right command for each (nvidia-modprobe -c 255for/dev/nvidiactl). restart-shellno longer says the shell exited when it is running. When the shell had just died (a plugin edit crashing it, a kill), Omarchy's launcher started it again a second later next to the new one, which exited with "An instance of this configuration is already running":restart-shellreported a failed start (exit 1), and every restart after failed the same way.restart-shellnow stops every running copy of the shell and its launcher before starting one. If something else starts the shell at the same moment, it reports that shell as the running one (exit 0), and a crash of an old copy it stopped is not taken for the new shell's (#192).
0.4.82026-10-03
A security fix for boxes started from a save, and a bar widget that no longer freezes on a command that hangs.
Fixed
up --fromno longer writes through links in a saved HOME. A box can put links in its HOME, and a save keeps them; starting a box from that save then made omabox, on your machine, write the box's settings wherever those links pointed, onto your own files. omabox now removes such links before it seeds the box. If you start boxes from saves of boxes that ran code you do not trust, update.- The bar widget stops an
omabox ls --jsonthat does not answer within 15 s, with what it started, and says so; one that hung used to freeze the widget's list until it was killed by hand. - The bar widget reads its own settings. Its
commandandrefreshIntervalSecin shell.json were ignored since 0.1.0 (the CLI's settings hid them);listTimeoutSecsets the new limit.
0.4.72026-10-03
Fixes from a review of the whole tool, first among them ls --json reading a file the box can replace, and omabox ports, which says which box holds a port on your machine.
Added
omabox portslists every box's TCP servers and what holds each port on your127.0.0.1: that box, one of several boxes serving on it, one of your own processes, or nothing yet (--jsontoo;omabox help portslists the states) (#88).- SECURITY.md: each box rule, where it is enforced and the test that proves it, and how to report a way around one privately (#83).
Fixed
ls --jsonreads only plain files from a box. A box could make its theme name a pipe, which hungls --jsonand the bar widget, or a link to one of your files, whose first line then showed as the box's theme. The same check now covers every file omabox reads from a box's HOME (#95).- Mounting omabox's own saves and box HOMEs is refused, with the token dirs of gh, gcloud, azure, 1Password's
opand git's credential files, as~/.sshalready was (#98). - Six rare states no longer end omabox without a word: a peek window closing during
down, a shell log the host cannot read inrestart-shell, a failed bar capture whileupwaits, a box dying at two points ofup, andrun -don a box that is gone (#101). - A box's idle limit holds when a
downfails. The reaper that takes idle and orphaned boxes down stopped when adowntimed out under load, leaving the box running; it tries again now. A throwaway's owner is checked by its start time too, so a reused pid does not keep its box (#99). - A failed
upleaves nothing behind, andup --fromreads its save once: a save removed whileupwaited could have made it copy your home into the box (#96). portsno longer exits silently when a box goes down while it reads it (#92).portsnames a box whose server listens on::1only as holding its port: its pasta takes the port on your127.0.0.1and connections there are reset; it said "not forwarded" (#90).- The docs say a box server on a port your host or another box has fails to start (address in use); they said it still answered inside its box (#89).
omabox help portslists what its states mean, and leftover text fromportsis fixed (#94).drag --holdis documented as a duration (300ms,2s; a bare number is seconds), and its refusal says so; the docs said milliseconds (#103).- A failed throwaway
runkeeps its logs where its message points (#100). - A box keeps forwarding its servers when one of its ports is taken on your machine. pasta stopped forwarding every port above one it could not bind, for as long as it was taken (#88).
- A failed
uptakes its box down completely: its cleanup stopped after the first step and could leave the network helper running. lslists a box it cannot read asunknowninstead of refusing the whole list (from a sandbox, for instance) (#87).- An
upand adownof one box started together are ordered by when each was started, so thedownwins as it should under load.
0.4.62026-10-02
Fixes found on a dev-linked Omarchy and with a bar widget kept in a sidebar plugin.
Fixed
- A box started from a dev-linked Omarchy checkout runs one Omarchy.
omarchy dev linkputs the checkout'sbinfirst on your PATH, and a box started from inside that checkout had the checkout'somarchy-*commands while the rest of it was the installed Omarchy. A box's PATH now leaves an Omarchy checkout'sbinout (--omarchy DIRstill runs a checkout on purpose);omabox hostkeeps it, since there the link is your real desktop. - Binds, the bar and terminals in a box get omabox's stand-ins. Omarchy's config puts its own
binfirst for everything Hyprland starts, so thereomarchy-versionprinted nothing and the browser policy stand-in was skipped. They come first again. up --pluginputs a bar widget in the bar when you keep it in a plugin of yours. A widget you placed inside a sidebar plugin's layout was in no bar in a box (the sidebar is not there): it now goes where its manifest says, its settings kept. Mounting the sidebar too keeps it there.
0.4.52026-10-01
Fixes found by testing what had shipped untested: a box that outlived its down, wait layer on newer Omarchy, pi not loading the skill, and light dialogs under a dark theme.
Fixed
- A
downwhile its box is still starting takes it down. Adownin the first moments of anupsaid "no box" and exited 0, and the box came up behind it and ran until its idle limit. Now it waits for thatupand takes its box down, or theupstops itself ("up: cancelled: omabox down NAME came while it was starting"). wait layeron newer Omarchy shells. Omarchy's development branch keeps its menus mapped as 1x1 layers while hidden, sowait layer omarchy-menuwas satisfied with the launcher closed and--gonenever was. A layer counts only when it is drawn (bigger than 1x1), here and inup's wait for the bar.- pi loads the agent skill. The skill's description was not valid YAML to a strict parser, and pi skipped the skill without a word. Claude Code, OpenCode, Codex and Hermes read it either way.
- Dialogs follow the theme's light or dark mode. A box's settings said "no preference", so file choosers and other portal dialogs, GTK, libadwaita and Qt apps were light under a dark theme. A box sets the mode from its theme at start, as
omarchy-theme-setdoes on your desktop. restart-shellrecords an--omarchytree's commit again (+dirtyonce edited), as it does for plugins, sols --jsonsays what the box tested.omabox gpunames the aquamarine the box runs (a line under the first;aquamarinein--json).
0.4.42026-10-01
An agent inside ai-jail 2.6.2 drives boxes again, and each command has its own help.
Added
omabox help CMDandomabox CMD --helpprint one command's options and the notes about it, not the whole help (omabox help shotis about a twelfth ofomabox help). The agent skill sends agents there, and tells them to check with text (windows,wait,events,log --grep) before taking a screenshot, and to take the smallest one that shows what they need.
Fixed
- The ai-jail broker works with ai-jail 2.6.2. ai-jail 2.6.2 passes bwrap's options through a memfd (
bwrap --args) to keep--envvalues off the process list, and the broker, which reads a jail's limits from bwrap's command line, refused every command from such a jail ("cannot read the jail's policy: unknown bwrap option --args"). It now reads them from ai-jail's memfd. Older ai-jail versions work as before.
0.4.32026-10-01
Plugin and app work in a box: up --plugin and restart-shell say why a plugin is not in the bar, omabox ls --json says what a box tested (Omarchy version, theme, each plugin's commit), omarchy-version works in a box, and the agent skill maps plugin and app steps written for the real desktop to boxes, with recipes.
Added
- The agent skill knows plugin and app work: what to do in a box instead of linking a plugin into your plugins dir, editing your
shell.jsonor runningomarchy plugin addon your desktop (writes the guard does not stop: your bar would change at once), and recipes for testing a shell plugin (settings, placement, a vertical bar, data states, leftover processes, the install path), an app from the launcher, a theme switch, a demo video, and reviewing an Omarchy pull request. It also says how to report what a box showed, and to use--net isolatedfor anything that starts local servers (a connected box's server holds that port on your machine too). omabox up --pluginandrestart-shellsay why a plugin is not in the bar: Omarchy's plugin validator's message, or the shell's own (a refused manifest, a QML error), as a warning; the box still comes up.omabox ls --jsonandup --jsonhave each plugin's state (plugin_status).omabox ls --jsonsays what a box tested: the Omarchy version (omarchy_version), the box's current theme (theme) and each mounted plugin's git commit,+dirtywith uncommitted changes.
Fixed
omarchy-versionworks in a box: it says the installed Omarchy's version (or, withup --omarchy, the tree's commit), where it printed nothing and exited 1.
0.4.22026-10-01
Omarchy's browser bind and its own shell restart work in a box, a box can run an Omarchy checkout (up --omarchy), keys held when an interactive box loses focus are released (with omabox's aquamarine build), setup offers the bar widget and tidies up after a checkout, and up refuses options a running box lacks.
Added
omabox setupoffers to put the bar widget in your bar (yes by default, a "no" remembered).- The widget says when it is older than the omabox installed (after an upgrade, until the shell restarts), and
omabox config --jsonnames the version. omabox up --omarchy DIRruns a box on an Omarchy checkout instead of the installed Omarchy (its Hyprland config, shell,bin/andOMARCHY_PATH), asomarchy dev linkwould, without touching your system.omabox up --jsonprints the box asomabox ls --jsonlists it.
Changed
omabox upon a box that is already up refuses options the box lacks (exit 1, naming each), where it ignored them: an agent asking for a plugin, isolation or a size no longer goes on without. A bareomabox up, or one asking for what the box has, is fine as before.
Fixed
- Omarchy's browser bind (SUPER+SHIFT+B) opens the browser in a box, and so do the other things Omarchy starts with
systemd-run --user(LocalSend from the share menu). Without--systemdnothing opened; with it, the browser closed again at once. - A key held when an interactive box loses focus no longer stays down in it (SUPER held while SUPER+1 switched your workspace made a later W in the box SUPER+W), with omabox's aquamarine build:
omabox setup --aquamarinebuilds it, or rebuilds an older one (omabox setupsays when). omabox setupfrom a package notices anomaboxlink left in~/.local/binby a checkout, says whether it takes over, and offers to remove it.- Your Hyprland binds are never left dead by an interactive box going down right after a config reload (the host could stay in omabox's key-passing mode with no way out).
- A box no longer follows your own
omarchy dev linkin its terminals (they took the host's checkout while the rest of the box ran the installed Omarchy). - An interactive box's window stays tiled on its workspace when another tool's rule floats every nested Hyprland window.
omarchy restart shellin a box brings the bar back. It left the box with no bar (no journald forsystemd-cat); it andomabox restart-shellnow take turns cleanly.
0.4.12026-10-01
Fixes from more testing of the package for Omarchy's repository: a clear message instead of a bare error for an account Omarchy has not set a theme for, no empty directories left by setup --remove, and a test suite that copes with an installed omabox on NVIDIA.
Fixed
omabox upfor someone Omarchy has not set a theme for yet (an account that never logged in) now says so and what to do, before making anything. It died on a barecp: cannot statand left the box's directories behind.omabox setup --removeleaves no empty directories of omabox's behind.- The tools link only what they use when built with a distribution's flags (
libmstayed linked, unused, in three of them). - The test suite says once when no box can start here (a headless box on NVIDIA without aquamarine's fix), instead of failing every box test, and finds your aquamarine build from an installed omabox in the tests that start a box inside a box or from a save.
0.4.02026-10-01
omabox is ready to be packaged: it runs read-only from /usr/lib/omabox, omabox setup does what each user needs (and --remove undoes it), and boxes run on your system's aquamarine unless a box needs the fix.
Added
omabox setupmakes what each user needs: the links (omabox, the agent skill, the bar widget), the settings dir, and the agent guard question.install.shruns it; a package's users will run it themselves.omabox setup --removeundoes it before you delete omabox: guard and broker off, widget disabled, links removed; your settings and saves stay (#49).- omabox runs from a system install, read-only at
/usr/lib/omaboxwith/usr/bin/omabox, as a package installs it (#50). Checked in a fresh Omarchy VM: built in a clean chroot, installed, a box driven, removed with nothing left behind.test/run.sh --installedchecks it on a checkout, and the suite run from an install skips by itself what only a checkout has.
Changed
- omabox runs on your system's aquamarine unless a box needs the fix (Hyprland's backend library; #47). Only headless boxes on an NVIDIA GPU and confirm-close need aquamarine PR #415 until a release ships it.
omabox setup --aquamarinebuilds it (install.shruns it, into the checkout'sbuild/prefixas before); without it,uprefuses those two and says what to run, and confirm-close from your settings stays off for the box. A private build whose soname Hyprland no longer links (after an aquamarine upgrade) is skipped for the system's instead of stoppingup.omabox --versionsays which aquamarine new boxes use,omabox ls --jsoneach box's.
Fixed
omabox shot -oto a path it cannot write says so: it reported a failed capture instead ("no frame ... ask the user" on an interactive box, "grim failed" on a headless one) (#63).- Closing an interactive box whose window could not come back now ends it: with confirm-close on, a box that could not open its new window ran on with no window at all. It now ends after 5 s.
- The bar widget's "Confirm before closing" switch says when it cannot work: on an aquamarine without the fix, it read on while no box asked. It is now off and greyed, its caption saying to run
omabox setup --aquamarine.
0.3.22026-09-30
The agent guard steps aside once omabox is gone, and Codex's agents now get its note too. omabox ls shows every box even while one goes down, and the test suite runs in about 1.5 minutes.
Fixed
- The agent guard no longer outlives omabox: deleting omabox without
omabox guard offleft every Claude Code session without a display, and nothing to turn that off with. The guard's hook now applies nothing when omabox is gone, and says so. Codex's guard gains a hook of its own (Codex asks you to trust it once,/hooks): it gives Codex's agents the guard's note, and once omabox is gone it tells them which lines of~/.codex/config.tomlto delete.install.shoffers the update (#51). omabox lsno longer stops partway through the list when a box goes down while it lists them.- Going to your own box during a test run no longer fails it:
test/run.shfailed with "omabox's workspace 9 came up" when you switched to workspace 9 for your interactive box (or an app of yours there). omabox's workspace coming up is now a note when the focus it brings is on a window that is not the suite's, and still a failure otherwise. With a special workspace inomabox config workspace, the suite now watches that one too (#56).
Changed
- The test suite takes about 1.5 minutes instead of 9:
test/run.shruns box tests side by side, as many as half your CPUs (at most 8);-j Npicks the number and-j 1runs them one at a time, as before (#60).
0.3.12026-09-30
With keys-to-box on, pointing away from the box (your bar, another monitor) gives SUPER keys back to your desktop.
Changed
- keys-to-box: the pointer decides too (#55). SUPER keys go to the box while its window has focus and the pointer is over it. Move the pointer off it (onto your bar, an empty part of the workspace, another monitor) and they are your desktop's again, keys-to-box still on; back over the box, they are the box's. The first key you press with the pointer off the box is already yours: SUPER+1 switches your workspace at once. The red border and the widget's icon follow. A running desktop picks the new rule up at the next
omabox up --interactiveoromabox keys-to-box.
0.3.02026-09-30
Agents see inside a box (omabox lua, log, events), restart an app in one step (run -d --replace), move the pointer the way a hand does (--steps) and click with modifiers held (--mod). Interactive boxes get SUPER keys that follow focus and your clipboard on demand, and --hyprland runs a Hyprland build of yours in a box. Releases now carry a source tarball and its checksum.
Added
- SUPER keys that follow focus into an interactive box:
omabox keys-to-box -b NAME on(or the keyboard button, orf, in the widget) sends SUPER keys to the box whenever its window has focus, and gives them back to your desktop when focus goes elsewhere, with no key to press. Per box, off by default, until the box goes down; SUPER+ALT+ESCAPE still passes them once, and in this mode is the way out until the box loses focus. While keys go to a box, its window's border turns the theme's red and the widget's icon lights up.lsshows the mode. A config reload of your Hyprland no longer leaves passthrough stuck on with nothing bound: the box puts it back within 2 s (#22). - Agents inside ai-jail drive boxes of their own:
omabox broker on(a systemd user socket) prints the lines to add to~/.ai-jail, andomaboxin the jail then works as outside. A jail's boxes get no more than the jail: no network when it has none, only its project, only its own boxes, gone when it exits. No change to ai-jail (#16). - Saves:
omabox save SAVEkeeps a box's HOME (what its apps set up: signed in, a PIN, a library), andup --from SAVE/run --from SAVEstart a box with it. Your Omarchy look is seeded on top as for any box. The box is paused for the copy, so a database is saved whole.omabox saveslists them (and which hold keyring secrets),saves rm SAVEdeletes one. They live in~/.local/share/omabox/saves, private to you. omabox drag: press, move, hold, release, with--window/--inlikeclickand--shotto see the drag while the button is down.pointer --windowmoves in a window's coordinates, anddown/updefault to the left button (#25).run --env-file FILEhands adev.env's variables to the command, off the command line (#30).shot --window SEL -g "X,Y WxH"crops a window in its own coordinates (#27).up --hyprland PATH(andrun --hyprland PATH) runs a Hyprland build of yours in the box instead of the installed one, to check a compositor change without installing it. A build linked against another aquamarine soname, or a file that is not an executable ELF, is refused before the box starts;lsandwindowsname the build, the box log has its version, andupwarns when yourhyprctlis another version (#44).run -d --replace -- CMDrestarts an app after a rebuild in one step: it stops whatrun -dstarted in the box with the same command (SIGKILL if it ignores SIGTERM for 5 s), waits until its windows are gone, then starts it again. Nothing else in the box is touched (#29).run -d -qdrops the "started in box" line, andrun -d --print-logprints only the log's path, on stdout, for scripts (#42).- A pointer that travels:
click --steps Nandpointer --steps N -- move X Y(ormove X Y --steps N) move there in N steps from where the pointer is, so what lies on the way is hovered and, under Omarchy's focus-follows-mouse, takes focus, as with a real mouse.clickandmovestill jump by default (#38). - Modifier clicks:
click --mod ctrl(shift, alt, super, altgr;ctrl+shift), and--modondragandpointer, hold modifiers down across the click, then let go, however omabox ends (#25). - The skill says the pointer's position is part of what a test sets up: where it starts, that
clickjumps, how to travel (#43). omabox lua EXPRevaluates Lua in the box's Hyprland and prints what it returns (tables and Hyprland's objects as JSON), wherehyprctl evalsays onlyok(#40).omabox logprints or follows (-f) a box's logs: Hyprland's by default, the shell's, the apps', the latestrun -d's and more,--grep RE,-n N, a box that died too.omabox path --logssays where each one is (#41).omabox events: every box records its Hyprland events (activewindow,urgent,openlayer, ...) from its start, timestamped.--marksays "from here" without clearing anything,--since MARK(or30s) reads from there,--grep,--json,-f, and--until REwaits for an event likeomabox waitdoes (#39).omabox cliphands your clipboard's item (text, or an image by its type) to an interactive box, once, andclip --from-boxhands the box's back: for a password or a URL while you drive a box. With no-bit takes the box whose window has focus, so a key binding of yours pastes into the box you are in; the widget has Paste your clipboard into the box and Copy the box's clipboard out on an interactive box's row (v,c). Nothing keeps watching either clipboard; a password manager's "sensitive" mark goes along. Never for agents: refused in their sessions, under the guard, in ai-jail, and for headless boxes (#23).- Release files: each GitHub release carries
omabox-X.Y.Z.tar.gz(the tag, without the demo media) andSHA256SUMS, made byrelease.sh, so a package can track omabox by them (#52).
Changed
shot -o DIR/FILEmakes DIR when it is missing, and-galso takesX,Y,W,H(#27).omabox pointer --holdis refused: it never returned, and read like "hold the button" (#25).- An unknown command is one line pointing at
omabox help, not the whole help (#36).
Fixed
-b NAMEgoes before the command too:omabox -b NAME windowsfailed with "unknown command: -b" and the whole help. It now means the same as after the command, for every command that takes-b; the others (ls,config, ...) say in one line that they take none (#36).wait window SELis satisfied when several windows match (an app with one window per vault or document): it failed with exit 2. Any match answers it and the line names them all;--focusedwhen one of them has focus.--windowonshot,click,keys,pointeranddragstill wants exactly one (#37).- An interactive box kept running after a close (confirm-close) comes back on the workspace it showed, with its windows, instead of a new, empty one (#24).
- A box's bar shows workspace numbers when yours come from a plugin left out of the box: Omarchy's go where that plugin was, or after the menu when your bar has none (#21).
- Peeking at the test suite's boxes no longer fails it: a peek you open from the bar widget (or
omabox peek) whiletest/run.shruns is noted as watched by you, and the checks it holds up (a box you watch is not reaped) are skipped, saying why. A peek the suite's own commands open, or one opened any other way, still fails it, and the message now names a peek of yours as a possible cause (#45). - A box starts on an NVIDIA GPU just switched to its driver (from
vfio-pci, say): its/dev/nvidiaNdid not exist yet andupstopped. omabox now creates it with NVIDIA'snvidia-modprobe -c N(no root needed), and says to run that when it cannot.
0.2.12026-09-29
OMABOX=NAME works under omabox run, --window finds apps by name, and a Qt app's logging reaches its run -d log.
Changed
--window nautilusfindsorg.gnome.Nautilus: a bare word also matches the last part of a reverse-DNS class, whole (nautdoes not) (#20).
Fixed
OMABOX=NAMEworks in commandsomabox runstarted: they got the default box instead (#19).- A Qt app's warnings and errors reach its
run -dlog: Qt logged to the journal, which a box has none of, so the log stayed empty (#26).
0.2.02026-09-29
Agents drive apps by their windows and wait for the screen instead of sleeping; every box gets a network of its own, and each agent session its own box.
Much of this release is Tyler South's (@btsouth): the network of its own, the box per agent session, hidden interactive boxes that can still be shot, and the guard keeping links off your desktop. Thank you, Tyler (#2, #7, #8, #9, #10, #11, #12).
Added
- Windows as targets:
omabox windowslists the box's windows (where, on screen or covered);shot --window SELcaptures one window's own pixels, covered or on another workspace too;click --window SEL X Ytakes window coordinates and focuses the window first when needed;keys --window SELfocuses it, then types. A selector never guesses: none or several is exit 2. shot --fit Nscales a shot down;click --in SHOT X Yandpointer --intake the pixels of a cropped or scaled shot, so nobody does the arithmetic.omabox waitinstead ofsleep: until the screen holds still (still) or changes (change), a window or a shell layer is there or gone, or a command in the box succeeds.keys,clickandrun -dtake--wait: they return once what they caused has settled, and say so when nothing changed. Exit 0, 124 at the deadline, 1 when it cannot be seen (never 0). A blinking caret and the cursor are not changes. Costs nothing while the screen is idle (tools/still).omabox keys --pass VARtypes one of your variables (a password) without putting it on a command line, where the process list would show it.- The peek window shows what the agent does for a few seconds: a ring that follows its pointer and clicks, and captions of the keys it types (secrets as
*). Drawn over the view only, never into the box's screen or its screenshots. - Each agent session gets its own box. In Claude Code, Codex, or an agent started with
omabox guard exec, the default box name ends with the session's id (myrepo-5cc72cdc), so two agents in one repo no longer share a box or take each other's down. A session's box goes down when its agent exits,--idle 0or not (unless it is in use then; arun -djob does not count), instead of waiting out the 2 hour idle limit. A session resumed in a new process (claude --continue) takes over its box if it is still up.-b NAMEandOMABOX=NAMEwork as before;OMABOX_SESSION=(empty) turns this off. Thanks to @btsouth (#2, #11).
Changed
shot --activeisshot --window active: the window's own pixels, not a crop of the screen. With no focused window it exits 2, as a selector that matches nothing.- install.sh checks that grim can capture a window (
-T, grim 1.5). shotis about twice as fast (PNG compression level 1; files ~20% larger).- The agent skill has rules for driving an app (look, act once, look again; never resend input not seen to land; set state directly) and a symptom → next step table; the details that are not about safety moved to
skill/reference.md. - Every box has a network of its own (pasta). A default box (
--net connected;--net hoststill works) reaches the internet, your LAN and your host's servers, and you reach its servers. Across the box boundary use127.0.0.1and a server that listens on IPv4 (127.0.0.1,0.0.0.0or::): from a box,localhostis reset when the server listens on IPv4 only, and from one box to another it never works. A box's ports appear on your host's127.0.0.1only (never your LAN address), usually within a second of its server listening; a TCP port there also takes the UDP port of the same number. A connected box started inside another box has no network. Thanks to @btsouth (#8). - Every box needs
passt(./install.shinstalls it) and, unless it is--net isolated,/dev/net/tun;omabox upsays so at once. Started from a process with no_new_privs (some agent sandboxes, a systemd unit withNoNewPrivileges=), a headless box has no network, only a loopback of its own, andupsays so; a--net isolatedone is refused there. A box that is already up can still be used from such a process. - Boxes that were up before you updated still share your network, and can still catch host X11 apps, until
omabox down(omabox lsshows them ashost). - Take your boxes down before going back to an older omabox: it lists a box started by this one as dead (unless it is
--net isolated), and itsdowncan leave that box running.
Fixed
- An interactive box now starts on a machine with two GPUs whatever GPU the desktop renders on. It failed with "bwrap did not start" when the desktop's GPU was not the first render node, or when
OMABOX_RENDER_NODEnamed another GPU (which now applies to headless boxes only). A box that dies while starting says so, with Hyprland's last words, instead of "bwrap did not start". omabox uprun from another user namespace (some agent sandboxes,unshare -Ur) no longer takes a box that is up for a dead one, clearing its dir and leaving it running out of reach. It stops and says it cannot tell.omabox upno longer exits silently when git has no globaluser.email, as on a fresh machine, thanks to @btsouth (#7).- The agent guard now refuses to open links and files on your desktop.
xdg-open URLorgh pr view --webfrom a guarded agent handed the URL to a browser already running there, which opened a tab and could take focus.BROWSERandGH_BROWSERpoint at a stand-in that fails with a note, and Claude Code andguard execput it first on PATH asxdg-open. Under Codex onlyghand what reads$BROWSERare covered: a plainxdg-openthere still uses the desktop's URL handler. After updating,install.shoffers to update the guard for the agents that have it (omabox guard ondoes it too). Thanks to @btsouth (#10). omabox shot,wait,clickandkeyswork on an interactive box while its window is hidden on its workspace. The host now keeps drawing the window (atmisc.render_unfocused_fps), and the error for a box started by an older version no longer suggests showing the window, which led an agent to switch the user's workspace before every screenshot. After you closed a box's window and kept the box running (confirm-close), its new window is only drawn while on screen:clickandkeysstill reach it, butshotandwaitget no frame while it is hidden. Thanks to @btsouth (#9).- A headless box no longer captures X11 apps started on the host. Its parent compositor's Xwayland claimed the host's abstract
:0X11 socket (or the next free one), and a host app (Steam) then opened in the box. An X server run inside a box (Xvfb) could do the same. Thanks to @btsouth (#8). - A check in the test suite (
t_throwaway, "no box left") counted other boxes than its own, thanks to @btsouth (#12).
0.1.22026-09-26
Apps installed inside a box start from the launcher, and pull requests get a check.
Fixed
- Apps installed per user inside a box (a
DBusActivatabledesktop entry and its D-Bus service in~/.local/share) now start from the launcher, as on the host. Boxes setXDG_DATA_HOME,XDG_CONFIG_HOME,XDG_CACHE_HOMEandXDG_STATE_HOMElike an Omarchy session (#4). - A flaky check in the test suite (
t_widget, "the viewer is started"), thanks to @btsouth (#3).
Changed
- Pull requests run shellcheck in CI (#6). The suite still needs a Hyprland session, so it stays a local step (CONTRIBUTING.md).
0.1.12026-09-25
NVIDIA GPUs, thanks to @btsouth (#1).
Fixed
- Headless boxes now start and resize on NVIDIA GPUs with a render node, without exposing the host display or DRM card. A custom bar without a tray no longer holds startup at the tray check.
- On NVIDIA, startup checks for the screen resize helper (
wlr-randr) before creating a box.
Changed
install.shinstalls one more package,wlr-randr(NVIDIA boxes size their screen with it), so the next update may ask for sudo once. AMD and Intel boxes keep working without it.
0.1.02026-09-25
The first release.
Added
- Boxes:
omabox upstarts a contained, invisible Hyprland + Omarchy desktop (Omarchy's Hyprland config and shell, your theme and bar) on a private screen and a private D-Bus session bus, in 3-4 s.run,shot,keys,click,pointer,hyprctl,restart-shell,mode,gpu,env,path,downandlsdrive it. - Tests that touch the desktop:
omabox run -- ctest ...with no box up runs them in a throwaway box, the repo as a discarded overlay.--pass VARhands the command one of your variables without putting it on a command line. - Box options:
--size WxH[@HZ]|host,--plugin,--ro-bind DIR[:DEST],--net isolated --allow PORTS(no internet or LAN, only the listed host ports),--env,--idle,--stock-bar,--systemd(a real systemd user manager),--xwayland,--no-shell. - Seeing a box:
omabox peek(a live, view-only window of a headless box) andomabox up --interactive(a box as a window you use; SUPER+ALT+ESCAPE sends SUPER keys to it). - Settings:
omabox configfor where windows open (workspace),confirm-closeand the widget'sbar-icon. - Bar widget (
chaves.omabox): the boxes on this machine, with Peek, Screenshot and Down, a New interactive box button and a Settings face. - Agent skill for Claude Code, Codex, OpenCode, pi and Hermes, so agents do GUI work in a box.
- Agent guard (opt-in):
omabox guard ongives agents' shell commands a display that does not exist, so a window opened by mistake fails instead of reaching your desktop;omabox host -- CMDfor what you ask for on the real one. install.shfor a fresh Omarchy, with--check;test/run.sh, the regression suite.
Give every agent a desktop of its own.
git clone https://github.com/diogochaves/omabox && cd omabox && ./install.shToday on Omarchy 4 · Hyprland 0.56+ · AMD, Intel or NVIDIA · MIT