FAQ

What is ShedOS, in one paragraph?

An operating system for software developers. You boot the installer; ten minutes later you have a Hyprland desktop, a complete development toolchain (Neovim/LazyVim, VS Code, zsh, Docker and Kubernetes tools, per-user PostgreSQL, language runtimes, Claude Code), and an update system with snapshots, rollback, a testing channel, and config merges, so the machine stays good for years, not weeks.

Can I use pacman, the AUR, and my usual tools?

Yes. pacman and the standard repositories work as they always do, and shedman install <pkg> reaches the AUR through yay. ShedOS adds one signed repository for its own packages and the shedman CLI on top — it removes nothing and locks nothing down. The tools you already know still work.

I already run Arch — do I have to reinstall?

No. shedman migrate --from-arch adopts a running Arch install: it verifies and trusts the ShedOS signing key, adds the repository, installs the ShedOS stack, and switches the login manager — your packages and files stay put, and any config a ShedOS default would touch lands beside yours for review instead of overwriting. Dry-run by default; on non-btrfs roots it works too, minus the snapshot machinery (which it tells you about loudly).

Can I try it without installing?

Yes — the ISO boots a full live desktop: the real Hyprland setup, the real toolchain, even Claude Code, running from the USB stick. Kick the tires for an hour; the installer is one click on the desktop whenever you’re convinced.

Will an update break my system?

This is the question ShedOS is built around, so the answer has four layers:

1. Tested before you get it — every ShedOS package lands on a testing channel first; the stable channel only ever receives a release-candidate snapshot that survived a real soak.
2. Snapshot before every upgrade — shedman update takes a BTRFS snapshot automatically, every time.
3. One-command undo — shedman rollback returns the system to any pre-upgrade state; shedman upgrade-history shows every past upgrade with what changed and lets you roll back from a TUI.
4. Self-healing boot — if three boots in a row never reach the login screen, the machine automatically boots a safe copy of the newest snapshot — no keypress, no recovery USB — and a desktop notification explains what happened.

Those four layers together are the core of what ShedOS is.

What happens to my config edits when ShedOS updates a default?

The flagship feature. ShedOS ships configured dotfiles (Hyprland, terminal, shell, editor…) and keeps improving them — but it never overwrites a file you've touched. Updates are merged three-way: if only the shipped default changed, you get it automatically; if you edited the file too, the new default lands beside yours as a .shedosnew sidecar, a waybar pill tells you, and shedman config --review opens a per-hunk merge TUI (or VS Code with --gui). You keep your customizations and their improvements.

Can I bring my existing dotfiles?

Yes — your $HOME is yours. Drop in your dotfiles and they simply win: ShedOS treats an edited file as user-owned and routes future default changes through the review flow above. A $HOME-level git repo for dotfiles works fine; the conflict scanner skips git working trees.

What exactly ships for development?

Neovim on LazyVim and VS Code, both configured. zsh with powerlevel10k. Docker + docker-compose, kubectl, minikube, helm, lazydocker. PostgreSQL with a role and database already created for your user. mise for per-project language runtimes (Python, Node, Go, Rust, and friends). git configured with your identity from the installer. Claude Code preinstalled. A GPU-accelerated terminal (kitty), fzf, ripgrep, fd, eza, and the modern CLI staples. The first git clone of your day is the first command that isn't already done.

What’s the AI story?

Claude Code ships preinstalled — a terminal AI that reads your repo, writes code, and runs commands, there on first boot and on the live USB. It’s treated as part of the developer baseline, like git or a compiler. You bring your own account, and nothing runs until you start it.

Why Hyprland?

Because for keyboard-driven development work, a tiling Wayland compositor is simply faster — and Hyprland is the best of them. ShedOS ships it fully assembled: 90+ keybindings in a searchable dialog (Super+Alt+K), fluid 3/4-finger touchpad gestures, a workspace overview, themed lock/greeter/power surfaces, screen recording, and a dock. You get the productivity without the three-weekend rice.

I don’t like something it ships. Can I remove it?

Yes — it's your machine. shedman uninstall <pkg> removes anything, showing the dependency closure and asking first. Swap the browser, the editor, the launcher; the system doesn't fight you.

How does theming work?

shedman theme set palette <name> recolors the entire desktop live — window borders, terminal, notifications, launcher, bar, lock screen, greeter, GTK apps — no logout. Wallpaper and fonts are one command each. Palettes are plain TOML files; adding your own is trivial.

What’s the security story?

Defaults you'd have to build yourself elsewhere: sudo requires your password (no silent wheel group), AppArmor is enforcing from the first boot, LUKS2 full-disk encryption is on by default, the lock screen fails closed (a crash locks, never unlocks), and a fingerprint enrolled once (shedman fingerprint enroll) works at the greeter, the lock screen, and sudo. You can also sign the boot chain with your own keys (shedman secureboot enroll) and bind the disk to the TPM2 for passwordless unlock (shedman tpm2 enroll). Every ShedOS package is GPG-signed and pacman verifies it.

Is there telemetry?

No. Nothing phones home, ever. The installer is fully offline and doesn't geo-probe (you pick your timezone on a map). The only self-initiated network traffic is package updates from mirrors listed in plain text in /etc/pacman.d/mirrorlist.

How is it different from Omarchy / Garuda / EndeavourOS / Manjaro?

Short version: Omarchy curates a similar Hyprland desktop, but without the three-way config merge, the declarative system.toml, or a single OS-wide CLI; Garuda has automatic snapshots but is a gaming-focused KDE distribution; EndeavourOS is deliberately minimal, leaving the desktop and toolchain to you; Manjaro holds packages back for stabilization. The full, sourced breakdown is on the compare page.

What about gaming?

ShedOS is a developer workstation first. Steam and friends install normally from the repos (shedman install steam) and run fine on the same Mesa/NVIDIA stack — but nothing gaming-specific is preinstalled or tuned. If gaming is the primary use, Garuda or CachyOS optimize for that out of the box.

What hardware do I need?

6 GB RAM and 20 GB disk minimum (installer-enforced), UEFI or legacy BIOS, and WiFi works on first boot on virtually all laptops — the firmware for Atheros, Realtek, Mediatek, Marvell, Broadcom and Intel ships in base. Details, including the GPU and fingerprint-reader story, on the hardware page.

How often are releases? Do I reinstall?

Never reinstall — it's a rolling release. shedman update (or the waybar pill) brings everything current whenever you choose. Stable releases are cut after their release candidates survive a soak; the changelog shows exactly what shipped in each.

Is it free?

Free and open source, GPL-3.0, developed in one repository — packages, installer, desktop, and this site. No paid tier, no account, no strings.

Something’s broken / I have an idea

Community page — bug reports with shedman status output and your version (pacman -Qi shedos-meta) get fixed fastest. Ideas and questions live in GitHub Discussions.