Skip to content

feat(computer): Omarchy computers, a base built from Omarchy's own image with cua-driver composed on it as a thin disk - #589

Merged
earakely-scale merged 13 commits into
mainfrom
edgararakelyan/omarchy-computers
Nov 10, 2026
Merged

earakely-scale merged 13 commits into
mainfrom
edgararakelyan/omarchy-computers

Conversation

@earakely-scale

@earakely-scale earakely-scale commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Part of FD-5338 (O1). It builds on #577's thin-disk module. The branch has no issue id, so merging won't close the issue.

With this, agent-env makes Omarchy computers end to end on a Linux machine with KVM:

  • Omarchy's own stable VM image becomes our base;
  • cua-driver is composed onto it as a thin disk;
  • gate 3 probes the result at full.

The base: computers/artifacts/omarchy-4.5/

  • os = linux / omarchy / 4.5.0 / wayland, amd64, session user omarchy, disk form only (Hyprland needs a GPU, which a container doesn't get).
  • Settings: resolution (1920x1080) and timezone (UTC), both deploy phase.
  • Alias omarchy-4.5.
  • D2: [forms.disk] gains an optional source = { url, sha256 }. A Linux disk with no container form names its image or its source; an Omarchy disk names its source and no image; a Windows disk names neither. A disk that names no source is written without one, so an agent-env from before sources still reads every disk this one writes, Ubuntu's included.

D1 (the local half): omarchy_disk.base builds it once per machine:

  1. Fetch Omarchy's qcow2 into the cache, checked by sha256.
  2. Boot it as the launcher's new linux-desktop guest, with root's ssh key passed as an SMBIOS systemd credential.
  3. Run computers/disk/omarchy/recipe.sh as root over ssh.
  4. Trim, convert, pack with the key and the os-release labels, and push to the image store.

The tag is a key of the recipe, the seed reader, the source, and the base's OS and session user.

The recipe (D7, D8, D9):

  • It refuses an image whose os-release isn't the artifact's omarchy 4.5.0.
  • It installs cua-driver's Hyprland plugin (cua-hyprland-plugin 0.33.2-3), pinned by URL and sha256.
  • agentenv.lua, required last from hyprland.lua, sets up:
    • the plugin, loaded at start;
    • a US keymap;
    • the idle cursor hidden;
    • the display's mode.
  • It installs the seed unit, and has SDDM log back in after a logout (D10's logout half).
  • Omarchy's own toggles make the desktop unattended: stay awake, no animations, no screensaver or suspend, notifications silenced.
  • It turns off what a trial doesn't want:
    • crash-watch and superwhisper;
    • dictation at its source, so its Alt+Space binds aren't added;
    • five housekeeping timers;
    • the firewall (ufw, new since the first VM run below): it lets in only ssh and LocalSend, while the launcher forwards only the computer's own ports.
  • It locks the session user's password and leaves the machine id empty.

The launcher's linux-desktop guest (D3)

It boots like linux, with these differences:

  • a virtio-vga sized from AGENTENV_SETTING_RESOLUTION, which is validated before boot;
  • 4 vCPUs and 8 GB by default;
  • discard=unmap on the disk, so trimming shrinks it;
  • VM_CREDENTIALS passed as SMBIOS type 11 credentials.

It's amd64 only, and refused elsewhere.

Composition (D4, D6)

  • _composed_omarchy_disk sits beside Windows' in the composer. It runs thin_disk.compose with omarchy_disk.GUEST, keyed and reused the same way.
  • Each layer is installed by a bash provision.sh, as its [install."linux/omarchy"] says:
    • files under /opt/agentenv/drivers/<name>;
    • downloads checked by sha256;
    • a venv on the system Python;
    • run scripts.
  • Services become systemd user units in /etc/systemd/user:
    • PartOf, After and WantedBy are graphical-session.target, with Restart=always;
    • ExecStart goes through with-seed;
    • they're enabled with --global.
  • DISK_INITS["linux/omarchy"] = "systemd", and OS_FORMS["linux/omarchy"] = ("disk",).
  • A disk-only base's computer is now written over its disks (it was Windows only).
  • [install."linux/omarchy"] gets a model of its own, OmarchyInstall, which refuses apt's packages and sources as macOS' and Windows' do. Installs are looked up by platform, at put and when a stored driver is read back.
  • A scope = "session" run script runs as the session user in their home, as on the container and macOS paths.
  • The composed disk has no ssh: provision masks sshd. Only a compose logs in, and a compose always boots the base, never a composed disk.

Shared with Windows: one base build

Omarchy is thin_disk's second guest, so what both OSes did alike now lives in thin_disk:

  • thin_disk.base(guest, key, build, say, registry, stale=…) finds or builds a guest's base:

    • this machine's base, pushed to the store if the store lacks it;
    • else the store's base;
    • else built by the OS's own build and pushed.

    It also handles the lock, the new admin key, packing and the push. A base whose labels stale gives a reason against is built afresh, and the reason is logged. Windows' stale is its evaluation's expiry. windows_disk.base and omarchy_disk.base are now only their OS's build.

  • Base carries its image's labels in place of Windows' expires field. The composer reads Windows' expiry label directly. It's the same string the composed disk's key always used, so Windows bases and disks already in a store or cache are still reused.

  • thin_disk.running(…) launches a launcher container and removes it however its use ends. thin_disk.answering(…) waits for its guest's ssh. Both replace code that the compose, the Windows install and the Omarchy build each had.

  • A base is packed from a folder holding only its image and admin key. So pack no longer deletes Windows' answers folder, and Omarchy's copy of its recipe stays out of the Docker build context too. Windows' install writes GUEST.file instead of "windows".

The seed (D5)

agentenv-seed.service runs before the display manager. It reads the NoCloud seed with the Linux initramfs's own seed-env, then:

  • writes the deploy's environment to /run/agentenv/environment, readable by root and the session user only, the seed's trust files first;
  • sets the hostname;
  • sets the timezone as /etc/localtime;
  • adds host.docker.internal at QEMU's 10.0.2.2;
  • writes the display's mode for Hyprland from resolution.

A seed it can't read, or a time zone the disk doesn't have, is written as a refusal, which every service then names when it fails to start. Before that, a deploy whose timezone isn't an IANA zone is refused at once by check_computer_settings, for Ubuntu's timezone too.

boot.DISK_SIZES["linux/omarchy"] is 4 CPUs and 8 GB. Probing and the computer env provider pass the base's platform to boot.

Not in this PR

  • Apps on Omarchy. Gate 1 refuses an Omarchy computer env with apps, and says why: their installs would have to be composed onto its disk.
  • Publishing the base to GHCR and pulling it by tag (D1's release half) is O10 (FD-5347). Until then, each machine builds the base once (about 5 minutes), and the image store keeps it.
  • Put reading the base's os-release labels from the registry (D7's put half) needs the published base, so it's also O10. Until then, put marks the disk unchecked, and the recipe checks os-release at the build.
  • D10's framework half, a final ready check making the turn an infra_error, is FD-5408.
  • Window opacity. Omarchy's stock window opacity is left as is; the probe passes with it.

Tests

  • Unit tests.
    • tst/unit/env/envs/test_computer_omarchy.py (new, 18 tests) covers:
      • the compose, and its reuse;
      • a machine with no disk platform;
      • apps refused;
      • the artifact's rules, and the shipped artifact;
      • DISK_SIZES;
      • unit quoting and argv;
      • the source fetch and its sha256 check;
      • the base build;
      • a mislabelled image;
      • an install naming apt packages, refused;
      • a session-scoped run script run as the session user;
      • a driver service that runs as root, refused naming systemd;
      • a disk form naming no source, written without one;
      • a time zone checked against IANA's before boot;
      • provision masking sshd.
    • test_disk_recipe.py covers the launcher's linux-desktop guest and its refusals.
    • test_thin_disk.py adds two tests for the shared base build:
      • a base is built once, then reused, and packed from its image and key alone with the labels its build returns;
      • a base the store holds that its guest calls stale is built afresh, saying why.
    • test_computer_windows.py's base tests now go through thin_disk.base.
    • test_computer_disk.py expects a composed Linux disk form to name no source.
    • Locally:
      • tst/unit/env/envs: 956 passed, 2 failed:
        • the Windows install recipe test, which fails on main locally too;
        • test_a_builder_boots_on_a_kept_overlay…, which failed once under the full suite's load and passes alone and in 3 of 3 runs of its file.
      • tst/unit/artifact, tst/unit/config, tst/unit/drivers and the shipped bundles' test pass.
    • ruff check is clean.
  • The base computer's fixture (tst/integration/computer/conftest.py base) now pulls the published agentenv-ubuntu-24.04 image of its sources for this machine's platform, as the gateway tier's fixtures do, and builds it only when the sources have changed. Building it from source installed its desktop from Ubuntu's archive on every run, and a slow archive timed out all of base_computer_test.py. tst/util/published_image.pull_published_else_build takes the platform to pull.
  • Three more fixtures pull their published images the same way: disk_test.py's disk tools, browser_gateway_test.py's gateway and playwright_mcp_local_test.py's Playwright MCP. A slow Ubuntu archive had timed out the fast tier's disk tests while it built the disk tools. Re-resolving Chromium's and the test apps' packages on every run is FD-5432.
  • Integration test. tst/integration/computer/omarchy_test.py composes the shipped base with cua-driver and runs the probe task, whose verifier waives nothing.
    • It's gated on a new omarchy_image capability (the qcow2 in this machine's cache), which is added to the slow tier's allowed skips.
    • CI's runners don't cache the 4.2 GB image yet, so it skips there; O10 caches it.

Verified on a VM

EC2 with nested KVM, from this branch, starting from Omarchy's stock 4.5 image: runs 1 and 2 on a c8i.2xlarge, the last on a c8i.4xlarge. Docker was on overlay2, as CI's runners are; the containerd image store breaks local disk boots (FD-5416, from #577).

Run 1 (29c9aa2) got as far as the probe boot:

  • the base was built from the image, and the recipe ran;
  • the base was packed and pushed;
  • cua-driver was composed onto it, packed and pushed.

The probe's boot then failed: the computer … wasn't ready within 180 s (ReadTimeout). Booting the composed disk by hand showed:

  • the seed unit had run, and both driver units were active;
  • the driver listened on 0.0.0.0:18765 and answered 200 from inside the guest;
  • from the host, the request timed out: Omarchy's ufw denies incoming connections except ssh and LocalSend;
  • with ufw disable, the host got a 200.

The recipe now turns the firewall off (d09fcd1).

Run 2 (d09fcd1): 1 passed in 8 min 52 s (test_the_omarchy_desktop_passes_the_probe_at_full, passed (probe: 1)):

  • a fresh base was built under its new key in about 4½ minutes;
  • cua-driver was composed onto it in about 3½ minutes;
  • gate 3 probed it at full, and the probe task passed with nothing waived.

Deploy settings, checked by booting run 2's composed disk by hand:

Boot Result
timezone = America/Chicago, resolution = 1280x800 /etc/localtime is Chicago, and date says CST in the system and in the session; Hyprland's monitor is 1280×800@60 at scale 1; ufw is inactive and disabled; the driver's card answers 200 from the host
timezone = Mars/Base refused: the driver's units fail with with-seed: its time zone, Mars/Base, is not in /usr/share/zoneinfo, and /etc/localtime stays UTC

That refusal is only in the guest's journal, as D5's refusal of an unreadable seed is: the deploy just reports the computer wasn't ready within 180 s. Since 6f93085, check_computer_settings refuses a zone like that before the computer boots. An unreadable seed still shows only as the timeout.

After rebasing onto main and the shared base build (353d92f), on a fresh c8i.4xlarge with nothing cached but Omarchy's image and Windows' ISO:

  • Omarchy: 1 passed in 8 min 53 s. The base was built through thin_disk.base under the same key as run 2, since its recipe is unchanged. Then cua-driver was composed onto it, and gate 3 probed it at full.
  • Windows: windows_test.py -k "probe_at_full or notes_app", 38 min 15 s:
    • a fresh Windows 11 base installed from the ISO through thin_disk.base, with _installed on thin_disk.running;
    • both computers composed on it (cua-driver alone, and cua-driver with the notes app), then booted and probed ready;
    • test_the_windows_desktop_passes_the_probe_at_full passed.
    • The notes app's task scored before: 1, session: 0, after: 1. Of the session verifier's checks, only obliging stop failed: {"shown": true, "waited out": false, "alive": true, "listed": false}.
    • That's a race in the protocol's Windows stop, which this PR doesn't touch. On the path where the window closes when asked, stop returns once the app's processes have left the job, but alive also counts the helper holding the job, which can still be exiting.
    • Rerun alone, the notes test passed (2 min 31 s).

After Greptile's review (3ccec62), on a fresh c8i.2xlarge:

  • Omarchy: 1 passed in 8 min 37 s.
  • Arch Linux: a generated provision.sh, run as root in an Arch container with an omarchy user, ran its system script as root and its session script as omarchy, with HOME=/home/omarchy.

After the follow-up review fixes (6f93085), on a fresh c8i.2xlarge:

  • Omarchy: 1 passed, composing with sshd masked.
  • No ssh: the composed disk was booted with port 22 forwarded and root's key supplied anyway. The driver's card answered 200 from the host, and ssh got Connection closed before the key exchange: nothing in the guest listens on 22.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The PR appears safe to merge, with no new actionable issues found.

Summary

Adds Omarchy computers built from the distribution’s VM image, with cua-driver installed as a thin disk layer.

  • Linux hosts can build and compose an Omarchy 4.5 desktop.
  • Windows and Omarchy bases use the same shared build and reuse path.
  • Integration fixtures use matching published images for the host platform.

No new actionable issues were found. The three supplied, unnumbered previous findings are addressed: image-only Omarchy bases are rejected, session scripts use the session user, and Omarchy installs reject apt fields. Tests were not run during this review.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Omarchy VM image] --> B[Check SHA-256]
  B --> C[Boot and run base recipe]
  C --> D[Pack and store base]
  D --> E[Install driver on thin layer]
  E --> F[Pack composed disk]
  F --> G[Boot and read deploy settings]
  G --> H[Start graphical session and driver]
  H --> I[Run full probe]
Loading

Reviews (10) · Last reviewed commit: "test: the disk tools', gateway's and Pla..." · Reviewed by Greptile

earakely-scale and others added 9 commits November 9, 2026 18:04
…er's linux-desktop guest

A disk form may name the source its base is built from, a distribution's own VM image by URL and sha256. A computer's
forms and its disk's init are chosen by platform, a distribution's replacing its OS type's: an Omarchy computer is a disk
alone, its init systemd, and a Linux disk with no container form names its image or its source. The computers bundle
ships omarchy-4.5, Omarchy's stable 4.5.0 VM image.

The QEMU launcher boots a linux-desktop guest, a Wayland desktop on amd64: a virtio GPU at the computer's resolution
setting, 4 CPUs and 8 GiB unless sized, TRIM to its disk, and the systemd credentials VM_CREDENTIALS names over SMBIOS,
as a builder's boot passes its ssh key.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…from Omarchy's image, cua-driver as a layer

omarchy_disk builds an Omarchy base from its artifact's source: Omarchy's own image, fetched into this machine's cache
and checked by sha256, booted once by the launcher as a linux-desktop guest with root's key as a systemd credential, and
made a base by computers/disk/omarchy's recipe over ssh. The recipe refuses an image that isn't the distribution and
version its artifact declares, installs cua-driver's Hyprland plugin pinned by URL and sha256, adds agent-env's Hyprland
drop-in and the seed unit that hands each boot its deploy's environment (the Linux disk's seed-env), has SDDM log back
in after a logout, sets Omarchy's toggles for an unattended desktop, and turns off crash toasts, dictation and its keys,
and housekeeping timers. A composed disk installs the driver over ssh with a bash provisioner, its services systemd user
units of the graphical session started through with-seed. A disk's VM is sized by platform, Omarchy's at 4 CPUs and
8 GiB, and gate 1 refuses apps on Omarchy, whose disks compose a driver alone for now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… disk-only base's computer is written over its disks

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nd booted

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…own ports reach it, and its time zone a deploy setting

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… and staleness given; a launcher running for its use

