Docs

Why Based instead of Omarchy on Arch

Based is Omarchy's desktop on Debian 13 or Ubuntu 26.04 LTS. The themes, the menu, the bar and the workflows are Omarchy's own, carried in a soft fork that tracks upstream. What changes is everything underneath: a base with a security team, updates that go through apt instead of a pile of migration scripts, config files that keep your edits, and editions built for teams as well as for one person at a keyboard.

Omarchy on Arch still wins on a few things. The last section says which, and anything below that isn't shipped yet is marked planned or in progress.

At a glance

A base with a security team

Poweruser runs on Debian 13 and Workstation on Ubuntu 26.04 LTS. Both have a security team that backports fixes to the versions you already run, so a security update changes the bug and nothing else. based-update.timer installs those fixes by itself, a few minutes after boot and daily after that, and leaves everything else for you to click. Arch can't split it that way. It's rolling, it doesn't support partial upgrades, and a fix arrives as whatever the new upstream version is.

Stability covers the native base: the kernel, Mesa, the compositor, GTK and GNOME. Your apps don't wait for it.

Flatpak apps update in the daily run too. Developer tools has the mise side.

One update path, and no migration history

Every Based machine updates through apt. The update icon, Update then Based in the menu, and based-update all run the same thing: apt-get full-upgrade from your base and Based's repo, then the converge in every logged-in session, then your Flatpak apps and mise tools, then cleanup and the firmware and restart offers. Updating walks through it.

Omarchy ships 106 migrations, numbered shell scripts that run once per home after an update. Seven of them fix an earlier migration or the migration machinery: one re-runs a migration a pipefail bug skipped, one deletes a broken line an earlier one wrote into foot.ini, two repair theme links earlier ones got wrong. Based runs none of the 106. The fork marks them done, because on Debian each one is handled by a package, applies only to Arch, or repairs a state Based never had.

Most of what those scripts do by hand, dpkg already does:

The converge isn't a migration. It has no history and no order: it compares each file with what Based last wrote and brings it to today's default, so running it twice changes nothing, and it exits at once when no package changed.

Based isn't at zero yet. It has five migrations of its own, each rewriting a state an older Based release shipped, and based-update runs six cleanups of the same kind, such as taking accounts out of input. A new one is allowed only for a destructive change that can't be made idempotent, and every one is listed in Migrations. Retiring the migration runners is planned.

Your edits are never lost

Where an app reads a system-wide file underneath yours, Based's defaults go there and your home file stays yours:

• git reads /etc/gitconfig, which includes Based's defaults, before ~/.gitconfig. Based never touches ~/.gitconfig.
• tmux reads /etc/tmux.conf, which loads Based's defaults and then ~/.config/tmux/conf.d/*.conf. Your home has no tmux.conf of Based's.
• GNOME's settings come from a system gschema override, so whatever you set in Settings wins.

Moving the GTK settings and the default-apps list out of your home the same way is planned.

Where an app's own file replaces the system one, your home gets a stub: one line that loads Based's defaults from /usr/share, with your lines after it, so yours win.

based-converge.service keeps those files current. It runs at every login, and based-update starts it in every logged-in session after an update. For each file it follows the rule dpkg follows in /etc:

"Unchanged" means the file's sha256 matches what Based last wrote, recorded in ~/.local/state/based/config/. The comparison is normalized: spacing, blank lines and whole-line comments don't count as edits, so you can annotate a file and still get updates. A comment after a setting does count, since # also starts a colour. A home older than the record is checked against every version Based ever shipped of that file. The first time a stub meets a file that isn't Based's, your file moves aside to .bak once and the stub goes in. After that it's the table above. A symlink is never followed, so a dotfiles checkout stays yours, and a bare * in ~/.config/based/unmanaged opts your whole home out.

Omarchy does this for .bashrc and the Hyprland config, which are already small files that load package defaults. Most other app configs it copies into your home whole, once. After that a new default reaches you only through a migration script that edits your file: shell.json has had five, Neovim four, kitty and foot four each, tmux.conf three. Its "Make Shift+Enter distinguishable" migration is a 172-line script that patches one key binding into four terminal configs. With a stub it would have been one changed line in a package file.

Outside your home, Omarchy's omarchy-settings package keeps its own copies of files other Arch packages own, nsswitch.conf, security/faillock.conf and plymouthd.conf among them, and copies them over the real ones with cp -f on every upgrade. Its own docs say your edits to them get clobbered. Its reset, omarchy-reinstall-configs, copies /etc/skel over your whole home.

Not finished on Based: about 90 files it puts under /etc still come from the edition's installer rather than a package, so dpkg's rule doesn't cover them yet. Moving them into packages is planned.

Any install route gives the same result

Omarchy's setup lives in scripts. Its installer is 77 shell scripts in its install/ folder, and the menu's omarchy-install-* commands do the rest. Install the same app with pacman -S and that setup never happens.

Based's rule is that setup is data plus one engine. A config package carries the defaults and the list of home files, and the converge applies them for whatever is installed, however it got there. Agents are agentctl's job (below). On Poweruser and Workstation none of Omarchy's install/ tree runs: packages, the edition and based-hw-probe do its jobs, or they aren't needed on Debian.

By the same rule, a setup step stays a step only where a person has to give something: a sign-in, a fingerprint or a security key, or a choice such as turning the SSH server on or adding a web app. It records that input and nothing more, and doing the same by hand gives the same result.

Not finished: the last audit found 15 cases where a plain apt install still ends up different from installing through the menu. The common ones are an agent installed outside the menu, which gets its servers and skills at the next login instead of at once; VS Code and Cursor, which get Based's settings only from the menu; and any app whose config is a stub, which gets it at the next login. The fix is planned as machinery rather than per-app scripts: a trigger that runs the converge right after apt, and tables the converge reads.

Only the distro's archive and Based's signed repo

No AUR and no PPAs. An image's apt sources are Debian's or Ubuntu's archive and Based's repo, https://apt.basedlinux.com/deb/based, in one file, /etc/apt/sources.list.d/based.sources, whose Signed-By names Based's key. Anything Based needs beyond the distro, patched or not, is built into that repo instead of adding a source.

The repo's suites are the base names, d13 and u26. Dev mode is one switch, Update then Channel, that adds the next release's snapshot suite (d13-dev or u26-dev) beside it, and apt takes whichever version is newer. There are no apt pins: version order does the work.

Two exceptions today. Poweruser and Workstation keep Docker's own archive, so Docker's updates come from Docker. And two Install menu rows, VirtualBox and Charles, still add their vendor's source when you pick them. Moving those into Based's repo is in progress.

That leaves out the AUR on purpose. An AUR package is a build script anyone can upload, and installing it runs that script on your machine. A few of Omarchy's install rows use it.

Editions for everyday users and teams

Omarchy is one Hyprland desktop for one person. Based builds editions from one catalogue. Based Poweruser is SwayFX tiling with Omarchy's workflows and Based's keybindings, on Debian 13. Based Workstation is an everyday windowed desktop, Zorin's GNOME on Ubuntu 26.04 LTS, with the same Omarchy menu, themes and developer stack; Super+Space opens the menu. The two are the same system apart from the desktop. Two Retro editions and two pure ones, stock Omarchy on Debian and plain sway, make six. Editions has them all.

The first login runs onboarding. Its Work or School Account row asks for your organisation's address, signs you in once in your browser through the organisation's Keycloak, and lists each service it publishes with a switch. What you approve is set up for you: Nextcloud files, calendar and contacts, mail in Thunderbird, Matrix chat, the NetBird VPN, and the organisation's AI servers for your agents. Device management through Fleet is offered too, and it enrolls only with your yes, because Fleet can run scripts as root. First boot has the pages.

Every account on the machine gets the same setup, accounts made after the install included: /etc/skel with its record, its own onboarding at first login, the converge at every login, and the device groups (video, audio and the rest) through based-user-groups.path.

Consistent theming

A Based theme is an Omarchy theme: same folder, same colors.toml, and themes published for Omarchy work unchanged. desktop-sync carries each switch past the compositor. On Poweruser one omarchy theme set repaints the bar and the lock screen, GTK and Qt apps, GNOME's accent, light or dark setting and icons, Chromium and Zen, and the boot splash, the GRUB menu and the GDM login screen, with no reboot. On Workstation the theme drives the terminal, light or dark, the wallpaper and the boot screens, and the Zorin look stays Zorin's. Themes has the details.

AI agents, managed in one place

agentctl is the one program that writes every agent's MCP servers and skills: Claude Code, Codex, OpenCode and the rest. An app's MCP bridge ships as its own package, which drops a fragment in /usr/share/agentctl/servers.d. Eight do today: LibreOffice, Thunderbird, Chromium, Blender, Inkscape, GIMP, FreeCAD and Audacity. Install the app from the menu and its server shows up in every agent, and Setup then AI Tools switches each server per agent. Your organisation's servers arrive through onboarding.

Omarchy's install rows write each agent's config and link its skills one agent at a time, and its migrations relink them when a path moves.

Hardware reach

Based runs on amd64 PCs and on Apple Silicon Macs: install Debian through Asahi, then Based on top with make install or the prebuilt install.sh. The install asks based-hw-probe which hardware packages the machine needs and installs them with the edition, such as the Mac's speaker stack (speakersafetyd, asahi-audio), and based-update adds them on a machine kept current by updates alone. On a Mac running macOS, the fork's make install brings Omarchy's menu, themes and shortcuts, and keeps macOS's light or dark appearance and desktop picture in step with the theme. Arch itself supports only x86_64.

Security defaults

About even with Omarchy today. The difference is how security config is kept.

• No account is put in input, whose members can read every keystroke, and based-update takes existing accounts out unless ydotool or xpadneo-dkms, which need it, is installed. Omarchy dropped the same grant recently.
• docker is root without a password, so only the account the installer creates is in it. A later account needs an admin's gpasswd -a. Omarchy now goes further and takes the user out of docker.
• A package-owned file in /etc follows dpkg's keep-if-edited rule. Omarchy's settings package copies its own faillock.conf and nsswitch.conf over yours on every upgrade.

Arch problems Debian doesn't have

17 of Omarchy's migrations exist only because of Arch.

Initramfs. On Arch what goes into the image is a list in /etc/mkinitcpio.conf, so a change meant a migration that edits the list and rebuilds: keep non-Latin keyboard layouts out so the disk-unlock prompt stays typeable, rename the T2 module, rebuild without kms on NVIDIA. On Debian each package ships its own initramfs-tools hook, and a dpkg trigger rebuilds the image.

Boot. Omarchy boots through Limine, and migrations rebuild the Limine image, add kernel options to its command line and make the Omarchy kernel its first entry. Based boots GRUB with the distro's kernel, Asahi's on a Mac, and a kernel option is a drop-in in /etc/default/grub.d that update-grub picks up.

Package churn. Swapping Brave's AUR beta for its stable build and dropping an unsigned-package override from pacman.conf each took a migration. So did swapping quickshell for quickshell-git and back, and mise for mise-bin. On Based those are just newer versions in Based's repo.

Networking. One migration retires systemd-networkd for NetworkManager. Debian desktops start on NetworkManager.

What Omarchy on Arch still does better

• Newer native packages. Arch ships new kernels, Mesa, Hyprland and GNOME within days. On Debian those wait for backports or the next release, and Based curates only the few it can't wait on.
• The AUR's breadth. Thousands of community packages, where Based has its repo, Flathub and mise, and some things just aren't there.
• It's the upstream. Based carries Omarchy as a soft fork, 210 patches on top of v4.0.4, so a new Omarchy release reaches Based only after a rebase, and every rebase costs work.
• Hyprland. It's Omarchy's home, with the animations and the Hyprland-only tools. Based's work is on sway, and Hyprland is parked. The Pure Omarchy edition runs stock Omarchy on Hyprland, without Based's layer.
• Snapshots and rollback. Omarchy takes a Snapper snapshot on every update, lists snapshots in Limine's boot menu, and restores one with omarchy-snapshot restore. A guided Based install already lays out btrfs, takes a Snapper snapshot before every apt run and lists snapshots in a GRUB submenu, but through Based's own small copy of grub-btrfs, not yet proven end to end. The packaged grub-btrfs is in progress. A snapshot row in the menu and a snapshot inside the update are planned.
• Factory reset. Omarchy rolls the disk back to a snapshot taken at install, and so does Based on a btrfs install: Setup > Reset Computer starts over, and Reset System, Keep Files puts the system back and leaves your files alone. Based keeps your account through both, since only its installer creates one.
• Disk encryption. Omarchy installs with full-disk encryption by default. Based's installer offers no encryption yet: planned.
• Fewer moving parts. Omarchy is one desktop, polished. Based spreads over more editions, and its converge is newer and less proven than Omarchy's migrations, which many people run every day.