Based Linux: the short guide

Based is Debian or Ubuntu with the desktop already put together. You pick an edition, install it, and the first login finishes setting it up for you.

These seventeen pages are for someone who has just installed Based, or is deciding whether to. They cover what Omarchy's manual and Debian's own documentation don't. Everything else in docs/ is engineering documentation for the image builder, not for daily use.

Start here

• Why Based: why Based instead of Omarchy on Arch, and what Arch still does better.
• Editions: what each edition is, and which browser and login screen it has.
• Installing Based: the images, the graphical and text installers, putting Based onto a Debian you already run, and Apple Silicon Macs.
• First boot: what onboarding sets up, and what it leaves for later.

Using it

• Updating: what updates by itself, the update you run, and Dev mode.
• Keybindings: Poweruser's keys, Workstation's, and where Omarchy's moved.
• Themes: switching theme, how far a switch reaches, wallpapers, light and dark.
• Accounts and your organization: Online Accounts, the Work or School Account, and joining an organization.
• Setup that needs you: fingerprint, security keys, the SSH server, Docker, web apps and the firewall.
• Troubleshooting: where the logs are, running things again, snapshots, and reporting a bug.

Software

• Where software comes from: apt, Flathub and mise, and what's installed up front.
• Developer tools: languages through mise, and the AI apps in the menu.
• AI agents: the MCP servers and skills agentctl keeps every agent supplied with.
• Vendor downloads: the Install rows that fetch a vendor's own download, and why.

Your configuration

• Your config files: where your own settings go, and what an update does to your edits.

Coming from Omarchy

• Reading Omarchy's manual on Based: each chapter of the Omarchy manual, and whether it applies as-is, differs, or has something else in its place.
• Omarchy on a Mac: Based's Omarchy on macOS.

Which Based am I running

cat /etc/based-release

PRETTY_NAME names the edition and the base it sits on, such as Based Poweruser D13 (debian trixie). VERSION is the base lineage, not a product release: D13 for Debian 13, U26 for Ubuntu 26.04, U24 for Ubuntu 24.04.

The pure editions have no /etc/based-release. There /etc/os-release is Debian's own, with VARIANT="Omarchy" or VARIANT="SwayOS" added.

Where to get help

These pages are the documentation at https://basedlinux.com/docs/. Troubleshooting has what to collect for a bug report, and https://basedlinux.com/issues says where to send it.