thin_disk.base finds or builds a guest's base: this machine's, else the store's, else built by the OS's own
build and packed from its image and key alone, a base whose labels the OS calls stale built afresh. Base carries
its image's labels, Windows' expiry among them, in place of an expires field. thin_disk.running launches a
launcher container and removes it however its use ends, and answering waits for its guest's ssh.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale requested a review from a team as a code owner November 10, 2026 03:36
earakely-scale and others added 4 commits November 9, 2026 19:49
…tall no apt, and its session scripts run as the session user

An Omarchy disk's base is built from Omarchy's own image, so a base naming an image instead was accepted at put and
failed its compose; put refuses it. linux/omarchy installs get a model of their own, as macOS and Windows have, which
refuses apt's packages and sources rather than skip them. A session-scoped run script runs as the session user in
their home, as the container and macOS paths run it. The gate names a disk-only base's own init, systemd or
agentenv-session, where a driver's service would run as root.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…rchy computer has no ssh, and a time zone is checked before boot

DiskForm left out source when it names none, so an agent-env from before sources still reads every disk this one
writes, Ubuntu's composed computers among them. A composed Omarchy disk masks sshd: only a compose logs in, and it
boots the base. check_computer_settings refuses a timezone that isn't an IANA zone, so a deploy fails at once rather
than when the computer isn't ready after its timeout.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…u-24.04 image of its sources

The base fixture built ubuntu-24.04 from source on every run, installing its desktop from Ubuntu's archive, and a slow
archive timed out every test that uses it. It now pulls the image agent-env published from the same sources, for this
machine's platform, and builds it only when they've changed or the pull fails, as the gateway tier's fixtures do;
pull_published_else_build takes the platform to pull.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…heir published images too

disk_test's tools, browser_gateway_test's gateway and playwright_mcp_local_test's image were built from source on every
run, installing from Ubuntu's archive and PyPI, and a slow archive timed out the fast tier's disk tests. Each now pulls
the image agent-env published from the same sources for this machine's platform, and builds it only when they've
changed or the pull fails.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale merged commit d29f59d into main Nov 10, 2026
64 of 66 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/omarchy-computers branch November 10, 2026 07:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant