GitHubInstall

Install

Three minutes, then your agents take it from there.

omabox installs from its git repository, into your home. It asks for sudo only to install packages it needs that you don't have yet.

git clone https://github.com/diogochaves/omabox && cd omabox && ./install.sh

Or ask your agent: "Install omabox. The guide is at omabox.app/install.md." It stops for you where sudo or a choice of yours comes up.

What you need

Your machine

  • Omarchy 4 on Arch, with Hyprland 0.56 or later
  • A GPU: AMD, Intel or NVIDIA
  • Rust: omabox 1.0 is one binary, built by ./install.sh. If there's no cargo, it installs Arch's rust; the first build fetches its crates.
  • nftables (nft), only if you set protected ports
  • For agents to reach for it on their own, one the skill is installed for: Claude Code, Codex, OpenCode, pi or Hermes

On NVIDIA

Headless boxes on NVIDIA, and the confirm-close setting, need a fix to aquamarine (Hyprland's backend library) until a release ships PR #415. install.sh builds it privately inside the clone; your system's copy isn't touched. The same build carries omabox's own fixes for boxes you drive (a held key, your pointer across a box's monitor windows), so it is built even when your system's copy has the fix.

With several GPUs, omabox config gpu (or the bar widget's Settings) picks the one headless boxes render on, and omabox gpu release takes down the boxes on one before you hand it to a VM. An interactive box renders on the GPU your desktop renders on.

Not on another distro yet

A box runs your host's own Omarchy today. Plain Hyprland boxes are coming, aimed at any distro with Hyprland 0.56 or later. What's coming →

Install and check

Install

$ git clone https://github.com/diogochaves/omabox && cd omabox
$ ./install.sh           # asks about the bar widget and the guard
$ ./install.sh --check   # then starts a box, screenshots it, takes it down

install.sh installs any missing packages, builds omabox and the aquamarine fix, then runs omabox setup.

What setup does

  • Links ~/.local/bin/omabox
  • Puts the agent skill wherever Omarchy puts its own skills (~/.agents, ~/.claude, ~/.codex, ~/.pi/agent, ~/.hermes)
  • Links the bar widget, and asks whether to put it in your bar
  • Asks whether to turn on the agent guard

Later, by hand: omarchy plugin enable chaves.omabox, omabox guard on.

From 0.x to 1.0.

omabox 1.0 is a Rust rewrite with the same commands. The move takes one pull and one build.

  1. Take your boxes down first.
    $ omabox down --all
  2. Pull and build in one go. Until install.sh has run, omabox is missing, new agent sessions start without the guard, and agents in ai-jail don't start.
    $ git pull && ./install.sh
  3. Restart agents running in ai-jail. A jail started before the upgrade keeps its old relay.
  4. Scripts on an old form are told what to write. A form 0.9 warned about is now refused, with a line naming what to write instead. The changelog lists each one.
  5. Nothing to move. Every path in your home stays where it was: the omabox link, ai-jail's maps, the broker's unit, the guard's hook.

Update and remove

Update

$ git pull && ./install.sh

Run it after a Hyprland upgrade too. omabox --version says which aquamarine boxes use. After an upgrade the bar runs the old widget until the shell restarts; its panel says so. Boxes already up keep the Hyprland config they started with: omabox reload gives one the new one. What changed in each release is in the changelog.

Remove

$ omabox down --all                         # every box
$ omabox setup --remove                     # guard and broker off, widget off, links gone
$ rm -rf ~/.config/omabox ~/.cache/omabox   # settings, and box HOMEs a crash left behind
$ rm -rf ~/.local/share/omabox              # saves, if you made any

Run setup --remove before you delete the clone: once omabox is gone there is no guard off left to run. Then delete the clone. The packages install.sh added stay; it printed them as missing: if there were any. The README has the details.

What a box can't do

Worth knowing before you hand it a task.

  • No system bus. Apps that need system services (disks, NetworkManager, bluetooth, power) open with errors or not at all: a box has none, by design.
  • No real hardware. A box's monitors are virtual (as many as you like), so real ones (their modes, HDR and VRR, a real hotplug), real input devices and suspend never run in it, and its lock screen takes no real password. With --audio it gets a speaker nobody hears, never your sound card. For the installer, system services or a reboot, a VM is the tool.
  • No wgpu apps on NVIDIA. Apps drawn with wgpu (eframe's default renderer, iced, Bevy) don't start in a box on NVIDIA: give them a GL renderer, or a box on an AMD or Intel GPU. Develop has the details.
  • Not a security boundary. A box shares your kernel, your GPU and, by default, your network. For a fence around the agent, use ai-jail with it. What a box does keep out, and the test for each rule: SECURITY.md.
  • Of the agents the skill is installed for, Claude Code and OpenCode were checked end to end; Codex, pi and Hermes find the skill.

Something didn't work on your machine? Run ./install.sh --check and tell us what happened. Another GPU, several monitors or a config nothing like ours is the test we don't have.

Questions people ask first

Do I type omabox commands myself?

You can, but you'll rarely need to. Ask your agent: "start a box with the app running so I can try it" gets you a window you drive, and the agent keeps changing the app in it while you test.

Does it work without Omarchy?

Not yet. A 1.0 box runs your host's own Omarchy: its Hyprland config, its shell and your theme. Plain Hyprland boxes are coming, aimed at any distro with Hyprland 0.56 or later (the Lua config). What's coming →

Does it run my own shell or dotfiles?

Not yet. Your own shell and your own Hyprland config in a box are coming, one shell at a time, Dux Shell first. What's coming →

Is omabox part of Omarchy?

No. omabox is an independent community project and is not made or endorsed by the Omarchy project. Report problems on omabox's GitHub, not to Omarchy.

Will 1.0 break my scripts?

Exit codes and --json fields keep their meaning within 1.x, and only grow. 1.0 itself removed the forms 0.9 warned about, each refused with a line naming what to write. The contract →

Why Rust?

One binary, built by ./install.sh. It leaves nothing half-done when you stop it, enters a box without nsenter, and keeps a box's commands off your terminal. The commands are the same.

Can two agents test at the same time?

Yes. Each Claude Code or Codex session gets its own box, named after its repo or worktree and its session. Subagents take a box each, with omabox brief.

Is it a sandbox?

No, it is not a security boundary. It keeps apps off your desktop and never gets your secrets, input devices or seat, but it shares your kernel, GPU and, unless you pass --net isolated, your network. For a fence around the agent, use ai-jail; for hostile code, a VM.

Which GPUs does it work on?

AMD, Intel and NVIDIA. On NVIDIA, headless boxes need a fix to aquamarine that install.sh builds for you; What you need has the details.

Does peeking slow the agent down?

No. Peek only copies frames out of the box.

What's comingPlain Hyprland boxes · Your own shell · Your own Hyprland desktop, in a box →