Underneath this whole story there’s a decision almost nobody makes consciously: the filesystem. The Synology used btrfs all along. The QNAP uses ZFS. And your Linux machine, most likely, came from the factory with ext4 without anyone asking you anything. That’s what this is about.

Where the two came from

ext4 is the end of a dynasty of over three decades. ext (extended filesystem) was born with Linux itself, ext2 became the standard in the 90s, ext3 added a journal in 2001 so you wouldn’t need an epic fsck after every power loss, and ext4 arrived in 2008 with extents, delayed allocation and volumes up to 1 exbibyte. The design goal was always the same: be the default filesystem, fast, simple and predictable. It’s excellent at that. And it stopped there.

btrfs was born in 2007, at Oracle, with Chris Mason, with a completely different goal: be Linux’s answer to ZFS. Instead of writing data over data, it’s copy-on-write: every write goes to a new block and the pointers are updated cascading up the tree. That single decision is the mother of everything that matters in it.

What each one delivers, in a list:

ext4:

• journaling (consistent metadata after a crash)
• extents and delayed allocation (good performance)
• mature, stable, everywhere, every tool works

btrfs:

• copy-on-write on everything
• data and metadata checksums on every block
• instant, cheap snapshots
• independent subvolumes inside the same volume
• transparent compression (zstd, lzo, zlib)
• native RAID and scrub (verification sweep)
• snapshot send/receive for incremental backup
• reflinks (copies that don’t duplicate blocks)

The list already answers the title’s question. Let’s go piece by piece.

Even NTFS and APFS have passed ext4

And if the comparison with btrfs seems unfair, look sideways. NTFS was born in 1993, with Windows NT, already with metadata journaling and ACLs, and back in the 2000s it gained a log of every change on the volume plus shadow copies (Windows’ “Previous Versions”). APFS, which Apple launched in 2017 made for flash, is copy-on-write like btrfs: native snapshots (it’s what Time Machine uses for local restores), instant file clones that share blocks, volumes sharing the space of the same container, and per-file encryption.

Read the ext4 list again and compare: no snapshots, no data checksums, no CoW, no compression. Windows’ and Mac’s filesystems, which nobody considers examples of sophistication, protect your data better than Linux’s default, whose last big feature came out in 2008. btrfs is what puts Linux in the same generation as the other two, instead of a decade behind.

Why btrfs is far superior

What copy-on-write is, for those who never stopped to think about it

In classic filesystems, writing is destructive by definition: updating a block means writing the new content over the old one, in the same place on disk. If the machine dies mid-write, the file ends up half old, half new. The ext3/ext4 journal covers that for metadata (the directory structure doesn’t corrupt), but your data itself is left to luck.

Copy-on-write inverts the order: nothing is ever overwritten. Writing to a file allocates a new block, writes the new content there, and only when everything is safely on disk does the filesystem flip the pointers to the new version, atomically. At any instant, you have either the whole old version or the whole new version. Never a mix of the two.

What that buys in practice:

• Nearly free snapshots. The old blocks already persist by CoW’s nature; a snapshot is just the filesystem holding the root pointer of that instant, pure accounting.
• Power loss doesn’t corrupt. An interrupted write leaves the previous version intact, because it was never touched. For anyone who has lost a VM image or a database to a mid-write crash, this is worth the whole filesystem.
• Verification becomes possible. Since each block is written once and never touched again, keeping its checksum forever makes sense. It’s the base of the corruption protection I detail further down.

The cost exists and I pay it knowingly: random-write-heavy files (VM disks, databases) fragment and duplicate blocks, because each rewrite becomes a new block. For those cases you disable CoW per directory with chattr +C, which must be set before the file is created. In my layout, the VM image made with the right +C stayed healthy; the one made without became the textbook fragmentation case.

Snapshots are the feature that changes your life

A btrfs snapshot is an instant photo of a subvolume, and it costs almost nothing, because CoW already keeps the old blocks while someone references them. Creating a snapshot is a seconds operation, not hours. In practice: before every upgrade, the system takes a photo. If the upgrade breaks, you don’t “uninstall packages”: you boot back into the previous photo and you’re done. The boot recovery section, further down, shows this happening for real.

Subvolumes are the right way to organize the disk

A subvolume is an independent namespace inside the same filesystem, with its own snapshot policy. And it has a killer property: snapshots are not recursive. A child subvolume inside another is automatically left out of the parent’s snapshot.

I use this for everything. On my desktop, the cache directories that can be re-downloaded (mise, rustup, npm, opencode, AI caches) are becoming nested subvolumes inside @home: they stay in the same place for any program, but out of every snapshot. That separation alone takes 165 GiB out of snapshot scope, and the big caches (Hugging Face, yay, uv, pip) already live outside the system volume, with symlinks pointing to them: minus 148 GiB of snapshot, part already migrated and part in progress. The snapshot stays small, the restore stays fast, and whatever can be re-downloaded from the internet never enters the photo.

The real cost, measured on the new QNAP (ZFS, but the CoW math is the same): 27 hourly snapshots of a folder with almost 80 TB, and nearly all of them consume megabytes, because between one hour and the next almost nothing changed. Cheap snapshots are what let this routine exist without guilt.

Reflink deduplication

First, the caveat that matters: btrfs has no native online deduplication like ZFS (which keeps a dedup table in RAM and charges dearly for it). What it has are two practical things: reflink and offline dedup. Reflink is a copy that shares blocks: cp --reflink=auto creates a new file that points to the same blocks as the original, instant and free, and each one starts diverging only where written. In the era of dozens of checkouts, worktrees and similar builds, that saves a mountain of blocks. For retroactive dedup there are userspace tools like duperemove and bees.

Real corruption protection

Every btrfs block, data or metadata, carries a checksum. When the filesystem reads and the checksum doesn’t match, it knows the block rotted, and if there’s a second copy (RAID or metadata DUP) it self-heals. ext4 checks no data at all: bit rot passes silently until you open the file years later.

Two pieces of my configuration show what that buys in practice, and what ext4 simply doesn’t offer. The first is metadata in DUP mode. On ext4, each structure on the volume exists only once: a well-placed bad sector corrupts the directory table and the whole drive stops mounting. On btrfs, even with a single drive, every metadata block exists duplicated. The bad sector keeps existing, but the checksum flags the rotten block on read and the second copy answers in its place, without you noticing. It’s the difference between losing the volume and noting a warning in the log.

The second is the monthly scrub. ext4 never re-reads anything to check health: if a block rots, you find out the day someone tries to open that specific file, maybe years later, when there’s no fixing it anymore. The scrub is a scheduled sweep that re-reads the whole volume validating checksums, and finds the rot while it’s still small and recoverable. When the btrfs device stats counter leaves zero, it’s the siren to replace the drive before the disaster, not after.

Transparent compression, measured

Every mount on my desktop uses compress=zstd:1. Level 1 costs a few percentage points of one CPU core, and btrfs detects what doesn’t compress (model blob, video) and writes it raw, at no cost. The result, measured this week on my two new drives:

That’s 630 GB of free space on 2.2 TB: 15% more drive, paying nothing. On the initial migration the gain was even bigger, 45% on the system volume, because there was more text and less binary. Notice the table’s details: programs and libraries compress well, Docker layers compress even better (39%), text logs compress 4.5x, and AI model weights compress nothing, which is expected and costs nothing. Source code, which is what we produce the most in the AI era, compresses beautifully.

Synology uses btrfs, QNAP uses ZFS

Being fair to ZFS: for a big NAS it’s superior, and it’s what I chose for the QNAP. Native checksums and self-healing, mature RAIDZ, excellent send/receive. The price is complexity and resources: ZFS wants RAM for the ARC cache (my QNAP has 7 GB for a 174 TB pool, and I feel the lack), its online deduplication would need about 190 GB of RAM just for the table on my volume, and its provisioning model gave me a free scare when the snapshot was refused with 20 TB free (the thick vs thin story is in the NAS article).

btrfs is the right balance for a consumer machine. Light, native in the kernel, does almost everything ZFS does without demanding a storage administrator. Desktop, laptop, homelab, small or medium NAS: btrfs. Synology proved it in practice, twice: the btrfs volume survived readable with two drives out, and its snapshots saved 11 albums I deleted by mistake in the middle of the cleanup, byte by byte.

Big, serious NAS, with RAM to spare: ZFS. Everything else: btrfs. And for a personal Linux machine, it’s not even a discussion.

Boot recovery via snapshot

The feature that has saved me for real, told on both machines.

On the desktop, Omarchy configures snapper to take a snapshot before every update and limine-snapper-sync publishes each snapshot as a boot entry in Limine. New kernel won’t come up? In the boot menu you pick yesterday’s snapshot and the machine comes back as if nothing happened. On my machine the scheduled routine runs via Timeshift on cron (every boot and hourly), with snapper covering the update points: the way back is the same mechanism. (The gotcha: each snapshot entry carries the kernel image along, so a small ESP fills up fast. My 1 GB one already refused a kernel update for lack of space; the system stayed bootable on the old kernel, which is the right behavior.)

On the server, which runs openSUSE MicroOS, it’s even stronger: the whole system is transactional btrfs, and every update is a new snapshot. Last week, kernel 7.2.9 took down the NVMe controller silently, twice, in the middle of the nightly backup. The fix was a transactional-update rollback and a reboot back to 7.2.6, which ran the whole load (754 GiB of backup reads with concurrent download) without a hiccup. A kernel regression became a scheduled reboot, not a recovery all-nighter. One documented caveat: /etc lives inside the snapshot, so the rollback undoes configuration changes along with it. After any rollback, check your units again.

Maintenance is not optional (and the deleted file that won’t go away)

A modern CoW filesystem delivers a lot, but it charges two routines ext4 never asked for.

The first is the scrub, which already appeared here: re-read everything and check checksums, monthly, on all machines. It’s bit-rot detection in action, and without it the checksum only warns you about the rot when you try to read the file. The second point is subtler: a snapshot pins the blocks of deleted files. When you delete a file inside a snapshotted subvolume, the space doesn’t come back, because the block stays referenced by the photo. That’s exactly what happened on my NAS: the 2.14 TB cleanup I ran on the Synology only freed space for real after the old snapshots were removed; until then, the blocks stayed pinned.

The treatment is simple routine. Retention has to be automatic, with snapper or Timeshift deleting the old snapshots per policy (on the QNAP, the Snapshot Manager’s retention policy plays the same role). Space that doesn’t come back after deleting old snapshots is usually over-allocated chunks: a btrfs balance start -dusage=50 returns the little-used pieces to the free pool (in my house I don’t blindly schedule balance, I monitor the unallocated space and act when it gets tight). And on the restic side, forget alone only removes the snapshot’s reference: the repository space is only reclaimed with prune along, forget --prune.

House cleaning in the AI coding era

Now the part almost nobody connects with filesystems: the agent era produces garbage at industrial speed. I know because I measured.

• Rust is the biggest disk polluter in the dev world. Every build leaves behind 100 to 180 MB test binaries, and they accumulate with each edit. On my desktop, the target/ directories added up to 920 GiB. ai-memory alone accounted for 704 GiB. The hygiene tool I was using is cargo-sweep, weekly. A reader pointed out that the project declares itself unmaintained, and its own README points to cargo-clean-all, which works differently: instead of pruning old artifacts inside one target/, it finds every Rust project under a directory and deletes the whole target/ of the ones you filter, for example cargo clean-all --keep-days 7 ~ to clean only what hasn’t been compiled in a week.
• Docker is right behind. On my machine I found 1.26 TB of build cache plus 938 GB of images. A single cleanup recovered about 600 GB. On the server, the weekly cleanup collects 0.6 to 4.5 GB every Sunday.
• AI and package caches bloat quietly. The Hugging Face cache had 86 GB until I deleted three dead models and it dropped to 21. Pacman had 22 GB of outdated packages. yay, uv and pip, another 125 GB.
• And agents create temporary directories without asking permission. A complex project with several branches means worktrees, and each release worktree has its own CARGO_TARGET_DIR full of test binaries. On ai-memory that has already blown up the disk, and it became a mandatory rule in the project’s AGENTS.md: after every release, cargo clean in each created worktree and removal of finished worktrees, no exceptions.

The solution is to automate the sweeping. My minimal example, a user timer that runs on the 1st and 15th at dawn, with Nice and idle I/O:

• deletes target/ directories of projects idle for more than 14 days
• cleans the yay cache
• prunes only Docker build cache older than 30 days, never images or volumes

And the part that became standard in my house: instruct the agents to clean up what they create. Three real rules from my projects, for you to copy:

In the desktop’s AGENTS.md: “Never run broad cleanups like docker system prune without explicit user authorization after a read-only inventory. Cleanup uses an exact list of IDs; idle, old or unreferenced does not mean disposable.”

In the homelab’s CLAUDE.md: “Before finishing any task, remove the temporary things the task created, and only those. Never delete what you didn’t create or can’t attribute to the task. When in doubt, list it for the owner.”

In ai-memory’s AGENTS.md: “target/ grows without limit: every edit to a shared crate leaves behind a copy of each 100-180 MB test binary (seen at 157 GiB). Weekly cargo sweep --time 7, and mandatory cargo clean after every release.”

And the real backup: restic

A snapshot lives on the same drive, so a snapshot is not a backup: if the drive dies, the snapshot dies with it. The last item in the kit is restic, which for me is the best backup system on Linux today.

restic is a single open source binary, written in Go, that does deduplicated, encrypted and versioned backup to practically any destination: another directory, another NAS via SFTP or REST, S3, Glacier. The central trick is content-defined chunking: it slices each file into variable-size blocks defined by the content, hashes each block and only writes to the repository the blocks that don’t exist there yet. That’s why the delta is cheap: today’s backup carries the blocks that changed since yesterday, not the files that changed. Editing a 100 GB database in the middle costs a few megabytes of backup, not 100 GB again. Each run becomes a repository snapshot, a restore point you browse with restic mount as if it were a filesystem, and restic check audits the whole repository’s integrity whenever you ask.

Configuration matters more than the tool, so here’s ours, mistakes included. On the desktop, the repository lives on the NAS and retention is keep-daily 7, keep-weekly 4, keep-monthly 6, keep-yearly 1. On the server, backup runs daily at dawn to the repository on the QNAP, covering /etc, /usr/local/bin, /home and the container volumes, with the password off the machine and pg_dump before the databases, because a filesystem snapshot doesn’t guarantee consistency for a database that’s writing. The first full load was 729 GiB in under an hour, and restic crossed unharmed, on retries, the window in which the NFS mount went read-only by mistake during the migration.

The most important part of the configuration is what does not go into the backup. Our exclusions, all with a reason:

• AI model caches (Immich, Hugging Face, EasyOCR): if lost, download again;
• Prometheus metrics: history that regenerates itself;
• the Fulcrum database: reindexes from bitcoind;
• the decision classifiers’ weights: re-downloadable by revision hash (and this exclusion’s glob goes inside quotes inside the bash array, because unquoted it becomes a backup source instead of an exclusion);
• node_modules, target/, cargo registry, rustup toolchains: pure build artifacts.

And one retention lesson to close. When we shortened the server policy to “yesterday, 2 dailies, 2 weeklies and 1 monthly”, the correct translation to flags is --keep-daily 3 --keep-weekly 3 --keep-monthly 2, not 2/2/1: restic’s levels overlap, and yesterday’s snapshot is also the newest of this week and this month, so each number needs to be one more than the older points you want to keep. The detail caught us off guard: the script had a literal 2/2/1, and with it the monthly level would never hold anything older than last night. In practice, the intention was to keep 5 restore points, and 2/2/1 delivers only 3: yesterday, plus one daily, plus one weekly. We erred, measured, corrected.

A humility note from the disaster: the old repositories were left on the Synology by my decision (almost 2 TB of abandoned history, because the content was already re-covered on the new QNAP). A backup repository ages too, and revisiting its scope is part of the hygiene.

Conclusion: in the AI era, disk is not a detail

Agents coding all day change the storage math at both ends. On the volume end: builds, caches, worktrees and models fill the disk much faster than any human habit ever did, and without a cleanup routine you find out when it blows up. On the safety end: the more generated code, the more you need a cheap way back, because not every agent change is a good one.

btrfs covers both. Transparent compression gives back 15% of disk for free, and source code is exactly the kind of data that compresses the most. Snapshots and subvolumes give you instant rollback on the system and isolation for what doesn’t need protection. Checksums and scrub watch the health of blocks that ext4 simply ignores. ext4 had its 15 years of well-deserved reign. In 2026, choosing it on a new Linux is giving up protection you’ll need, sooner or later. Choose btrfs and set up the cleanup today.

The problem with juggling several plans is keeping track of how much I’ve burned on each. I’d been using claudebar, a Waybar widget that shows your Anthropic plan usage. I like it, but I wanted to see all my vendors in one place, glance at it and know where I stand. And I didn’t want to clutter my Waybar with a separate widget per vendor. So I built my own: ai-usagebar.

It’s a Rust port of claudebar, drop-in compatible, extended to four vendors: Anthropic Claude, OpenAI Codex/ChatGPT, Z.AI (GLM), and OpenRouter. It keeps the same flags (--icon, --format, --tooltip-format, etc.), the same minimalist Pango-bordered tooltip, and the same Omarchy theme auto-detection. The difference is that now all four vendors show up in the same place, instead of 865 lines of bash babysitting just one.

How it authenticates with each vendor

This is the part worth explaining, because each vendor does it differently. Claude and Codex use OAuth: their official CLIs (claude and codex) already wrote the credentials to disk when you logged in, and ai-usagebar reads those same files. No environment variable needed, the token even refreshes itself.

Z.AI and OpenRouter use API keys, so for those you need to set a key (via env var or inline in the config).

The interface beyond Waybar

Besides the widget on the bar, there’s a tabbed TUI (ai-usagebar-tui) to see everything at once. Navigate with Tab / h / l between vendors, auto-refresh every 60s. You can open it by clicking the Waybar widget, or run it straight from the terminal (more on that in the next section).

The OpenRouter tab shows credit balance, today/week/month spend, and the tier:

And there’s a settings overlay to pick the primary vendor and paste the API keys without editing the config by hand:

Not on Omarchy or Hyprland? Run it as a standalone TUI

The Waybar widget is optional. The two binaries are independent, so if you don’t run Omarchy, or Hyprland, or Waybar (or you just prefer to check usage now and then instead of having it on the bar all the time), ai-usagebar-tui works as a fully standalone terminal app:

ai-usagebar-tui    # opens in your current terminal

It runs in any terminal emulator (Kitty, Alacritty, Foot, Ghostty, etc.), works even over a plain SSH session, and doesn’t depend on a compositor or any window-manager feature. All the controls and the settings overlay work the same. Same four vendors, same tabs:

Typical use off Omarchy: a quick check before starting a long session (“am I close to my Claude weekly limit?”), a monitor in a tmux pane while you code, or a shell-only tool on a remote machine (install the binary and that’s it, no Waybar or Hyprland dependency). The TUI is the canonical way to see all four vendors at once, whether or not you ever set up the widget.

Install

On Arch there’s an AUR package, two flavors:

yay -S ai-usagebar-bin    # prebuilt binary from GitHub Releases (~5s)
yay -S ai-usagebar        # compiles from source (~30-60s)

Or straight from source:

cargo build --release
sudo make install                  # → /usr/local/bin
# or
make install PREFIX=$HOME/.local   # → ~/.local/bin

The recommended Waybar config is a single module you scroll to cycle through vendors, with click to open the TUI:

"custom/aibar": {
    "exec": "ai-usagebar --format '{vendor_short} {session_pct}% · {session_reset}'",
    "return-type": "json",
    "interval": 300,
    "signal": 13,
    "tooltip": true,
    "on-click": "ai-usagebar-tui",
    "on-scroll-up":   "ai-usagebar --cycle-next",
    "on-scroll-down": "ai-usagebar --cycle-prev"
}

If you’d rather see all four vendors at once, you can use one module per vendor. The README has the full config detail, format placeholders, and the variations.

Why I built it

This looked like a Saturday-night little project, so I just did it. And it was: porting claudebar to Rust and adding the extra vendors I wanted was painless. I came out of one night with a widget that does exactly what I needed and is more reliable (tested, modular) than the original shell script.

If you use other vendors I didn’t cover, or you hit a bug, send an issue or pull request: github.com/akitaonrails/ai-usagebar. It’s MIT.

This post inaugurates an experimental project I’ve been hacking on for the past few weeks: NW-Omarchy. The pitch is easy to explain and stubborn enough to be worth defending: take the opinionated, pretty look-and-feel of Omarchy (which is Hyprland, meaning Wayland) and bring all of that to the X11 world, as a parallel session you pick at SDDM. Your Hyprland session stays untouched. When you want to try X11, pick nw-bspwm at login and land in something that looks like the same Omarchy with different parts underneath.

The obvious question is “why bother”. Red Hat already announced in 2025 that upstream xorg-server is gone from RHEL 10, and the corporate Linux narrative shifted to “use Wayland and move on”. As usual, in open source we don’t have to agree. There’s XLibre, a fork of xorg-server picking up active maintenance, and there are plenty of people with old hardware, legacy drivers, or legacy software for which Wayland still isn’t a viable path. NW-Omarchy is for that scenario: give that gear a graceful second wind and, while you’re at it, make it pretty.

What XLibre is and why it matters

XLibre is a fork of xorg-server that started in 2025, after it became clear upstream had no energy left to evolve. X.Org itself was only taking critical security patches, and the historical primary funder of new development (Red Hat) announced it was stepping out of new X-server work as part of the RHEL 10 plans. XLibre took the codebase and went back to cleanups, security fixes, modernization and driver-ABI bumps. The first public release was XLibre 25.0, and the project lives at github.com/X11Libre/xserver.

XLibre’s technical pitch is being a drop-in replacement for xorg-server. Same X11 protocol, same client API (libxcb/libx11), same dependency graph in pacman. Your xterm, your Firefox, your Steam, your favorite emulator for arcade machines from the 90s, none of them know the X server changed. Distros already shipping XLibre as default or tier-one:

• Artix Linux (2026.04+) ships it as the default X server.
• Fedora has an open Change proposal to migrate.
• Arch Linux has an official binary repo at x11libre.net/repo/arch_based/. That’s exactly what NW-Omarchy uses.

Comparing what’s still alive:

If your reason for staying on X11 is any of the classics (legacy proprietary Nvidia driver, vintage Intel GPU, Optimus laptop with quirky muxing, dependency on xdotool/wmctrl/xprop/xinput for accessibility or remap tools, ssh -X to run a remote app, clipboard with no permission prompt, screen reader that needs to read input from any window), XLibre is the path that keeps that stack under active maintenance.

Why this project exists

I run Omarchy on my Thinkpad T14 Gen 6 (wrote about it here) and I genuinely like it. DHH did serious curation work: a single coherent theme across everything (terminal, launcher, top bar, lockscreen), consistent shortcuts, visual choices that don’t tire your eyes. It’s opinionated the right way, and it spares you the fatigue of configuring everything from scratch.

The catch is that Omarchy is Hyprland, Hyprland is Wayland-only, and Wayland still has scenarios where it’s the wrong tool for the job. Older machines with legacy Nvidia drivers, environments leaning on software with deep X11 integration, situations where you want ssh -X and don’t want to learn waypipe, or just machines you want to keep running without swapping half the stack. For those cases, I wanted Omarchy’s aesthetic and workflow on top of X11. It didn’t exist. So I built it.

The name NW-Omarchy is short for “Not Wayland Omarchy”. It’s deliberately a sidecar: runs alongside, doesn’t replace. You install it on top of an existing Omarchy install, it creates a separate SDDM session called nw-bspwm, and nothing in your Hyprland setup gets touched. Want to go back to Hyprland? Pick Hyprland at SDDM next login. Want to uninstall? There’s an uninstall script that reverses exactly what got installed, based on a manifest that tracks every action.

What changes in the stack (Wayland → X11)

Hyprland is compositor + WM in the same binary. In the X11 world, those two functions come as separate pieces, and each has a well-known substitute. The translation work was mapping every Omarchy component to its X11 equivalent, then making sure the keyboard shortcuts, theming, and behavior stayed as close as possible.

bspwm is a minimalist tiling window manager. The WM itself only responds to commands over a socket, and bspwmrc is literally a shell script. Keybindings live in a separate daemon, sxhkd, which reads a plain text file. That separation is classic X11: each piece does one thing.

picom is the compositor that gives you blur, shadows, rounded corners, fade-in/out, and per-window opacity rules. NW-Omarchy uses upstream v13 (released February 2026), not the old picom-ftlabs-git fork, abandoned since 2024. The visual effects Omarchy has under Hyprland (rounded corners, fade on open/close, blur on rofi and dunst) all come from picom in NW-Omarchy.

polybar replaces waybar. Same visual layout: Omarchy logo on the left, date in the middle, audio/wifi/bluetooth/battery indicators on the right. Same nerd-font icons. Left click opens the same TUIs (wiremix, impala, bluetui), right click opens the GUI variants. Scroll on audio adjusts volume, middle click mutes. Practical parity.

rofi replaces walker. super + space opens the full launcher with every .desktop on the system plus icons. super + shift + space opens a cheat-sheet of the pinned apps, with the chord shown next to each name. Useful for remembering “what was the chord for Signal again”.

For a user who isn’t going to crack open ~/.config to customize anything, the difference between the two sessions is cosmetic at homeopathic levels. The same Omarchy shortcuts (over 70 bindings) are wired up, the same menus pop up, the same logo sits in the bar, the same nerd-font icons.

The theme system is the same

This was the most fun part to build, and the part that surprises people most. Omarchy has a centralized theme system: each theme lives at ~/.local/share/omarchy/themes/<name>/, ships a colors.toml with a universal palette (accent, background, foreground, color0..15), and omarchy-theme-set <name> re-renders each app’s config to match. The active theme lives at ~/.config/omarchy/current/theme/, and every app imports its colors from there.

NW-Omarchy plugs into that same pipeline. I added .tpl templates for bspwm, polybar, rofi and dunst that follow the Omarchy convention, and omarchy-theme-set-templates regenerates everything on every theme change. The result is that all 19 themes Omarchy ships work as-is in NW-Omarchy, with zero porting work. Catppuccin, gruvbox, kanagawa, nord, tokyo-night, all of them. The wallpaper changes along with the theme via an inotify daemon (nw-omarchy-bg-watch).

A few examples in action:

When Omarchy adds a new theme via omarchy-theme-update, NW-Omarchy gets it for free. No extra work, no rebuild, nothing for me to republish.

System menu and TUIs

Omarchy’s system menu (the super + alt + space one that opens the hierarchical menu with Hardware, Setup, Update, etc.) has a 1-to-1 port in NW-Omarchy. Same tree, same navigation. Where Omarchy calls walker --dmenu, I call rofi -dmenu. The rest of the code is identical, and most of the helpers the menu invokes (omarchy-pkg-add, omarchy-theme-set, omarchy-update, etc.) have nothing Wayland-specific in them and run straight on X11.

The TUIs too: wiremix for audio, impala for wifi, bluetui for bluetooth, btop for system resources. They all open as a centered floating window, same as Omarchy under Hyprland. bspwm has a rule (bspc rule -a) that recognizes the org.nw-omarchy.<cmd> class and applies state=floating center=on rectangle=900x600 automatically.

What’s there and what isn’t

Honesty first: there are Hyprland features that are Wayland-only and don’t come back. Per-monitor fractional scaling is gone, X11 only does integer scaling per output, so mixed-DPI setups look off. HDR doesn’t exist on X11. Tear-free rendering by design needs Wayland; on X11 you need picom + vsync and a cooperative GPU, and even then you get close to Wayland without quite matching it. Workspace swipe with live preview during the gesture is also gone, because bspwm has no in-progress switch state, so the gesture fires a discrete command only on completion (you go to the next workspace, but you don’t see the preview slide). And the Wayland-specific daemons (voxtype, walker preview pane, hyprsunset, hypridle) become redshift and xss-lock, with no preview pane in rofi.

If any of those points is a deal-breaker for you, stay on Omarchy/Hyprland. SDDM picks between the two sessions every login, so they coexist without resentment.

On the other hand, what X11 has going for it still applies. xdotool, wmctrl, xprop and xinput keep working for automation, key remapping, screen readers, AutoKey, kanata, xkeysnail. xclip, xsel and clipmenu do straightforward clipboard plumbing, no permission dialog. ssh -X keeps working: you run Firefox on a remote box and the window pops up locally. Legacy Nvidia, vintage Intel and quirky Optimus drivers are all first-class on X11. The tiling WM ecosystem is mature (bspwm, i3, awesome, openbox, xmonad, dwm) and configs port between them with little pain. And the predictable input model, where any client can read any event, is bad for security but excellent for accessibility and productivity tooling.

For older hardware, that’s the difference between “live machine” and “machine sitting in a corner”.

Install

Prerequisite: Arch Linux with Omarchy already installed. NW-Omarchy runs on top of it, doesn’t replace it.

One-liner install:

curl -fsSL https://raw.githubusercontent.com/akitaonrails/NW-Omarchy/master/boot.sh | bash

boot.sh runs preflight (checks Arch, Omarchy, git), clones the repo to ~/.local/share/nw-omarchy, and runs the full install pipeline: packages, the nw-bspwm session, configs in ~/.config, and the XLibre swap as the last step. It asks for confirmation once before touching anything. Skip the prompt with:

curl -fsSL https://raw.githubusercontent.com/akitaonrails/NW-Omarchy/master/boot.sh | bash -s -- --yes

When it finishes, reboot. The X server swap (xorg-server → XLibre) only takes effect on the next session. At SDDM you’ll see a session picker. We also swapped Omarchy’s SDDM theme for one with a selector, because the vanilla Omarchy theme has the session name hard-coded in the QML with no UI to change it. Pick nw-bspwm and you’re in.

If you’d rather clone and run by hand to inspect first:

git clone https://github.com/akitaonrails/NW-Omarchy.git ~/.local/share/nw-omarchy
cd ~/.local/share/nw-omarchy
./install.sh           # dry-run, prints what it would do
./install.sh --apply   # actually run it

Upgrade

When a new release ships, the path is:

nw-omarchy-upgrade --check    # checks current vs latest, exits
nw-omarchy-upgrade            # yay -Syu, fetch latest tag, migrations, install

The script runs yay -Syu (or pacman -Syu if you don’t have yay), compares the local tag to the remote, and if there’s a new release does git fetch && git checkout v<latest>, runs the migrations between the current and new versions, and re-applies install.sh --apply. All idempotent. Re-running on an already-current machine is a no-op.

Uninstall

If you tried it and didn’t like it, uninstall this way:

~/.local/share/nw-omarchy/uninstall.sh --apply

The uninstaller reads ~/.local/state/nw-omarchy/manifest.tsv and replays it in reverse: removes only the packages it installed (pkg-skip rows are left alone; packages that were already on the system stay on the system), restores original configs from ~/.local/state/nw-omarchy/backups/, deletes the nw-bspwm session entry, wipes the state dir. Your Hyprland session keeps working as before. Nothing under ~/.config/hypr/ or ~/.local/share/omarchy/ gets touched at any point during install or uninstall.

To revert specifically XLibre back to xorg-server (without uninstalling anything else), pacman handles it on its own:

sudo pacman -S xorg-server xorg-server-common xf86-input-libinput

The package provides/conflicts graph handles the rest of the swap atomically.

Status: experimental, feedback welcome

The current version is at 1.0 but the project is still young, in polish phase. The big items are in place: binding parity, menu parity, theme parity, TUI parity, doctor for health-checking the install, manifest for clean uninstall. What’s left is polish, edge cases, working through varied hardware, listening to feedback from anyone running it on a different machine than mine (Thinkpad T14 Gen 6).

If you try it and hit something (something that doesn’t work, configuration that’s missing, behavior that differs from Omarchy in a way that breaks flow), open an issue here:

github.com/akitaonrails/NW-Omarchy/issues

Repros, stack traces, output of nw-omarchy-doctor, anything helps. PRs are welcome too.

Defending X11 in 2026 is a pragmatic argument. The transition to Wayland takes time, plenty of hardware and plenty of software still live comfortably on this side of the fence, and the open source community can support more than one path at a time. XLibre is the bet on keeping the X server alive a few more years. NW-Omarchy is my bet that you can make this older stack look as pretty as the newer one, without compromising any of what makes X11 still worth the trip.

If you’re on a new machine, modern GPU, 4K HiDPI display, wanting HDR, stay on Omarchy/Hyprland. If you’re on an older box, or you simply prefer the X11 ecosystem for any of the reasons above, give NW-Omarchy a shot.

I bought a Lenovo Thinkpad T14 Gen 6 and installed Omarchy on it. It’s not my main machine, and it’s not supposed to be. It’s a companion: a notebook I can open on the 3D printing office desk, SSH into the desktop, fire up Claude Code, access files on the NAS, debug the network through ethernet without hunting for a USB dongle and a long cable. This article covers the hardware choice, the Omarchy setup on top, the customizations specific to a laptop and to this Thinkpad in particular, and the architecture decisions that might not be obvious.

Mini-review of the Thinkpad T14 Gen 6

Let’s get this out of the way: this isn’t the notebook of my dreams. If I were picking by looks, I’d grab an Asus Zenbook S 14 with an OLED screen. If I were picking by portability, the Thinkpad T14s with the aluminum shell, which is lighter and much better looking. The regular T14 has a 14" 1920x1200 IPS panel, 400 nits, 60Hz, no HDR. It gets the job done, but it’s a far cry from the Zenbook’s screen. The shell is plastic with a rubberized finish, which makes it scratch-resistant but not premium. Reviews from NotebookCheck and XDA Developers land on the same verdict: good price, good connectivity, fine performance for office work, but the screen is dated.

What makes up for it:

• Port selection. Full-size HDMI. Gigabit ethernet. USB-A, USB-C Thunderbolt 4, charges over USB-C (not a proprietary charger). For a debug companion, this is exactly what I wanted. The Zenbook S 14, being thinner, cuts ports.
• Fingerprint sensor that actually works on Linux (Goodix MOC, works with libfprint on kernel 6.11+). I use this, details later.
• Thinkpad keyboard. 1.5mm key travel, trackpoint, classic layout. It’s not the best keyboard in the world in 2026, but it’s reliable and durable.
• Rugged shell. It will fall, it will scratch, it will travel in a backpack. If I put a Zenbook OLED or a Macbook Pro on the 3D printing office desk next to the printer with PLA dust in the air, I’d be nervous. The Thinkpad can take a beating.

If I wanted a gaming machine, I’d get an Asus Zephyrus G14, my favorite gaming notebook. If I wanted a creative work machine, I’d get the Asus Zenbook Duo (UX8406) with two vertical OLED screens, great for video editing and 3D modeling. I can afford any Macbook Pro or Mac Studio, and I chose not to go that way. I’ll explain in the next section.

My use case

My main PC is a desktop with Ryzen 9 7950X3D, 96 GB of RAM, RTX 5090 with 32 GB. That’s where I work, experiment with local models, run containers, edit the blog. For gaming, I have a separate mini-PC with an RTX 4090. Those two cover 100% of what I need to do at home.

The notebook exists to cover the remaining 1%: sitting on the couch, taking it to the 3D printing office, taking it to the kitchen, short trips. It’s not meant to replace the desktop. It’s meant to give me remote access to the desktop when I’m away from it.

In practice it looks like this: open the notebook, split the Hyprland layout, left pane SSHs into the main desktop, right pane is the notebook itself. Same Omarchy on both, same keybindings, same bash. The notebook becomes an extension of the desktop, not a parallel environment I have to re-learn in my head every time I switch.

SSH from outside the house: Tailscale

Inside the local network, SSH is trivial, the notebook talks to the desktop through the internal IP. Outside the house is another story. My home IP is dynamic, opening port 22 to the internet is a terrible idea, and even with DDNS and port forwarding you’re putting SSH on the public internet for any scanner to find.

The solution I use is Tailscale. For those who don’t know: Tailscale is a mesh VPN built on WireGuard that creates a private network between your devices (the “tailnet”). Each machine runs the agent, authenticates once, and gets a fixed IP on the private network (something like 100.x.y.z). Traffic between your own devices goes peer-to-peer, encrypted by WireGuard. It doesn’t route through Tailscale’s central server, they only coordinate NAT traversal. Result: from my notebook in a café anywhere in the world, I run ssh hal9000 and land on my home desktop as if I were on the same network.

More sophisticated options exist: Cloudflare Tunnel with Zero Trust to expose services publicly with SSO auth, self-hosted headscale, raw WireGuard with manual config, Nebula, OpenVPN. Each has its use case. If you need to expose services to third parties, control granular per-identity access, or run the whole infrastructure at home without depending on anyone, those options win. In my case, it’s just notebook talking to desktop, for short periods (it’s not a full week of work, it’s a weekend debug session), so free Tailscale covers it. The free tier accepts up to 100 devices and 3 users, way more than I need.

Setup is as simple as it gets:

# On Arch/Omarchy
sudo pacman -S tailscale
sudo systemctl enable --now tailscaled.service
sudo tailscale up --ssh

The --ssh flag enables Tailscale SSH, which authenticates via tailnet identity instead of a local SSH key. Once you log in through the browser to tailscale, each registered machine can SSH into the others based on ACL policy defined in the admin panel. Zero key management.

I repeat the same on the desktop, log in with the same account, done. Both machines show up in the panel (hal9000 and hal9666 in the screenshot above, both with SSH enabled). From the notebook: ssh hal9000. From the desktop to the notebook: ssh hal9666. No port forwarding, no public IP, no port 22 exposed to the internet. If the notebook is stolen, I remove it from the tailnet with one click.

A practical detail: since the tailnet gives stable names, I added entries to ~/.ssh/config to use these short names:

Host hal9000
  HostName hal9000
  User akitaonrails

Now ssh hal9000 works from anywhere that has Tailscale connected. It’s the closest thing to “it just works” I’ve seen for remote SSH.

Why not a Mac

I have no use for macOS. As a dev, I live better in native Linux. Every tool I need has a first-class Linux version, and on macOS I’d get a second-class version via Homebrew. I don’t do iOS, so I don’t need XCode. For mobile I use Flutter or Hotwire Native, which run on any OS. iTerm2 and Ghostty on Mac are fine, but Alacritty, Kitty and Ghostty itself on Linux work just as well. Every good piece of software lands on Linux first and gets ported afterwards. Arch with AUR covers everything in a single yay.

For creative work, I haven’t done it professionally in years. DaVinci Resolve Studio on Linux is better than Final Cut Pro. Krita or Affinity Photo replace Photoshop for most cases. Clip Studio Paint on Android is better than Procreate. I simply don’t have a workflow that depends on Apple, and the App Store annoys me.

For gaming, Mac is terrible. Apple Silicon has a decent GPU for some things, but the native macOS game library is pathetic compared to Windows or Linux. Game Porting Toolkit exists, CrossOver exists, but for anyone who games seriously, it doesn’t cut it. I won’t be gaming on the Thinkpad, I have the main desktop and the mini-PC with the RTX 4090 for that. But if I ever feel like running Hollow Knight or some indie on a train, I just install Steam and let Proton handle it. Linux became a real gaming platform in the last few years, with Proton/DXVK running almost the entire Steam catalog (check ProtonDB). I recently wrote about running my emulation library in distrobox without polluting the host system. With Mac, those options don’t exist.

Another argument that always shows up: “but a Mac Mini M4 or a Mac Studio with 128GB of unified memory runs large models locally, it’s a ChatGPT replacement.” I already tested that thesis and wrote a detailed benchmark. The conclusion: expensive local hardware to run LLMs is a weekend hobby, not a production tool. The open source models that fit don’t deliver the quality Claude Opus delivers. I have a home server with AMD Strix Halo and 96 GB of unified RAM, I ran models for dozens of hours, and in my real coding flow they’re fine for simple tasks. For complex tasks, Claude Opus. Before spending $4000 on a Mac Studio justifying it with local models, actually test it first. You’ll probably end up paying for Opus again.

Why Omarchy

I’ve been using Omarchy on the desktop for months and documented the path in a series of articles. Omarchy 2.0 has its own installer with LUKS, Btrfs, Limine, snapper and SDDM already configured. I wrote about using the official ISO, about ZSH customizations with atuin, starship, secrets properly organized, about Mise for multiple languages, about LazyVim and LazyExtras, about SSH and Yubikeys, about modern TUIs. There’s also Omarchy 3 with dual GPU AMD + NVIDIA and Crush as a coding agent.

For those who don’t know: Omarchy is plain Arch Linux with a cosmetic layer on top of Hyprland/Wayland. Pre-configured with sane defaults. I could build all of it from scratch, I’ve done it several times in my life, but why redo work someone already did well? I install Omarchy, I stack the tweaks that are mine on top, and I have customized Arch in a fraction of the time.

A point I raise every time I recommend Omarchy: the documentation is excellent. There’s an official manual covering everything from installation to theme customization, keybindings, Hyprland, Waybar, the works. If you’re coming from Ubuntu or Fedora and are wary of Arch, this manual handles most of the doubts. If you’ve never touched Hyprland, open it and read around. It’s not a README dumped on GitHub, it’s a real manual with chapters and an index.

The story of this article starts in a previous thread. I recently migrated my home server, swapping an old Ubuntu box for a Minisforum MS-S1 running openSUSE MicroOS configured with Claude Code. That was the first serious experiment of letting Claude Code drive an entire infra migration, with containers, NFS, services, networking. It worked. And it left an idea in the air: why not use the same approach to configure a new notebook?

That’s what I did. I grabbed the Thinkpad, downloaded the latest Omarchy ISO, burned it to a flash drive, installed it over Windows. From zero to working desktop in under an hour. From there on, it’s all tweaking, which I documented as I went.

I’ll detail the two layers of customization: what any notebook needs, and what’s specific to this Thinkpad.

Laptop-specific configs

A notebook has problems a desktop doesn’t: battery, suspend, lid, brightness, trackpad. Those are the parts Omarchy default doesn’t cover the way I want.

Power management with TLP

Omarchy defaults to power-profiles-daemon. I swapped it for TLP, which gives granular control over CPU scaling, battery thresholds and dynamic profiles based on AC vs battery.

sudo pacman -S tlp tlp-rdw
sudo systemctl mask power-profiles-daemon.service
sudo systemctl enable --now tlp.service

The mask is necessary because upower pulls power-profiles-daemon back in if you just disable it.

Charge thresholds: 60% to start, 85% to stop. The notebook spends most of its time plugged in on the office desk, and keeping the battery at 100% 24/7 wrecks capacity over time. With 60/85, the battery spends most of its time in the healthy lithium range and still has decent usable capacity.

Profiles: balanced with balance_power on battery, performance on AC. TLP’s low-power was too aggressive on the Core Ultra 5 235U, window and terminal response became noticeable. Balanced gives the best consumption/responsiveness ratio for normal use.

There’s a gotcha: tlp auto after tlp ac doesn’t always re-apply the battery profile. I wrote a small script bound to Super+Ctrl+P that reads the current state and calls tlp bat or tlp ac explicitly:

#!/bin/bash
set -euo pipefail

profile=$(cat /sys/firmware/acpi/platform_profile 2>/dev/null || echo unknown)
on_ac=$(cat /sys/class/power_supply/AC*/online 2>/dev/null | head -1 || echo 0)

if [[ "$profile" == "performance" ]]; then
  if [[ "$on_ac" == "1" ]]; then
    sudo /usr/bin/tlp auto >/dev/null
    label="Plugged in — back to AC auto"
  else
    sudo /usr/bin/tlp bat >/dev/null
    label="On battery — normal profile"
  fi
  notify-send -t 2000 "Performance mode: off" "$label" 2>/dev/null || true
else
  sudo /usr/bin/tlp ac >/dev/null
  notify-send -t 2000 "Performance mode: on" "Forcing AC profile" 2>/dev/null || true
fi

In waybar, a custom module custom/perf shows the current state (󰓅 PERF, 󰌪 ECO, or empty for balanced) and accepts a click to toggle. The output script is tiny:

#!/bin/bash
p=$(cat /sys/firmware/acpi/platform_profile 2>/dev/null)
case "$p" in
  performance) printf '󰓅 PERF' ;;
  low-power)   printf '󰌪 ECO'  ;;
  balanced|"") printf ''       ;;
  *)           printf '%s' "$p" ;;
esac

Suspend, hibernate, and the lid

This is what changed compared to the notebooks I used in 2015. The T14 Gen 6 closes the lid, suspends, and wakes up when you open it. No bug, no weird delay, no needing to log in again mid graphical session. Hyprlock kicks in after the suspend, accepts fingerprint or password, and brings me back to the desktop in seconds. This is the behavior Apple has had for years and that on Linux used to be an adventure. In 2026, on modern hardware with kernel 6.11+, it just works.

Mem sleep mode is s2idle (no deep sleep). Hibernation is enabled via a ~30 GB Btrfs swapfile and resume=/dev/mapper/root resume_offset=... on the Limine kernel cmdline. I rarely use it, but it’s there.

Hypridle has aggressive timeouts for a laptop:

• 2.5 min → screensaver
• 5 min → lock
• 5.5 min → DPMS off + keyboard backlight off

After lock, another 5 min and the screen turns off completely. On unlock, it restores screen and keyboard brightness to the previous level. These timings are much shorter than on the desktop (20-40 min there). The battery difference over a day is measurable.

Brightness and keyboard backlight

brightnessctl controls both. Fn+Space toggles the keyboard backlight across three levels. Hypridle saves the current level before turning off and restores it on resume. Command I use in the script:

brightnessctl -sd '*::kbd_backlight' set 0    # save and turn off
brightnessctl -rd '*::kbd_backlight'          # restore

Touchpad

In hypr/input.conf:

touchpad {
    natural_scroll = true
    clickfinger_behavior = true
    disable_while_typing = true
    scroll_factor = 0.4
}
gesture = 3, horizontal, workspace

clickfinger_behavior swaps the 2-finger click as right-click (more comfortable than hitting the lower-right zone). disable_while_typing is basic palm rejection. Three-finger horizontal swipes switch workspaces, the most useful gesture in Hyprland.

Thinkpad-specific configs

This is what’s specific to this model. Some things modern Linux handles on its own, others need explicit configuration.

Fingerprint sensor

Goodix MOC 27c6:6594, works with libfprint 1.94.9+ on kernel 6.11+. Package is fprintd.

sudo pacman -S fprintd
fprintd-enroll                        # right index finger by default
fprintd-enroll -f left-index-finger   # other finger

To make sudo accept fingerprint, I added auth sufficient pam_fprintd.so above the pam_unix.so line in /etc/pam.d/sudo. With sufficient, if the fingerprint passes, it authenticates directly. If it fails or I hit ESC, it falls back to the password prompt. This is genuinely worth it: dozens of times a day, sudo pacman -Syu or sudo systemctl restart something, and I just touch the sensor.

On hyprlock, I use hyprlock’s native configuration, not PAM:

auth {
    fingerprint {
        enabled = true
        ready_message = Scan fingerprint or type password
        present_message = Scanning...
        retry_delay = 250
    }
}

The PAM path gives a double prompt. Configured natively, hyprlock accepts fingerprint or password, whichever succeeds first unlocks.

On SDDM (initial login), I kept password only. The reason: the login password unlocks the GNOME keyring, and the fingerprint can’t provide plaintext for that. Once the keyring is unlocked, hyprlock can use fingerprint without issues.

In practice, sudo looks like that. Touch the sensor, authenticate, move on.

Brazilian Thinkpad keyboard

The Brazilian Thinkpad keyboard has an annoying quirk. The /? key sits where the right Ctrl would be (keycode 97), not in the traditional ABNT2 AB11 position (keycode 89). If you use the standard br(abnt2) layout, that key is inaccessible. It literally prints nothing.

The solution is the br(thinkpad) variant that exists in /usr/share/X11/xkb/symbols/br:

xkb_symbols "thinkpad" {
    include "br(abnt2)"
    name[Group1]="Portuguese (Brazil, IBM/Lenovo ThinkPad)";
    key <RCTL> { [ slash, question, degree, questiondown ] };
};

In hypr/input.conf:

kb_layout = br
kb_variant = thinkpad
kb_model = thinkpad60

And system-wide for TTY/X11:

sudo localectl set-keymap br-abnt2
sudo localectl set-x11-keymap br thinkpad thinkpad60

I wrote a small Python that reads raw scancodes from /dev/input/event* to diagnose these quirks. Useful when a key decides not to work and you need to find out if it’s hardware, kernel, or xkb.

Input method: fcitx5

Alongside the layout I install fcitx5. Input method, for those who don’t know, is the layer that turns a key sequence into characters. It handles deadkeys (tilde for nasalization, acute accent, circumflex), composing characters that aren’t on the keyboard (ç, Ç, uppercase accented letters), emoji support. In Qt or GTK apps, the input method also drives context menus for cedilla and accents.

Packages:

sudo pacman -S --needed fcitx5 fcitx5-configtool fcitx5-gtk fcitx5-qt

And the environment variables for toolkits to find fcitx5. I created ~/.config/environment.d/fcitx.conf:

INPUT_METHOD=fcitx
QT_IM_MODULE=fcitx
XMODIFIERS=@im=fcitx
SDL_IM_MODULE=fcitx

systemd’s environment.d is loaded before graphical sessions, so Brave, Alacritty, VS Code and any GTK/Qt app pick it up automatically. I enable autostart in Hyprland:

exec-once = fcitx5 -d

Typing ~a produces ã, 'e produces é, ç works as it should in every app. On a Brazilian Thinkpad keyboard, this is the difference between typing Portuguese naturally or hunting for each character.

SOF audio

Realtek ALC3306/ALC287 codec via Sound Open Firmware. Without sof-firmware, the kernel module loads but the DSP never boots and PipeWire silently falls back to auto_null. Result: you think the speaker is on mute, but actually PipeWire has no device at all.

sudo pacman -S --needed sof-firmware alsa-ucm-conf pipewire pipewire-pulse wireplumber

If you need to force SOF instead of legacy HDA:

echo "options snd-intel-dspcfg dsp_driver=3" | sudo tee /etc/modprobe.d/alsa.conf

Reload without reboot:

sudo modprobe -r snd_sof_pci_intel_mtl
sudo modprobe snd_sof_pci_intel_mtl
systemctl --user restart wireplumber pipewire pipewire-pulse

Firmware updates via fwupd

fwupdmgr update works, but with Limine there’s a gotcha: fwupd tries to write to /boot/EFI/systemd/ or /boot/EFI/arch/, which don’t exist. The workaround:

sudo mkdir -p /boot/EFI/arch
sudo fwupdmgr update -y --no-reboot-check
fwupdmgr get-history  # should show "Success"

HiDPI / fractional scaling

14" panel at 1920x1200, Hyprland’s free resolution. Omarchy’s auto 1.5x felt too chunky. I pinned it at 1.333x:

env = GDK_SCALE,1
monitor=,preferred,auto,1.3333,vrr,2

Effective 1440x900. GTK with GDK_SCALE=1 renders 1:1 with Hyprland (no double magnification). VRR mode 2 only in fullscreen, because LCD panels tend to flicker on static content with VRR active.

Brave and Chromium flags to render well at this scale:

--ozone-platform=wayland
--enable-features=WaylandFractionalScaleV1,UseOzonePlatform,VaapiVideoDecoder,VaapiVideoEncoder
--enable-gpu-rasterization

VAAPI makes a real difference on YouTube battery life.

Tuning Omarchy to be mine

Omarchy comes with good defaults. What I adjust stacks on top of them, without touching ~/.local/share/omarchy/ (which is clobbered by omarchy-update). All customization lives in ~/.config/.

Infra: Btrfs, snapshots, Snapper

Omarchy already ships with Btrfs and separate subvolumes:

@home separated means ~/.cache, ~/.config/BraveSoftware, etc. don’t bloat root snapshots. Snapshot is for system, not profile.

Swap: 4 GB zram at priority 100 (hit first), plus a 30 GB swapfile at priority 0 (enables hibernation, sized to match RAM).

The snapshot stack: Snapper takes a snapshot before and after every pacman -Syu via snap-pac. limine-snapper-sync writes those snapshots into the Limine menu, so you can boot into a previous snapshot to roll back. If something breaks after an update, you hold a key on boot, pick the pre-update snapshot, boot read-only to verify, and if it’s good, run snapper rollback.

Omarchy leaves snapper-cleanup.timer and snapper-boot.timer disabled by default. I enabled both and configured retention to fit on a 1 TB SSD without blowing up:

TIMELINE_LIMIT_HOURLY=10
TIMELINE_LIMIT_DAILY=0
TIMELINE_LIMIT_WEEKLY=1
TIMELINE_LIMIT_MONTHLY=1
NUMBER_LIMIT=50

A detail that costs debug time if you forget: Docker and Ollama write gigabytes into /var/lib/docker and /var/lib/ollama. If that falls inside @, snapshots go catastrophic. Each Docker image or Ollama model downloaded triples in size. I created nested subvolumes for both, with chattr +C to disable CoW:

sudo btrfs subvolume create /var/lib/docker
sudo chattr +C /var/lib/docker
sudo btrfs subvolume create /var/lib/ollama

This has to be done BEFORE Docker or Ollama writes any data. If they already have data there, you need to migrate.

NFS to the Synology NAS

My Synology exposes three volumes. On the desktop, I mount them the usual way. On the notebook, it has to be more defensive. The notebook moves around, forgets networks, connects to public WiFi. Notebook’s fstab:

nfs4  _netdev,noauto,nofail,x-systemd.automount,x-systemd.idle-timeout=10min,x-systemd.mount-timeout=15s,noatime,nodiratime,nconnect=4,actimeo=10,soft,timeo=30,retrans=2

Critical difference vs the desktop: soft with short timeouts (doesn’t hang forever), x-systemd.idle-timeout=10min (auto-unmount when idle), no network-online.target in the require (doesn’t slow boot). Practical result: cd /mnt/gigachad at home mounts lazily, away from home it fails fast without locking the shell.

Another important detail: my user on the notebook has UID 1026, which matches the share permissions on the Synology. Linux defaults to creating users at 1000, the Synology enforces identity via UID on the wire. If the UIDs don’t match, you can’t read the files, or worse, you write as nobody. I ran the usermod/groupmod from a TTY (with the user logged out) to remap the user to 1026/1026 and did chown -R on /home.

Public WiFi hardening

The notebook will leave the house. In an airport or café, I don’t want to announce hostname, don’t want a trackable MAC, don’t want a service listening on an open port.

/etc/NetworkManager/conf.d/00-macrandomize.conf:

[device]
wifi.scan-rand-mac-address=yes

[connection]
wifi.cloned-mac-address=stable
ethernet.cloned-mac-address=stable
connection.stable-id=${CONNECTION}/${BOOT}

ipv6.ip6-privacy=2
ipv6.addr-gen-mode=stable-privacy

Random MAC per scan (passive anti-fingerprinting). Stable cloned MAC per SSID (captive portals don’t re-prompt you every time) but different MACs between networks. IPv6 with temporary addresses and interface ID derived from a stable secret, not from the MAC (no EUI-64 leak).

/etc/systemd/resolved.conf.d/hardening.conf:

[Resolve]
LLMNR=no
MulticastDNS=no

Kills hostname broadcast on LLMNR and mDNS. I also disable avahi:

sudo systemctl disable --now avahi-daemon.service avahi-daemon.socket

UFW firewall:

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw --force enable

SSH server is already off by default on Omarchy. Nothing listening. Even if the firewall leaks, there’s no surface.

All of it rolls into a single initial setup ritual.

SSH agent persistence (keyring + keychain)

If you use SSH seriously, you want to type the passphrase once per boot and have ssh, git push, scp stay silent for the rest of the day. On current Arch there’s a catch: gnome-keyring 50 dropped its SSH component, and the replacement (gcr-ssh-agent) is a plain in-memory agent with no passphrase persistence. The “remember this key” checkbox you saw in old guides simply doesn’t exist anymore.

The combination that works has three pieces:

1. gcr-ssh-agent.socket managed by systemd serves SSH_AUTH_SOCK at $XDG_RUNTIME_DIR/gcr/ssh
2. pam_gnome_keyring on SDDM login unlocks the keyring with the login password (used by GUI apps like Brave, not by SSH)
3. keychain (wrapper) keeps an ssh-agent alive across logouts, overrides SSH_AUTH_SOCK to point at that persistent agent, and caches the PID in ~/.keychain/<host>-sh

First, install the keyring:

sudo pacman -S --needed gnome-keyring seahorse keychain

Then edit /etc/pam.d/sddm so the login password unlocks the keyring automatically. Add at the top:

-auth      optional    pam_gnome_keyring.so

And at the end:

-session   optional    pam_gnome_keyring.so    auto_start

The leading hyphen (-auth, -session) marks it optional, so if the module fails to load, login doesn’t break.

Pin SSH_AUTH_SOCK for graphical and TTY sessions via ~/.config/environment.d/ssh-agent.conf:

SSH_AUTH_SOCK=%t/gcr/ssh

%t resolves to $XDG_RUNTIME_DIR, something like /run/user/1026. Enable the gcr socket and user linger (so user daemons survive logout):

systemctl --user enable --now gcr-ssh-agent.socket
sudo loginctl enable-linger $USER

Finally, in ~/.config/bash/init.sh, keychain starts or reuses the agent:

if command -v keychain &>/dev/null && [[ -r ~/.ssh/id_ed25519 ]]; then
  eval "$(keychain --eval --quiet ~/.ssh/id_ed25519)"
fi

--eval emits shell assignments (SSH_AUTH_SOCK, SSH_AGENT_PID) pointing to keychain’s agent, overriding the gcr path set by environment.d. --quiet silences the banner once the key is loaded.

Flow in practice: boot → first terminal → keychain prompts for the passphrase once → key stays loaded. Logout → login again → new shells reattach to the same agent (via ~/.keychain/<host>-sh) → zero prompts. ssh-add -l confirms the key is there, echo $SSH_AUTH_SOCK confirms it’s at keychain’s path.

When you’ll re-enter the passphrase: reboot, ssh-add -D, or keychain --clear. In normal use, once a day.

Bash instead of ZSH

On the desktop I use ZSH. On the notebook I went with Bash to align with Omarchy’s default, without having to maintain a parallel stack of modular layers. ~/.bashrc is a symlink to ~/.config/bash/bashrc, which sources Omarchy’s defaults first and then stacks my customizations:

source ~/.local/share/omarchy/default/bash/rc
source ~/.config/bash/envs.sh
source ~/.config/bash/aliases.sh
source ~/.config/bash/mounts.sh
source ~/.config/bash/init.sh
source ~/.config/bash/secrets    # gitignored, chmod 600

envs.sh has what’s mine: OpenRouter base URL, Ollama pointing to the LAN GPU box (192.168.0.14), AWS region, Hugo analytics, zoxide and SSH agent configs. aliases.sh has TLP shortcuts, an alias for shell-gpt via Docker, and functions to harden PATH when running makepkg or yay (prevents binary injection via a malicious user config).

init.sh does the integration work. Atuin with a manual bind for Ctrl-R (so the up arrow keeps bash’s default history-search, which I use more). Keychain loading ~/.ssh/id_ed25519 once per boot and reusing it across shells (no need to re-authenticate SSH every time). Blesh if installed (ZSH-style autosuggestions for Bash). And a function that has PROMPT_COMMAND set the window title to the current pwd and the running command:

__title_idle() { printf '\033]2;%s\007' "${PWD/#$HOME/~}"; }
__title_busy() {
  local cmd="${BASH_COMMAND}"
  [[ "$cmd" == "__title_"* || "$cmd" == *"PROMPT_COMMAND"* ]] && return
  printf '\033]2;%s — %s\007' "${PWD/#$HOME/~}" "$cmd"
}
if [[ -n "${PROMPT_COMMAND-}" ]]; then
  PROMPT_COMMAND="__title_idle; ${PROMPT_COMMAND}"
else
  PROMPT_COMMAND="__title_idle"
fi
trap '__title_busy' DEBUG

Idle, the title shows just the pwd. With a command running, trap DEBUG catches the BASH_COMMAND and updates the title. Waybar’s hyprland/window picks that up and displays it.

For the modern Rust toolbelt, the list:

sudo pacman -S --needed \
  eza bat fd ripgrep sd git-delta dust procs bottom duf tokei hyperfine \
  zoxide atuin tldr starship

eza replaces ls. bat replaces cat with syntax highlighting. fd replaces find. ripgrep replaces grep. sd replaces sed. delta plugs into git for colored side-by-side diff. dust for visual du. procs for ps. btm (bottom) for top. duf for df. tokei counts lines of code. hyperfine for command benchmarking. zoxide is cd with memory (very useful). atuin is shell history with encrypted sync (I point it to my home server via sync_address = "http://192.168.0.90:8888"). starship is the prompt. tldr is a man page in 10 lines.

The atuin key has to be backed up offline. If you lose it, you lose the encrypted history. I saved mine in my self-hosted Bitwarden (Vaultwarden), documented in the Bitwarden self-hosted article.

Git pipes diff through delta:

[core]        pager = delta
[interactive] diffFilter = delta --color-only
[delta]       navigate side-by-side line-numbers hyperlinks, light=false
[merge]       conflictstyle = zdiff3

Hyprland and Waybar

Visual and UX customizations on top of the default.

In hypr/looknfeel.conf, smaller gaps (2/5 vs the default 5/10), slide animation between workspaces, VFR on (reduces consumption when the screen is static), allow_session_lock_restore (if hyprlock crashes, it goes back to the lock screen instead of dumping you on the desktop).

In hypr/bindings.conf:

On Waybar, three custom modules I recommend:

Window title: the hyprland/window module shows what’s focused. In bash, PROMPT_COMMAND updates the title to something like “~/Projects/blog — hugo server”. So in waybar the directory and running command show up, without me needing to look at the terminal.

"hyprland/window": {
    "format": "{title}",
    "max-length": 50,
    "rewrite": { "(.{47}).+": "$1…" }
}

Perf mode: custom/perf runs a script that reads TLP state and shows an icon:

"custom/perf": {
    "exec": "~/.config/scripts/perf-waybar.sh",
    "interval": 3,
    "format": "{}",
    "on-click": "~/.config/scripts/perf-toggle.sh"
}

Empty for balanced, 󰓅 PERF for performance, 󰌪 ECO for low-power. Click toggles. Useful to quickly see what mode the machine is in.

Claudebar: I integrated claudebar as a custom module that shows the Claude Code session usage % and extra spend inline in waybar. No need to open another window.

The clock:

"clock": {
    "format": "{:L%A %d %B - %H:%M}",
    "format-alt": "{:L%A W%V %Y - %H:%M}"
}

Shows “Thursday 17 April - 14:32” by default, click toggles to “Thursday W16 2026 - 14:32” with the ISO week number, useful for planning articles and tasks.

Self-hosted Atuin

Atuin runs on my home server at 192.168.0.90:8888. I made a separate account for the notebook (akitaonrails-thinkpad), I don’t mix history with the desktop on purpose. atuin sync runs every 5 minutes and all history is encrypted before going to the server. The server doesn’t see the commands, only encrypted bytes.

Conclusion: picking a notebook for Linux

One thing I learned on this journey: picking a notebook to run Linux comfortably is not trivial. You have to check the ArchWiki for your specific model before buying. The T14s Gen 6 AMD page, for example, catalogs every hardware quirk and how to work around it. Without that reference, you discover the problems during install.

Rule I follow: never buy a freshly-released model. Let 6 to 12 months go by after launch. That gives the community time to iron out bugs, drivers to land mainline, the ArchWiki to have a decent page, libfprint to include the fingerprint sensor, and the kernel to cover WiFi and the IR camera. Buying on day one means signing up as a beta tester.

Brands with a decent Linux track record: Lenovo (especially Thinkpad, they ship Ubuntu and Fedora pre-loaded), Dell (the XPS and Latitude lines), Asus (Zenbook and ROG have reasonable support), Framework (built for Linux from the factory). Any recent Mac is cut off from Linux mainline or runs through Asahi with caveats.

The Thinkpad T14 Gen 6 isn’t the prettiest notebook I could have bought. But it’s rugged, it has the right ports, the fingerprint sensor works, and the plastic shell lets it fall, get scratched, travel in a backpack without making me nervous. To serve as a remote debug companion, it’s what I needed. If that’s your use case too, I recommend it. If you want OLED and metal, go Zenbook or T14s. Every premium comes with a compromise, no Linux notebook in 2026 is perfect.

Everything I described here is versioned in a private repo of mine. If I need to reinstall tomorrow, I run half a dozen steps in order and I’m back at the same place. That’s the whole point of keeping config in Git: notebook is commodity, config is mine.

Hyprland doesn’t play nice with NVIDIA

You can use it. But there are several little problems, particularly with Hyprlock, and particularly with DPMS where I leave my computer idle, it locks itself, and after a timeout turns off the monitors to save power, avoid burn-in, etc.

When I try to wake it from sleep, Hyprlock crashed and I have to jump to another TTY to restart it. I even wrote a ~/.local/bin/hypr_unlock.sh script like this:

hyprctl --instance 0 'keyword misc:allow_session_lock_restore 1'
hyprctl --instance 0 'dispatch exec hyprlock'

But then I unlock and see that my Brave crashed too. NVIDIA really doesn’t like the monitor being turned off while it’s active. People said this happened in Hyprlock 0.9.1, but I’m already on 0.9.2 and it still crashes. I tried enabling services like nvidia-suspend/resume/hibernate, but nothing worked either.

At the end of the day I decided it’s not worth fighting with this: I have an AMD 7850X3D, and this CPU has an iGPU (integrated GPU), an AMD Raphael, which for things like rendering a window manager is more than powerful enough.

First, detect the GPUs:

❯ ls /dev/dri/by-path
Permissions Size User Date Modified Name
lrwxrwxrwx     - root 21 Jan 15:22   pci-0000:01:00.0-card -> ../card1
lrwxrwxrwx     - root 21 Jan 15:22   pci-0000:01:00.0-render -> ../renderD128
lrwxrwxrwx     - root 21 Jan 15:22   pci-0000:1a:00.0-card -> ../card2
lrwxrwxrwx     - root 21 Jan 15:22   pci-0000:1a:00.0-render -> ../renderD129

To find out which is AMD and which is NVIDIA, just run:

❯ lspci | grep -i vga
01:00.0 VGA compatible controller: NVIDIA Corporation GB202 [GeForce RTX 5090] (rev a1)
1a:00.0 VGA compatible controller: Advanced Micro Devices, Inc. [AMD/ATI] Raphael (rev c9)

Done. From the PCI ID we know card1 is NVIDIA and card2 is AMD. Now I need to configure my ~/.config/hypr/hyprland.conf:

....
# NVIDIA environment variables
env = NVD_BACKEND,direct
#env = LIBVA_DRIVER_NAME,nvidia
env = LIBVA_DRIVER_NAME,radeonsi
#env = __GLX_VENDOR_LIBRARY_NAME,nvidia

# Comment these out when using AMD as primary
#env = __NV_PRIME_RENDER_OFFLOAD,1
#env = __VK_LAYER_NV_optimus,NVIDIA_only

# card1=nvidia, card2=amdgpu (verify with: cat /sys/class/drm/card*/device/uevent)
# AMD first for iGPU primary:
env = AQ_DRM_DEVICES,/dev/dri/card2:/dev/dri/card1

env = ELECTRON_OZONE_PLATFORM_HINT,auto

I left the NVIDIA-specific settings commented out; none of them can be active. But the most important line is AQ_DRM_DEVICES, which lists the order for Hyprland to pick the GPU. Card2/AMD has to come first. Done, just reboot and move the HDMI cables to the iGPU output.

With that, I can now choose to offload only some apps to the NVIDIA using Prime. For that, I first created the script ~/.local/bin/nvidia-load.sh:

#!/bin/bash
__NV_PRIME_RENDER_OFFLOAD=1 __VK_LAYER_NV_optimus=NVIDIA_only __GLX_VENDOR_LIBRARY_NAME=nvidia "$@"

Finally, I configured some bindings in ~/.config/hypr/bindings.conf:

...
bindd = SUPER SHIFT, B, Blender, exec, ~/.local/bin/nvidia-load.sh blender
bindd = SUPER SHIFT, L, Bambu Studio, exec, ~/.local/bin/nvidia-load.sh bambu-studio
bindd = SUPER SHIFT, P, Blender, exec, ~/.local/bin/nvidia-load.sh plasticity
...

This way, only Blender, Plasticity, and Bambu Studio, which primarily use the NVIDIA to render 3D in real time. All the other apps open on the AMD iGPU.

AI tools like ComfyUI, Ollama, or LM Studio automatically recognize the NVIDIA and pick it. And with that I also have more free VRAM to load LLMs.

If you’re going to use XLibre/X.org, you can stay on NVIDIA just fine. But if you’re going to use Wayland, NVIDIA still isn’t fully stable, particularly with Hyprland. It’s less of a headache to drop in a second AMD GPU just for this.

Lucky for us, the open source side is cooking up new options. DHH decided to bring OpenCode into Omarchy 3.x.

After I ran the upgrade (just omarchy-update) I noticed I also got the option to install the one I’m starting to play with now, CRUSH.

Crush is from the same crew that’s been cranking out a bunch of libraries to make TUI (Terminal User Interface) development easier, like BubbleTea and Gum. I’d recommend digging into those repos too. Building terminal apps is way more interesting these days, especially dev tools or anything Linux-flavored.

It’s a really well-built TUI. Here’s what it looks like:

For a first pass I ran it on this little blog project, which is a static site generated with Hugo.

Since I already have the env vars set up for OpenRouter, I didn’t even need to configure anything. Just crush inside the project directory.

The first thing it did was analyze my project. It’s small, so it was quick. I have no idea how it handles giant projects. But it goes scanning through the source code and at the end writes everything down in an AGENTS.md file. And I was impressed by how good of a job it did summarizing the project. Take a look at this snippet:

I didn’t even know I had the option of running scripts/dev.sh new-post to automatically create the timestamped subdirectory for a new post. I’d been doing that by hand every single time 😅.

I knew my scripts/generate_index.rb script was kind of a mess, so I asked Crush if it could refactor it:

And in the end it refactored the thing nicely, no new bugs introduced, no rewriting stuff that didn’t need rewriting. It really nailed refactoring only what needed to be touched. It changed things like using Dir.glob instead of Find.find, switched to symbols instead of strings (more idiomatic), that kind of thing.

I liked that it ran the modified version and checked that it still worked the way it was supposed to.

Then I asked it to do the same thing with scripts/dev.sh:

And in this case it actually found a bug I hadn’t noticed. Again, it edited the shell script to make it safer, separated constants out, improved error checking, and so on.

Here’s the commit with the changes. Take a look. It really didn’t add any unnecessary code. Everything still works the way it did before, but now it’s more organized. And on top of that it caught a bug I had missed.

For this little example I picked the Claude Opus 4.5 model. All the code came out of it. Crush is just the agent that talks to the model and feeds it the right context.

So far I’ve only done easy, dumb stuff. The docs say it integrates with LSPs and MCPs to get even more context about the code, but I haven’t tested that yet.

Either way, I figured I’d write a quick post just to say that these new options like Crush and OpenCode are already plenty good for daily use. Worth trying on your own project.

Second Test

Since Crush did fine with that basic web test, I figured I’d throw it last year’s challenge. I’d built a tiny command-line project that’s a basic chat, written from scratch, talking directly to the llama.cpp library, with CUDA, in Zig — which is a low-level language, still experimental and unfinished. The whole point of the challenge is that almost nobody uses it, so there’s barely any documentation or examples. The LLM has to actually sweat to make it work.

Unlike a web page with React and Tailwind — which has thousands of forum posts, tutorials, blog posts and everything else — Zig has almost nothing. The only popular app I know of that uses Zig is Ghostty.

To make it worse, a new version came out recently, 0.15, which changed a whole bunch of the IO API (in preparation for better Async IO support). New versions of Llama, Cuda, etc. also dropped. So the idea was to use Crush with Claude Opus to see if it could refactor, fix bugs, update the APIs, and get to the point of compiling a working binary.

In short: it pulled it off!

On the first refactoring pass, it burned only USD 5.64 of credit on my Anthropic account. It managed to take the spaghetti monolith (which I’d written that way on purpose as a challenge) and split it into smaller files like chat.zig and llama.zig.

It managed to map the C functions from Llama as Zig functions. It managed to figure out that things like ArrayList changed in the new Zig. It managed to figure out that all the IO APIs changed in 0.15. And it managed to modify the right places.

It ran zig build, checked the errors and made fixes that actually made sense, until it produced the final binary.

You can check the Pull Request with everything it did. It was a pretty reasonable amount of change and didn’t leave the project broken.

The fact that it managed to consult the Zig 0.15 documentation, and also correctly infer which new Llama.cpp functions it should make extern, was pretty impressive.

Anyway, on the first pass it got to the point where it compiles. But that doesn’t mean it works. And sure enough, when I tried to run it, it ended in a segmentation fault:

So I asked Crush to run it and look at the error. It found the bug and made the necessary changes. It found a wrong struct and even caught a memory leak. It fixed both and now the program runs the way it should:

Like I said, it’s a goofy little chat program that uses Llama.cpp directly to load the Qwen3 model and open a chat for me to talk to. It’s just an exercise — a chat like this already exists, all you have to do is use Ollama. But I wanted to build one from scratch, low level, as an exercise for LLMs. Up to last year, no LLM I tested could finish this program properly. But now one finally did.

And as you can see, in the end I spent almost 8 bucks to refactor it, fix the bugs, and get this program working properly. Not cheap, but at least it wasn’t credits thrown out the window like it was a year ago. I haven’t tested it with local LLMs yet, to see if Crush can land on similar results.

But the fact that it can deal with a language as obscure as Zig has me genuinely excited to play with this more. The tooling and LLMs have finally hit a point where they’re actually practical to use. I’m not saying it solves everything, but compared to a year ago, it’s a real leap.

I’d recommend giving Crush a spin with other models too. I only played with Opus a little, but other models can give you different results depending on the kind of problem you’re trying to crack.

I’ll do only this one article about it and I don’t intend to cover more than the tip of the iceberg. The idea is to serve whoever is coming from other editors like Sublime Text or VS Code and can’t even start navigating or even quit Vim lol 🤣.

Initial Commands

As I said in the previous post about LazyVim, I’ll assume you already understand at least how to install support for your language with LazyExtras and already learned to version things using Mise.

Without even getting into LazyVim, the first thing to know is that it installs all the relevant configurations in the ~/.config/nvim directory. Normally you don’t need to touch anything there. Leave files like lazyvim.json alone. Notice that it does the same thing as any NPM out there: there’s a lazy-lock.json file that declares the version/commit of each installed plugin. LazyVim does something similar to an npm install. Just a curiosity so you know how it organizes itself.

If you need to customize something, it’s usually going to be in the ~/.config/nvim/lua/config directory. That’s where I added Mise support, for example:

~/.config/nvim
❯ cat lua/config/mise.lua
-- Prepend mise shims to PATH
vim.env.PATH = vim.env.HOME .. "/.local/share/mise/shims:" .. vim.env.PATH

They’ll always be scripts written in Lua. And you don’t even need to know Lua deeply. At a glance it’s a very simple language, not very different from Python or Javascript and any programmer should be able to read any snippet without any problem. Besides, in most cases you’ll be copying configurations you got from the documentation, wiki or ChatGPT itself, so you just need to know that things go in this location.

Understand that NeoVim has the concept of the “Leader” key, a key that precedes hotkeys for other commands (there’s also localleader which is backslash \). This is configurable but in LazyVim the Leader is the “Space” key. In a lot of documentation we’ll see people saying “press Leader-w”, which means Space+w and now you know what that means.

To open a file there are at least 3 different ways, 2 of them shown in the image above:

Space+E opens NeoTree, which is that sidebar on the left that looks like Windows Explorer. You can navigate with the keyboard or even with the mouse. Find your file and press “Enter” to open it, then “Space+E” again to hide the sidebar. If you want to know how to create a new file, a new subdirectory, rename things and so on, type ? (question mark) to see this help:

The third way is manually with the :e command followed by the file name in the local directory. It has autocomplete too, this is the fastest way, if you know what you’re looking for.

Whenever you want to cancel anything or close “floating windows” (pop-ups, dialog boxes). Just press “Esc”. Esc is fundamental in NeoVim.

Once a file is open, it sits in the Buffer. Think of Buffer as “Open Tabs” in your VS Code. To navigate through Buffers (like alt+tab between your already-opened files) it’s simple:

• ]+b for next “tab” (next Buffer)
• [+b previous Buffer
• Space+bd to “close the tab” (close the Buffer)
• Space+bo to stay where you are and close the other buffers

Open as many files as you want. If one of them is one of those huge logs you opened by accident, Space+bd to close it and done.

Speaking of closing, how do you exit NeoVim? There are several ways:

• Space+q
• :q
• :q!

The difference: the first is the custom way in LazyVim. The second is the standard way using the “commands” feature that always starts with “colon”. And the third is if you modified something in the file but want to cancel, exit without saving anything, hence the exclamation mark.

Normally I use :wq which means “write” and “quit”. So it first saves the changes to the file and then quits the program. It’s useful when I’m just quickly editing a config file.

Basic Navigation

Now I have a file open. How do I navigate through it? First, how do I go to the end of the file and then back to the beginning? This is something I use a lot, just type Shift+g to go to the end of the file and then gg to go back to the beginning. Simple as that.

Now let’s learn several commands at once:

• Type v. This starts the “visual mode” which, in practice, means starting to select from wherever your cursor is.
• Type j. Which is the equivalent of “arrow down” to go to the line below. You’ve probably heard that in Vim you navigate with “hjkl” which are, respectively, left, down, up, right.
• Type x. Which is the equivalent of “cut” and putting the content in the clipboard. Having done that, typing p gives you “paste”.
• Type u. Which is the most-used command: Undo or undoing the last modification.

All of this works in what’s called “command mode”, which is the default mode Vim opens every file in. In this mode you can’t type any text. As you can see, each letter by itself is a command, like “x” for cut or “p” for paste.

To type, you first need to press i (just the lowercase “i” letter), which then switches from command mode to “edit mode”. Now just type your text normally, like in any editor. When you want some command, just press ESC to go back to command mode. We’ll be doing this all the time, which is why a lot of people remap the “caps lock” key on the keyboard to be ESC so it’s easy to just tap with your left pinky.

Combining Commands

Still in command mode, how do we navigate through the file more easily?

Beyond the “hjkl” keys, we can navigate more easily using b for “previous word” or w for next word:

Command mode lets you combine commands, so we can do:

• dw to delete the next word
• db to delete the previous word
• d4w to delete the next 4 words
• d4j to delete the next 4 lines down

Primeagen’s tutorial has several exercises for this kind of navigation, I recommend practicing. In VS Code everyone is used to first grabbing the mouse, marking the block they want to delete visually, then pressing delete or backspace. In Vim, we look at where the cursor is, press ESC to be in command mode, and type the operation and the location. Test all the combinations you can imagine.

This is the paradigm shift that bothers the lazy. But once you’ve learned this, you’ll find it annoying to use an editor that forces you to use the mouse for basic things.

Now it gets more interesting: what if instead of deleting a word, I want to replace the word where my cursor is with another word?

In a normal editor, you’d mark it with the mouse (or use some combination like “ctrl+shift+arrow”), and type over it or delete the word.

In LazyVim there are plugins configured for more interesting things. In the video above see how I’m replacing words “in-place”. You do this with the ciw command.

• ciw deletes the entire word under the cursor and opens edit mode for you to type the replacement
• ce deletes from the cursor to the end of the word (preserves the beginning of the word) and also opens for you to type in its place
• Shift-c (capital C) deletes everything from your cursor to the end of the entire line and opens for you to type.

But that still doesn’t look thaaaat cool. What if you want to change only the first letter of several lines at the same time, for example, in the text of the video above, I want to change only the hyphen ("-") of each tag line?

I said before that pressing v in command mode starts visual mode and you can select from there. But there’s Ctrl+v which opens vertical block selection mode.

In this mode we use the “hjkl” keys normally, like j to go down, but instead of marking the next entire line, it marks only the character right below your cursor. Now I can delete with d and type Shift-i (capital “I”) to enter edit mode at the beginning of the block and replace with whatever I want.

LazyVim has plugins for comments, but this is another alternative if you want to add “//” or “#” at the beginning of several lines to comment out, for example. In this case, read about the ts-comments plugin for better options for commenting. To start a new comment block, type gco to add a comment below.

“Block mode” as I showed above, is one of the things I use the most in code.

But only that is very little. What if you want to replace ALL IDENTICAL WORDS in the text at once. In the example video above, I want to replace “domínio” with “DOMAIN” and “Cloudflare” with “AWS Amazon”, how do I do that? This is “Search and Replace” that exists in every editor and in Vim it’s very easy:

We type :%s/domínio/DOMAIN/.

If you’re a programmer you’ve probably seen this syntax before. It’s the REGEX MATCH syntax. Yes, you have to know Regex (and no, it’s not PCRE nor Unicode, it’s NeoVim’s own Regex dialect, but it’s similar).

As I said before, “colon” opens the command-typing box, "%s" starts “search with regex” and between the slashes “//” first goes what you’re looking for and then what you want to replace it with.

But that’s the way in pure NeoVim; in LazyVim, there’s the grug-far plugin and you activate it with the SPACE+sr command:

Now yes, more like VS Code, right? Use whichever you find easier.

Conclusion

As I said, this is only the tip of the tip of the iceberg, the bare minimum of the bare minimum to at least start editing simple config files without opening Nano or VS Code just for that.

Read the LazyVim documentation. Check out the keymaps to discover other commands. Pay attention to every letter you press in command mode, LazyVim shows the available options. For example, let’s say I pressed g (goto), it will show a help in the bottom-right corner:

This way you can always discover new commands or remember commands you rarely use. That’s why I recommend LazyVim, which comes well configured to help you. The plugin that provides this feature is which-key, in case you want the same thing in a NeoVim you configured from scratch.

There are several Cheatsheets out there with tables of important command combinations. Worth exploring.

And there’s more: LazyVim comes with dozens of plugins for formatting, linting, integrated LSP, integrated GIT, and much more. There’s no way I can document each one here. Each of them has its own documentation on the LazyVim.org plugins page.

Again, don’t forget to call :LazyExtras and install the optional plugins for your languages.

The questions I get the most, literally every single day, come in this format: “Akita, should I go to college?”, “Akita, what do you think I should study?” and variations of that.

Dude, I don’t know you, I will never know nor will I ever be interested in knowing who you are, what you aim for, your aspirations, ambitions, tastes, preferences. Nothing. Neither me nor ANYONE ELSE. Only you know what’s best for you. If you don’t know, go find out. That’s what LIVING means.

What you won’t admit is that you want someone you consider more important or relevant to approve your choice and tell you that you got it right.

Never expect that from me, I will never validate you.

I will always say: FIGURE IT OUT. That’s how I became who I am. I never followed anyone, I never asked anyone what I should do. I just went there and did it. Fell on my face, got up, tried again. That’s life.

Let me show you what actually BOTHERS me:

Let’s check the manual?

DHH took the trouble to write a manual. It has a section called “Security”. A quick Google search would have found it. Or this other gem:

How do you want to become a “DEVOPS” (who has to know EVERYTHING about Linux) starting like this? Already off to a bad start. Park your butt in the chair, roll up your sleeves, and test them one by one, and learn.

Linux for Beginners?

That said, watch my video. But since I’ve been talking a lot about Omarchy already, I’ll say that yes, this is what I use in my day to day and it’s the only one I’ll recommend for the near future (I may change my mind later). Having used distros ever since Linux was invented in the early 90s, I know there are dozens of distros and even I don’t have the patience to try them all.

Why Omarchy?

First, because it made the right choice of base distro: Arch Linux. I consider it the best distro out there today for two reasons: it has very little “bloat” (it doesn’t install a bunch of stuff you’ll never use, like Ubuntu, Fedora, Mint, Deepin, or any of those other “beginner-friendly” distros).

Second, Arch Linux has the AUR, which is a repository of user-made packages that has basically everything. You don’t need to go hunting for third-party repositories or install things manually. With a single command, yay, you install everything. There’s none of that apt-repository add nonsense or having to make install or anything like that. The AUR manages all of it for you.

Third, it installs Hyprland (which I was already using and liked), with very good configs, and a very good package selection. Everything I would install manually myself. So it’s a thousand times easier to get what would take me much more work to do on my own. Check my series of posts about Omarchy to see those options.

Linux for Beginners?

Beginner at what?

I hate this question. If you’re really an amateur user, not a programmer, maybe you’re an accountant, maybe you’re just a teenage gamer. The first question I ask is: why do you want to use Linux?

Let’s say it’s because you heard it’s more secure (and it actually is). Then it doesn’t matter, any distro will do. Install Ubuntu, install Manjaro, install Garuda. It makes no difference, because you’ll never deal with anything under the hood. You’ll open Chrome, open Steam, and that’s it. The rest is going to be web apps.

Let’s say it’s just for gaming, then install Bazzite on your mini-PC or handheld. Or just install your games on a separate Windows box just for gaming like I did. Whatever.

Or just stick with Windows or macOS. If you’re a total amateur, you’re probably going to use the same weak password for everything, and click on WhatsApp links without checking who they’re from. It literally makes no difference which OS you use. No security from any OS will protect you from your bad habits and ignorance.

If you’re a beginner at programming or tech, then I have no mercy: learn Linux properly. You want to be a professional, be a professional, learn the right way: learn to have 100% control over your own machine. There’s no step-by-step or tutorial for that. It’s something you’re going to do continuously for the rest of your life. I’ve been in this field for over 30 years and I still learn new things every day.

Hardware

The BIGGEST problem anyone is going to face, with ANY distro, is going to be hardware support. And that’s why you shouldn’t just follow what someone recommends to you:

Nobody has the same PC as you.

What’s your notebook? A Lenovo? A Dell? A Positivo? From what year? Which model?

Everything varies: which Wi-Fi and Bluetooth device? Which graphics card? Which firmware is running? With which power profile support? Do you need FIDO2 devices for things like a fingerprint reader? Hardware keys? Does your machine have TPU? Will you need Secure Boot?

I don’t know. You are the one who has to know.

A practical example, I have an Asus Zephyrus G14 notebook that I use with Windows because it only lives in my workshop to run Bambu Studio to control my X1C 3D Printer. I haven’t gotten around to installing Omarchy on it, but let’s say I wanted to. Would it work?

Fortunately there’s a page on the ArchWiki dedicated to this model. It looks like everything works “out-of-the-box”. But if it were the previous year’s version I’d have to check extra items. There are Wi-Fi issues, for example.

Each different machine will have different problems.

Live Env and Ventoy

“So what do I do, you [censored]?”

That’s why pretty much every good distro offers an installation ISO that comes with a live environment. I’ve seen a lot of people on Windows who have trouble knowing what to do with an ISO. It’s very simple.

The easiest program to use is Balena Etcher. You download the file with the .iso extension, whether from Ubuntu, Mint, Elementary, etc (ALWAYS FROM THE OFFICIAL SITE!!!!). Open Balena and there are only 2 steps: select the image (the ISO file), select the drive (your pen drive, careful not to pick your HD!), and done.

Now just boot your PC and go into the BIOS to select the pen drive to boot from, or use a key like F12 (varies from BIOS to BIOS) to have UEFI select your pen drive.

That will boot the Live Environment straight from the pen drive.

Most distros start by opening a “Welcome” screen similar to the one above. This installer app is called Calamares and everyone with a graphical installer uses it. That’s why it looks similar across all of them. It’s the same step-by-step. If you’ve installed one distro, you’ve installed them all.

But you don’t have to follow Calamares. You can close it. And now you’re already in the graphical environment of the distro you chose to install. USE IT. Try to configure your Wi-Fi, try to pair your Bluetooth headphones or mouse, try to turn on the webcam, put in a micro-SD card and see if it shows up. Try to browse the web and feel the performance.

If at this point you can do all the basic things, it means the chances that everything will work are high. If at this point you already start having problems, like not being able to connect to your Wi-Fi, that distro is probably going to give you a headache. Start by going to Google and see if somebody has already solved the problem for your notebook or PC model, before continuing with Calamares.

Let’s say you decided to take the day to test several distros to see which one runs best on your machine. Great call, but you’ve probably figured out that it’s going to be a huge pain to have several pen drives, one for each distro. Or having to keep going back to Windows and using Balena to overwrite a new distro on your only pen drive.

You don’t need to do that.

You just have to first download and install Ventoy on your pen drive. Check the documentation on their site, but it’s ridiculously simple.

After installing it on your pen drive, now just copy ALL THE ISOS you want at once onto the pen drive. When you boot from it, you’ll enter the Ventoy menu, which lets you pick any of the ISOs you copied there. If you didn’t like the current distro, just reboot into Ventoy again and pick another ISO. It’s that simple.

Distrobox

Let’s say you’re a programmer, or a devops, or any tech professional. Your concern isn’t so much the graphical interface (which you can test with Ventoy), but whether the OS infrastructure is going to work with your development requirements.

Let’s say you use Fedora. I wonder, if I go to Mint, will it have the K8s packages the way I need them? Does it support the Java version I use? If I build a .deb package on my Fedora, will it install properly on Ubuntu?

Having to dual boot or install a VM feels too heavy, too much work, just to test 2 command lines, for example.

That’s what Distrobox is for. It needs Docker or Podman already installed on your machine. But after that you just do:

distrobox create -n debian-test --init --image debian:latest --additional-packages "build-essential"

Once the box is created you just enter it:

distrobox enter debian-test

Done, you’re inside Debian, super fast. Since it’s a Docker container, you can map directories on your local machine into the container, so everything stays integrated. And the most important thing: it loads super fast, because it’s just a Docker container.

The Quick Start guide explains all of that and has this video with a tour to demonstrate how it works:

Conclusion

Seriously. With Distrobox there’s no excuse not to test another distro in 2 minutes. Stop wasting time sending DMs to “influencers”. See for yourself! If you’re not capable of doing that, maybe you’re in the wrong profession.

Every “dev” or tech professional, whether devops, cybersec, data analyst, blah blah blah, whatever the trendy title is these days, MUST have control over their own machine. MUST know how to deal with security (that’s why I wrote posts about Vaultwarden, Cloudflare, SSH, etc).

IT’S YOUR RESPONSIBILITY!

Don’t outsource your responsibility to others. Don’t look for validation. Be promiscuous and test whichever distros you want, and do whatever you want on those distros: they are yours! There’s no such thing as a “distro for beginners”, “distro for devs”, “distro for devops”. A distro is a distro. Linux is Linux. It’s all the same, what varies is your skill. If you don’t have the skill: earn it! Learn! Break your head over it! Pull all-nighters tuning configs! Read the official documentation! Don’t waste time thinking you’re going to learn on social media. You won’t.

I’ve been using Linux since the early 90s and I don’t stick with Slackware just because it was the first one I learned and I feel a need to validate my first choice. I use whichever ones I want. Right now, I had my own Hyprland setup, and I decided I wanted to learn and use Omarchy. I spent the week banging my head against it, and wrote half a dozen blog posts. And now I’ve learned. I know Omarchy: one more for the collection.

Just head to the official site and click “ISO” to download. Use Rufus or Balena Etcher on Windows (or Caligula on Linux) to burn it to a USB stick and boot from it. From there, follow the step-by-step and in less than 5 minutes you’ll have everything installed.

As I explained in the first article, I did it differently: I installed pure Arch Linux, Desktop style, with Hyprland + SDDM. Then I installed Omarchy using the manual command line:

curl -fsSL https://omarchy.org/install | bash

You can do it either way. The second gives you more control, but after gaining more experience and reading the install scripts, I recommend downloading the Omarchy ISO itself. It really is easier.

Limine vs Grub

The reason I went the manual route was because I wasn’t sure if Omarchy supported BTRFS rollback via snapshots. I had heard that the Limine bootloader didn’t support that. But I was wrong: Omarchy installs Limine with Snapper support (which is similar to Timeshift, the one I usually use). Read ArchWiki section 6.2. So this should be a superior option to my GRUB+Timeshift setup that I talked about in the first article.

Since I already installed it manually, I’ll keep things as they are because in practice it’s the same thing. But if I were installing again, I’d go with Limine+Snapper just to try it out.

This means there’s support for snapshotting your entire filesystem with BTRFS before a package update, and if something goes wrong, you can reboot and roll back to a previous snapshot. That gives you peace of mind so you don’t lose a whole day trying to fix something if an important system package ships buggy or corrupted. That’s the most important feature.

SDDM vs UWSM

Another thing I noticed was the login manager. On pure Arch, it installs Hyprland by default with SDDM, the same one KDE uses.

Omarchy uses UWSM, which auto-logs you in with your user at boot. So there’s no login screen, it just opens Hyprland automatically.

“But isn’t that insecure??”

No, because the Omarchy ISO pre-configures your SSD with LUKS, below the filesystem.

For those who don’t know, LUKS stands for Linux Unified Key Setup, which provides full-disk encryption. Its advantage over Windows BitLocker is that it’s filesystem-agnostic. In other words, it works with BTRFS or EXT4 or any other, because in the boot sequence, after the bootloader (whether Limine or Grub), it loads before the filesystem. It’s a block-level encryptor.

So when you boot your system, it first asks for the passphrase to decrypt your disk. Then the filesystem opens and the Linux kernel can continue the normal boot with the disk unlocked. So you are always forced to type your strong user passphrase at boot to decrypt the disk.

That’s why typing a password again at a login manager would be redundant and unnecessary, and I imagine that’s why they chose UWSM instead of SDDM.

Especially on a laptop, or in situations where other people live with you, it’s essential to make sure your disk is encrypted, no matter the operating system. Say you go out to work or travel and your laptop gets stolen. Without encryption, it’s game over, regardless of whether you have a login manager. It doesn’t protect your data. Anyone can just pull the SSD from your laptop, plug it into another computer, and boom, they can copy everything by booting as root.

With encryption, without the passphrase to decrypt it, accessing your data is impossible. Truly impossible, because on any modern computer from the last 15 years, the CPU ships with hardware-accelerated instructions for AES 256 encryption.

Getting a bit more nerdy: the decryption key is not your passphrase. During the install process, a new stronger and more secure key is generated using a key derivation process (KDF - Key Derivation Function), nowadays using Argon2id, previously PBKDF2. I explain this in this video:

So when you type your passphrase, what actually happens is it decrypts that secure key, and it’s with that secure key that your disk is encrypted. That’s why you can’t brute-force decrypt your data.

Plus, AES 256 is one of those encryption algorithms that’s quantum resistant. Even if a quantum computer were possible (it isn’t), not even that could decrypt your disk. That’s the level of security.

“But won’t it be slower?”

No. It’s practically imperceptible, because AES, as I said, is hardware-accelerated by your CPU and doesn’t depend on operating system software. In day-to-day use, you’ll barely notice. Performance is practically the same. There’s no reason not to enable encryption, especially on a laptop.

In my personal case, where I installed it on a desktop PC that I control myself on a secure local network, because I know how to implement network security, it’s not an issue. My most important data lives on my NAS (which is encrypted), in backups (which are encrypted). I don’t have sensitive data on this PC, and the little I do have sits in files encrypted by Veracrypt on a separate sub-volume.

That’s why I didn’t enable LUKS on my PC. And I kept the SDDM that pure Arch installed. Except it’s REALLY ugly by default, so here’s a small tip: install either the sddm-sugar-dark theme or dark-arch-sddm. I prefer the second one because it’s more minimalist and looks like this:

I customized it and swapped the Arch logo for the Omarchy one, and that was it.

Conclusion

I’ll say it again: only after installing manually did I see how Omarchy installs things, and today I prefer the Omarchy way. If I were installing from scratch, I’d use the Omarchy ISO and keep it with Limine+Snapper and Hyprland+UWSM, with snapshot rollback support, full disk encryption, and automatic login into Hyprland.

You can tell the people behind Omarchy have experience and have already picked components that make sense to work together in the most convenient and secure way possible. I was worried that, being a new distro, maybe they hadn’t given this much thought, but I’m happy to say I was wrong.

Use the official Omarchy ISO.

More important: having a strong, random, exclusive and different password for EACH site, app or service you use. Never, ever, reuse a password. Why? Because every day one of these sites gets breached and passwords get leaked. If you search for yourself on Have I Been Pwned you’ll surely find accounts of yours that have already leaked. And if you share that same password across 10 other sites, someone has probably already gotten into your account by now.

Watch my video about security:

Being too lazy to use a password manager is just a dumb excuse from lazy people. And a programmer has zero right to use that excuse.

Omarchy 1Password

Anyone who has followed DHH since the early days when Macs were the best platform for developers remembers he was always a fan of 1Password, one of the apps that worked best on iPhones.

I migrated back to Android and Linux many years ago, in 2015. I used 1Password, but on Android the app was horrendous, ugly, and painful to use. That’s why I gave up on it and kept bouncing between several other apps. Google Authenticator, Lastpass (which I don’t recommend).

I know there are several other open source ones that people prefer, but I ended up settling on Bitwarden, which is BEAUTIFUL both on Android and as a browser extension. On top of that, it has open components and allows self-hosting.

More than that, it doesn’t make it hard to export all the data from your account and import it somewhere else. Unlike apps like Twilio Authy, which locks you out of everything and is why I stopped using it.

Bitwarden has a secure random password generator, supports 2FA TOTP, lets you store secure notes (mini texts) and a lot more. The apps integrate with phone biometrics, so it’s very convenient to use.

I still keep my Bitwarden inside Samsung’s Secure Vault, the Samsung Knox Vault. So there are 2 layers of security. And when I need to walk around somewhere suspicious, I don’t take my main phone, only a burner phone with nothing important logged in.

Look how beautiful it is. I like it and I’ve been using it for a few years now. My passwords range from 21 to 42 random characters, a different one for each site. I’ve updated all the passwords for everything more than once in the past few years, and all accounts have 2FA/TOTP registered inside Bitwarden too, which is how I managed to drop Authy.

Installing VaultWarden Self-Hosted

More important, the time has come to host my own Bitwarden server, vaultwarden, which is an open source alternative, code open on GitHub, so you can poke around yourself to learn or even contribute to it. Again, I bring everything up with Docker Compose on my Home Server, so I just needed to add this snippet to my file:

  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      DOMAIN: "https://bitwarden.fabioakita.dev"
      SIGNUPS_ALLOWED: "false"          # set to true only to create first user
      WEBSOCKET_ENABLED: "true"
      ADMIN_TOKEN: "iA...Q9"  # for /admin
      # SMTP (recommended)
      SMTP_HOST: "smtp.gmail.com"
      SMTP_PORT: "587"
      SMTP_SECURITY: "starttls"
      SMTP_USERNAME: "boss@akitaonrails.com"
      SMTP_PASSWORD: "xxx"
      SMTP_FROM: "boss@akitaonrails.com"
    volumes:
      - /home/akitaonrails/vaultwarden/data:/data
    ports:
      - "9999:80"
    healthcheck:
      test: ["CMD", "wget", "-q", "-O", "-", "http://localhost/health"]
      interval: 30s
      timeout: 5s
      retries: 5

Important:

• Create a long, random ADMIN_TOKEN. Use Bitwarden itself for that, keep it secret.
• Set SIGNUPS_ALLOWED to true only once, log into the local site and create your new account. Then change it back to false in the file and restart the container. That way nobody else will be able to create any new accounts.
• It’s recommended to configure a GMAIL SMTP to send notification emails. For that, you need to create an app password in Google.

To create a password exclusively for vaultwarden, go to Google App Passwords and generate a new exclusive secret password:

It will only show you that password once. Copy and paste it straight into the docker compose yaml. With email properly configured, every time someone logs in, it sends an email notification. That’s good to make sure nobody shady is messing with your server:

Now I just need to bring up the container:

docker compose -f utils-docker-compose.yml up -d

Routing the Cloudflared tunnel

As I already showed in the Cloudflared post now I want to be able to access it remotely, via secure tunnel, using a public URL like https://bitwarden.fabioakita.dev. To do that we have to edit that /etc/cloudflared/config.yml file and add this to the end of it:

  - hostname: bitwarden.fabioakita.dev
    service: http://192.168.0.200:9999
    originRequest:
      httpHostHeader: bitwarden.fabioakita.dev
      http2Origin: true
  - service: http_status:404

Then we have to restart the service and also add the route manually:

sudo cloudflared tunnel route dns homelab bitwarden.fabioakita.dev
sudo systemctl restart cloudflared

And done! It might take up to 5 minutes for DNS to sync and all that, but then just hop into your browser and you’ll see this:

If that SIGNUPS_ALLOWED is true there will also be a link to “Create new account”. In my case I already did that and turned it off, so there’s only login.

Importing your Data

Before moving on, let’s open the Bitwarden extension - which is still logged into the cloud version at bitwarden.com - and export all my data:

Just authenticate, then on the bottom icon bar you’ll find “Settings”, then “Vault Options” and finally “Export vault”. Leave the default JSON format (it will be an encrypted JSON) and download that file somewhere safe.

Now we can log back into our self-hosted version at https://bitwarden.fabioakita.dev and go through the same menu, but choose “Import”:

And done! Now my self-hosted version is identical to the cloud version I had been using until now.

Logging into the new self-hosted server

Now just log out of both the mobile App and the browser extension. Then on the login screen you’ll see the following option:

On the web extension the window doesn’t let you see that option, use the mouse scroll and scroll to the bottom of the window and you’ll see that small option. Choose “self-hosted” and a window will open to type the URL https://bitwarden.fabioakita.dev and done!

From here on the usage is exactly the same as before. The interface is the same, the options are the same. Configure biometrics, PIN, lock timeout and everything else the way you like it.

Do the same on the mobile app and done!

On this new account we created on the self-hosted server, don’t forget to enable 2FA too, which is the “Authenticator App” option under “Settings/Security”:

For all other accounts, we can register the 2FA inside Bitwarden. But for the master account of Bitwarden/Vaultwarden itself, we need to use a second app just for that.

I don’t know if it’s the best, but I’ve been enjoying using Aegis Authenticator on my Android:

It’s open source, the code is on GitHub, so it seems minimally trustworthy. I also keep it inside the Samsung Knox Vault. I only need it when I have to re-login into Bitwarden/Vaultwarden. To log into Google, Steam or any other account, the 2FA for each one lives inside Vaultwarden itself:

Conclusion

Now all that’s left is to log in with my old account at bitwarden.com, which is the “official” cloud version, and delete my account, to make sure nobody else has access.

And there, PERMANENTLY DELETED! My accounts no longer exist on some random server I don’t control, even if they were encrypted.

I’m pretty happy with this solution. Now my Vaultwarden is in a container, the home server data gets automatic backups to my NAS, everything is encrypted and access only happens via Cloudflare’s secure tunnel. The risk is very low and nobody has a chance of getting access to my data, because it’s no longer in the “cloud”.

My data is mine alone.

Every programmer needs to know how to manage their SSH keys. At the very least because every GitHub account requires one.

Every time you run git push to one of your repositories, it will ask for the passphrase of that key:

❯ git push origin master
Enter passphrase for key '/home/akitaonrails/.ssh/id_ed25519':

What does this mean?

SSH is a set of tools, both client and server, to create a secure, encrypted connection over the internet. It has several uses and I explained how to do SSH Proxy in this video:

The whole process starts by installing SSH on your machine, and on Omarchy/ArchLinux you just do this:

yay -S openssh

If you’ve never created a key pair (yes, it’s a pair), just run this command:

ssh-keygen -t ed25519 -a 100 -C "your_email@example.com" -f ~/.ssh/id_ed25519

ED25519 is a public-key algorithm, meaning it creates a pair of keys: a private one that must never leave your machine, and a public one that can be exposed on the open internet (the one you register on your GitHub account, for example). I explained public keys in this other video:

ED25519 is a more modern algorithm than the old RSA (which I think is still the default in ssh-keygen if you don’t make an explicit choice — it’s still secure, but elliptic curve is even more secure).

It’s based on elliptic curve cryptography (ECC). For the paranoid, yes, it’s even considered quantum-resistant, meaning that even if a quantum computer became feasible, it wouldn’t be able to break an ED25519 key.

Two files will be created after running ssh-keygen:

.rw-------   464 akitaonrails 14 Nov  2017  󰌆 id_ed25519
.rw-r--r--   108 akitaonrails 14 Nov  2017  󰷖 id_ed25519.pub

Pay attention to the permissions of these files. It’s important that the ~/.ssh directory and the private key files inside it always have 600 permission, meaning read-write only for your user, and no permission for groups or any other user. Nobody else should even be able to list the directory.

The *.pub files, which are the public keys, have 644 permission, which is read-write for you and read-only for other groups and users. As I said, the public key can be exposed publicly. Mine, for example, is this one:

❯ cat id_ed25519.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEWG5bHK02sMqilMiYu67xqdaBsk3TtCQ564bcJibDiO akitaonrails@Miner42.local

ED25519 has another advantage: it’s orders of magnitude more secure than RSA and still provides a much shorter public key, which makes copy-pasting it around much easier.

A private key has an envelope in this format:

-----BEGIN RSA PRIVATE KEY-----
MIIEpA ...
...
XfI0X....
...
... nQ5w==
-----END RSA PRIVATE KEY-----

Repeating: THIS FILE MUST NEVER LEAVE YOUR MACHINE. Never leave it lying around on a pen drive, for example. And always make sure the permission is chmod 600 as I explained.

Yubikey 5

The most secure form, one that many companies even enforce, is the use of a HARDWARE-KEY. The private key is never written to your local machine; instead, it’s generated inside secure hardware from which it’s impossible to read that private key. Examples are Yubikey or FIDO2.

About Yubikey, be careful, you want the newer Yubikey Series 5 models:

If you have the old one — usually the blue one — it’s the Security Key v4.3.1 and only supports U2F (FIDO U2F) but not FIDO2/WebAuthn, and no PIV/OpenPGP/OTP applets. To be sure, install these packages on your Arch:

sudo pacman -S yubikey-manager libfido2

Then check with this command:

❯ ykman info
WARNING: PC/SC not available. Smart card (CCID) protocols will not function.
Device type: FIDO U2F Security Key
Firmware version: 4.3.1
Enabled USB interfaces: FIDO
 
Applications
Yubico OTP   Not available
FIDO U2F     Enabled
FIDO2        Not available
OATH         Not available
PIV          Not available
OpenPGP      Not available
YubiHSM Auth Not available

See how it finds the Yubikey connected via USB but everything shows up as “Not available”. That’s the wrong model — this Yubikey only works as Two-Factor Authentication on websites. It’s not useless, but for our case it doesn’t work because:

• it has no PIV applet, so it can’t act as a smartcard
• it has no OpenPGP applet, so it can’t store GPG or SSH private keys
• it has no FIDO2, so you can’t run ssh-keygen -t ed25519-sk.

A new one, on Mercado Livre today, costs around BRL 800. If you’re going to use it for work per the company’s security policy, they should provide it or reimburse you. But even for personal use, I recommend investing a bit more in security.

With a Yubikey 5 in hand, the procedure is as follows. Start by making sure you have the packages on your machine:

sudo pacman -S yubikey-manager yubico-piv-tool opensc

Initialize the PIV application by changing the PIN:

ykman piv reset                # wipes PIV, careful
ykman piv access change-pin    # default PIN is 123456
ykman piv access change-puk    # default PUK is 12345678

Generate a new key pair inside the Yubikey:

ykman piv keys generate 9a pubkey.pem

Extract only the public key to your local ~/.ssh directory:

ssh-keygen -D /usr/lib/opensc-pkcs11.so -e > ~/.ssh/id_yubikey.pub

The contents of that ~/.ssh/id_yubikey.pub file is what you’ll add to the ~/.ssh/authorized_keys file on the remote server you want to connect to via SSH. To open an SSH connection to it, plug the Yubikey into the USB port and run:

ssh -I /usr/lib/opensc-pkcs11.so your-user@server

It will ask for your PIN and authorize the connection. If you don’t want to keep typing that -I every time, just edit ~/.ssh/config with this:

# ~/.ssh/config
Host server
  PKCS11Provider /usr/lib/opensc-pkcs11.so
  User your-user

HOWEVER

This procedure uses the key generator inside the Yubikey, which only supports RSA (1024–2048) or ECC (P-256, P-384). If you want to generate an ED25519 key, the flow is different, we have to run it like this:

ssh-keygen -t ed25519-sk -a 100 -C "you@example.com" -f ~/.ssh/id_ed25519_sk

The id_ed25519_sk file that it generates on your local machine is not the private key, it’s just a “stub” that points to your Yubikey. So the key stays stored in the hardware and never passes through your machine.

To add your public key to the remote server, just manually append it to the ~/.ssh/authorized_keys file as we did before, or run this command to log in with your password and it will add the public key for you:

ssh-copy-id -i ~/.ssh/id_ed25519_sk.pub your-user@server

To use your key to log in now, just do:

ssh -i ~/.ssh/id_ed25519_sk your-user@server

This only works because the Yubikey 5 has FIDO2 support. The old ones don’t, which is why you can’t do this with them.

Oh, and on your home server or any other server, AFTER adding your key to authorized_keys, I recommend DISABLING the password login option (so that no bot keeps trying to brute-force its way in). On the server, edit:

# /etc/ssh/sshd_config
PasswordAuthentication no
ChallengeResponseAuthentication no
KbdInteractiveAuthentication no
UsePAM no
...
PubkeyAuthentication yes

In other words, turn off all login options and leave only public-key. Now just restart the service:

sudo systemctl restart sshd

SSH-Agent

To be clear: the most secure way to manage private keys is via an external security hardware device, in this case the Yubikey 5.

But it’s not mandatory. If you have a dedicated PC for work, with your Arch Linux or Omarchy installed, and you don’t keep installing shady software — like pirated games — nor keep browsing sketchy sites and clicking on random links (malware risk), keeping your keys locally on your machine isn’t entirely bad. I’ve been using it this way for years and have never had problems — because I’m paranoid about the security of my machine.

Remember, one of the most common types of malware are the ones that upload your files, or encrypt your files and then demand a cryptocurrency ransom to return them. The good old RANSOMWARE:

This exists not only on Windows but on Mac and Linux as well. And web browsers are the main vector, especially phishing emails with malicious links that you click on, or links that come through Discord, Telegram, or WhatsApp channels.

NEVER CLICK ON LINKS. Copy the link, paste it into a terminal, and see what kind of link it is. If it’s not an obviously official domain like “whatspp.com” or “google.com”, don’t go forward.

With all that said. Let’s say you created your keys locally and registered them in your server’s authorized_keys and in your GitHub account. Now, every time you run ssh or git push, it will ask you to type your passphrase (which, if you’re not silly, you made VERY LONG).

This is extremely inconvenient to keep typing all the time. That’s why SSH has a feature to help: caching your authentication for a fixed period using ssh-agent.

Start by creating this user service for systemd:

# ~/.config/systemd/user/ssh-agent.service
[Unit]
Description=SSH Agent

[Service]
Type=simple
Environment=SSH_AUTH_SOCK=%t/ssh-agent.socket
ExecStart=/usr/bin/ssh-agent -D -a $SSH_AUTH_SOCK

[Install]
WantedBy=default.target

Enable it with your user privileges (no sudo):

systemctl --user enable --now ssh-agent.service

Expose it in your .bashrc or .zshrc:

# ~/.zshenv (or ~/.profile)
export SSH_AUTH_SOCK="$XDG_RUNTIME_DIR/ssh-agent.socket"

Now, every time you log into your system and start working, add your work key:

ssh-add -t 30m ~/.ssh/id_ed25519

It will ask for your passphrase once, but for 30 minutes (which is what the -t 30m option does), you won’t need to re-type the passphrase and can comfortably keep accessing ssh or doing git push.

If you want to remove the cache from the agent before the timeout, you can do:

ssh-add -d ~/.ssh/id_ed25519

If your work routine involves using ssh, instead of manually running ssh-add you can add the following configuration to your ~/.ssh/config:

# ~/.ssh/config
Host *
  AddKeysToAgent yes
  IdentitiesOnly yes
  IdentityFile ~/.ssh/id_ed25519

And every time you open the terminal, it will ask you to type your passphrase. And that will last while your session is logged in.

Finally, the filename in the examples is always id_ed25519, but that has no relevance whatsoever — you can rename it however you want and even create multiple keys to use for separate services if you want to be extra secure. Just generate keys like heroku_id_ed25519 or google_cloud_id_ed25519 and so on. Create as many keys as you want or think necessary. This applies both to local keys and to keys on the Yubikey 5.

I think these are the aspects I consider most important to know about SSH keys. Did I forget anything else important? Feel free to share more tips in the comments below.

The more “modern” apps are basically canned web front-ends wrapped inside Electron. The problem? They’re HEAVY and chew through RAM like there’s no tomorrow. Start opening Discord, Spotify, and a handful of these and see if your old 8GB notebook can keep up.

But, especially if you’re a programmer, you should pay more attention to TUIs. At first, some will turn their nose up: “terminal apps are ugly, black and white, boxy, blegh”

Twenty years ago, they’d be right. But it’s 2025 and today’s terminals support 256 colors (more than enough), various resolutions and, most importantly, fonts, in particular Nerd Fonts, fonts that have icons inside. That’s how a tool like eza works, which I use every day aliased to ls and looks like this:

And there’s more: there are modern libraries, for several languages, like BubbleTea, a framework for building TUIs. Check their GitHub but they have the tools to make interfaces like this:

And if you just want a simple widget to complement a Bash script you’re writing, they have Gum, which lets you do interfaces like this:

And to use it just install the binary and put lines like this in your script:

# Gum examples
gum choose "fix" "feat" "docs" "style" "refactor" "test" "chore" "revert"

gum input --placeholder "scope"

gum confirm "Commit changes?" && git commit -m "$SUMMARY" -m "$DESCRIPTION"

And if you use Omarchy they ship an extra feature for TUIs. Just hit “SUPER+ALT+SPACE” to bring up the main menu, then pick “INSTALL” and “TUI”. Or simply open the terminal and run:

$OMARCHY_PATH/bin/omarchy-tui-install

It’ll ask for a name for the App and the command line to run. You can also pick icons at Dashboard Icons. Once registered that way, when you call the Rofi launcher with “SUPER+SPACE” and type “lazy”, LazyDocker shows up as if it were a regular app:

And since Hyprland has no title bar or anything, TUI apps or web apps (there’s omarchy-webapp-install too) open as if they were “native” apps:

Read the TUIs and Web-Apps sections in the Omarchy manual.

Obviously, this is only for those who prefer the feeling of running “Apps”, but it’s the same thing as opening a Terminal and simply typing lazydocker on the command line - which is my preference. What these Omarchy scripts do is create a .desktop file at ~/.local/share/applications. The LazyDocker.desktop example generates this:

❯ cat ~/.local/share/applications/LazyDocker.desktop
[Desktop Entry]
Version=1.0
Name=LazyDocker
Comment=LazyDocker
Exec=alacritty --class TUI.tile -e lazydocker
Terminal=false
Type=Application
Icon=/home/akitaonrails/.local/share/applications/icons/LazyDocker.png
StartupNotify=true

If you don’t want this launcher anymore, just delete the file or call the $OMARCHY_PATH/bin/omarchy-tui-remove script.

This feature is particularly interesting in Hyprland because, unlike GNOME or KDE, the window has no top title bar, so it doesn’t give away that you’re just opening a terminal or web browser. That’s how it ships pre-configured with things like ChatGPT or Grok looking like “native” apps, when they’re really just Chromium windows opening each one’s URLs directly:

Some TUIs I like

In my opinion, since there are no pretty GUI apps for Linux, it’s really better to use the respective web apps like Canva or ChatGPT that way, but more interesting is having actual TUIs. As I said, these days it’s not hard to make pretty TUIs. For a programmer, the advantage is that you don’t have to deal with front-end frameworks first, and second, you don’t have to deploy anywhere on the internet.

TUIs are lightweight, use few machine resources, they’re easy for any programmer to build, and you can have a home server or a server in some cloud, SSH in, and access the TUI, without having to deal with X11 or RDP or anything heavier just to get a GUI.

Some TUIs are obvious: in the previous post I already talked about LazyVim and how it’s a text editor as competent and complete as VS Code, using only a fraction of the machine’s resources. Everyone should know tools like HTOP or BTOP. Plus LazyGit or LazyDocker. All of these already come in Omarchy.

But there’s much more, for example, dblab which is a TUI database client for MySQL or Postgres:

Another similar one is LazySQL, written in Go:

Or if you prefer tools written in Rust, there’s rainfrog:

For those who can’t use CURL on the command line and prefer Postman to call and explore APIs, there’s the TUI Posting that does the same thing:

For those of us who run lots of Docker containers, I already mentioned LazyDocker, but there’s also oxker:

If you use Discord, there’s discordo:

Anyone who does a lot of Linux ricing has had to burn ISOs to USB sticks dozens of times; for that there’s dd on the command line, but there’s a cooler TUI called Caligula:

If your SSD is filling up and you have no idea where the hell all that space is going, there are several tools to analyze and show you. One of them is gdu:

And the last one I thought was cool out of nostalgia is sc-im; think Excel as a TUI or - for those of us who came from the 80s - think Lotus 1-2-3 but with Vim keybindings:

Why open Google Spreadsheets just to make a Todo list if you can do it in the Terminal?? TUIs are exceptional!

If you want to discover more TUIs check out awesome-tuis on GitHub:

Again: zero need for heavy web front-ends for simple things. Nothing beats the simplicity of a command line. And with libraries like BubbleTea or Gum, it’s now very easy for anyone to make a pretty app. And with Hyprland and Omarchy, everything stays integrated side-by-side with any other GUI app.

Getting a bit philosophical, the history of GUIs starts with skeuomorphic graphical interfaces that try to imitate objects from our daily life, particularly looking pseudo-3D, like Windows 95 was. The 2000s arrived and they started migrating to flat or minimalist interfaces, completely removing the skeuomorphism, making everything flat. That came mainly from Windows 8’s Metro. And I think that’s converging toward a more TUI-like style, coming full circle, going back to how it was on 70s terminals. Personally, I find that fascinating.

But you don’t need to use these menus. Let me explain.

On a regular Arch Linux or Ubuntu, an amateur would install ruby or python doing something like this:

# arch
yay -S ruby python3
# ubuntu
apt install ruby python3

This is the WRONG way.

These commands will install the latest version of each language, and every time you update the system with yay -Syu or apt upgrade, they’ll pull in even newer versions.

The thing is, if you develop real projects, you don’t want the versions to change.

The version deployed on the cloud server and the version on your local machine MUST BE THE SAME.

If you’re using Ruby v3.0.7 and Node.js 22.19.0, you can’t be held hostage to the fact that when you update your system, out of nowhere Ruby 3.4.5 and Node 24.7.0 show up. Everything will start breaking and you’ll be super confused without knowing why. This is the most basic mistake a junior developer makes.

To avoid this, every project you’re working on MUST BE LOCKED TO FIXED VERSIONS.

The easiest way to do this in 2025 is using MISE. As I said, it already comes installed and activated on Omarchy, but if you’re using another distro just install Mise manually:

yay -S mise

# .bashrc
eval $(mise activate bash)

Adapt this for ZSH, Fish or whatever shell you’re using, read the documentation

Now navigate to your project directory, for example:

cd ~/Projects/AkitaOnRails.com

And lock the versions:

mise use ruby@3.2.3
mise use node@14.21.3

This will create a .tool-versions file that you should add to your repository’s git:

❯ cat .tool-versions
ruby 3.2.3
nodejs 14.21.3

❯ git add .tool-versions

And done, every time you cd into the directory, Mise will activate exactly the right version for that project. Look:

AkitaOnRails.com [ master][$!?⇡][ v24.7.0][💎 v3.2.3]
❯ ruby -v
ruby 3.2.3 (2024-01-18 revision 52bb2ac0a6) [x86_64-linux]

AkitaOnRails.com [ master][$!?⇡][ v24.7.0][💎 v3.2.3]
❯ which ruby
/home/akitaonrails/.local/share/mise/installs/ruby/3.2.3/bin/ruby

Notice that, if you’re using the Starship prompt I explained in the previous post, with a preset like Pure Prompt, it shows the version of each language in the prompt so it’s easy to see if you’re on the wrong version.

In this case, if you read carefully, you’ve probably already noticed that YES, I’M ON THE WRONG VERSION of Node.js. Look how the prompt says I’m using Node 24.7.0 but the .tool-versions file asks for 14.21.3.

The reason it’s “missing” is because this machine was recently installed, but the project is old.

So let’s check:

AkitaOnRails.com [ master][$!?⇡][ v24.7.0][💎 v3.2.3]
❯ mise list
Tool    Version            Source                                              Requested
go      1.25.0             ~/.config/mise/config.toml                          latest
node    14.21.3 (missing)  /mnt/data/Projects/AkitaOnRails.com/.tool-versions  14.21.3
node    22.18.0
python  3.13.7
ruby    3.2.3              /mnt/data/Projects/AkitaOnRails.com/.tool-versions  3.2.3
ruby    3.4.5

See how in the mise list output it says 14.21.3 is “missing”. So let’s install it:

AkitaOnRails.com [ master][$!?⇡][ v24.7.0][💎 v3.2.3]
❯ mise use node@14.21.3
mise /mnt/data/Projects/AkitaOnRails.com/.tool-versions tools: node@14.21.3

AkitaOnRails.com [ master][$!?⇡][ v14.21.3][💎 v3.2.3]
❯

With the mise use command we can ask it to install and use a particular version. If it’s not already installed, it will install it. Notice how after that the Starship prompt changed to reflect that we’re now using 14.21.3. That’s the right way.

If you’re not necessarily in a project directory with locked versions, you can still run commands using a specific version, like this:

mise exec ruby@3.2.1 -- ruby ...

Say you want to generate a Rails project on a specific Ruby version:

mise exec ruby@3.2.3 -- rails new todo-exercise

The same goes for generators in Node, like Next.js or any other framework.

I haven’t checked whether LazyVim on Omarchy comes configured this way, but in case it doesn’t, for NeoVim to support Mise you need to add this:

-- Prepend mise shims to PATH
vim.env.PATH = vim.env.HOME .. "/.local/share/mise/shims:" .. vim.env.PATH

Just put this in ~/.config/nvim/lua/config/mise.lua and it should load the correct path. To integrate with other editors, check this documentation. There are TONS of advanced options and it’s worth reading about them in the Dev-Tools section, but the basics are what I listed here.

And databases??

The same goes for databases. Every project should be locked to a specific version identical to what’s running on the production server and should never depend on operating system packages. You can use mise for this but the most recommended option is to use Docker. Every project MUST have a docker-compose.yml to spin up only the databases. You don’t need to spin up containers for languages, for that it’s better to use Mise.

If you don’t understand Docker, I made videos teaching it:

Adding up Mise + Docker Compose + LazyVim, that’s everything you need to be a productive web developer, while also using your machine’s resources efficiently. Every developer NEEDS to learn this combo of options. Omarchy already brings it all pre-installed, which is why it’s been my recommendation for every beginner.

Don’t worry: Arch Linux (with archinstall) is as easy to install as an Ubuntu or Linux Mint, and Omarchy’s Hyprland is much prettier and smoother than MacOS. The best of both worlds. Learn it today!

Even if you don’t use Omarchy, I recommend installing LazyVim. Just do this:

# required
mv ~/.config/nvim{,.bak}

# optional but recommended
mv ~/.local/share/nvim{,.bak}
mv ~/.local/state/nvim{,.bak}
mv ~/.cache/nvim{,.bak}

git clone https://github.com/LazyVim/starter ~/.config/nvim

rm -rf ~/.config/nvim/.git

nvim

That’s it. For those who don’t know, NeoVim is a more modern fork of the old Vim (hence the command is nvim, leaving vim reserved for the old one). It replaces the old VimScript with Lua scripts and has many optimizations and better quality-of-life features. These days, there’s no reason to keep using old Vim.

Using Lua, you can configure Nvim any way you want. But configuring everything from scratch is a lot of work. It’s a good exercise, but practically speaking, it’s not worth it day to day. Better to install a pre-configured setup like the old LunarVim, which I used before and even recommended in some Linux videos on my channel, or AstroNvim, or LazyVim, which is currently my favorite. Any of them is a good start and it comes down to personal preference.

Each plugin they install has many features and its own key combinations (hotkeys) that you need to read in the documentation to know what does what. I recommend going to the plugins section of the official site and reading them one by one. There’s a lot of stuff you wouldn’t even expect, and all of it is very useful.

LazyVim on its own already helps a lot because it opens pop-ups documenting some of the hotkeys. For example, what’s called the Leader command in LazyVim is the “space bar”. When you press it, this context menu appears:

From here, if you type, say, “b”, another context menu shows up:

And if you type “b” again, it switches to the next file already open in the Buffer. Buffer is the Vim name for where already-opened files live. Deleting from the Buffer is the equivalent of “closing the file”.

Next time, you won’t need to look at the menus. Just type quickly in one go: “Space+b+b”. That’s how you memorize the commands you use the most.

Some commands worth learning right away: Space+Space (twice), which opens the menu for opening files. Type a few letters of the file name and it filters dynamically:

Or “Space+e” to open the NeoTree Explorer. Type “?” to open a popup with the commands you can use to create new subdirectories or files within the subdirectory:

Once you learn the other commands and plugins, you’ll notice you don’t even need to open NeoTree. It’s more for when you want to explore visually. For day-to-day work, commands like “:e” should be enough. By the way, “:” (colon) is the command for executing NeoVim functions. For example “:q” is quit, “:w” is write, and “:wq” is write and quit at the same time.

If you want to learn NeoVim more deeply, I recommend the YouTube channel of my friend Eustáquio Rangel, a Linux, Rails, and Vim veteran who teaches NeoVim from scratch (without LazyVim).

Now, let’s say you’ve already learned the basics of NeoVim and LazyVim, and now you want to start working on your PHP, Java, C#, Ruby, Python, or whatever projects. You’ll notice that LazyVim doesn’t have any functionality for any of them.

What do you do now? Install VS Code?? NO!!

That’s because you haven’t run :LazyExtras yet.

Type it exactly like that and watch this:

This window looks complicated but it’s just a list of plugins split into sections. At the top you see the plugins already installed and enabled. If you don’t want any of them, just use the arrows to move the cursor down to one of them and press “x” to unmark it. But leave that section as is. Let’s scroll down to the “Languages” section:

This is the section where all the languages you can enable support for live. Just scroll down with the arrows and mark with “x” which ones you want to install. And there’s everything: Angular, Vue, Erlang, Elixir, Rust, Zig, Haskell, and much more.

Next to each language is the group of individual plugins it will install. To know what each one does, type their names into Google and find the documentation page, where you’ll find hotkeys and extra configurations you can set.

With this you gain things like Linters, syntax highlighting, LSP, snippets, and much more.

And if you want to install additional plugins that aren’t listed, you can add them manually. Read the Adding Plugins section in the documentation.

LazyVim + LazyExtras covers 90% of everything you need for day-to-day software development. It’s lighter and faster than VS Code, uses way less memory, and will be much better especially on older machines. Don’t be lazy about learning Vim. A real programmer shouldn’t stick with VS Code just because they’re too lazy to learn a few extra hotkeys.

If you want to switch to ZSH, it’s easy, just do this:

yay -S zsh zoxide
chsh -s $(which zsh)

Logout, login, and done. But now your shell will be empty. To grab my config do this:

git clone https://github.com/akitaonrails/omarchy-zsh.git ~/.config/zsh
ln -s ~/.config/zsh/.zshrc ~/.zshrc 

There are two things you need to change. In .zshrc remove this line:

source ~/.config/zsh/mounts

That’s just for me to check my NFS mounts to my NAS. It’s useless to you so you can remove it.

The second thing is to create a new file for secrets:

touch ~/.config/zsh/secrets
chmod 600 ~/.config/zsh/secrets

This is where you put stuff like your OpenAI or Google Cloud keys or anything like that. For example:

# ~/.config/zsh/secrets
export OPENAI_API_KEY="sk-xx-v1-xxx...xxxxx"

That way your secrets stay separated from your configs and we can git push to a repository without worrying that something might leak in the future. Always keep secrets, passwords, and keys separated locally. This is already in .gitignore so you’re safe.

As a bonus, in ~/.config/init I added support for Atuin, a tool that syncs all the command history you ran in your shell to a “cloud” repository (read the docs, you can create your own local server too). The repository is encrypted, so it’s safe even if your history contains secret keys in the commands.

Install it like this:

yay -S atuin
atuin register -u <your username> -e <your email>
atuin import auto
atuin sync

As soon as you register, Atuin will generate a random encryption key. Make sure you store this key somewhere safe like 1Password, Bitwarden or another secure vault!! Without it you won’t be able to decrypt on a new installation. If you forget, you can still view it before reinstalling, like:

atuin key

If you reinstall your machine or set up a new one and want your history back, just install Atuin and run:

atuin login -u <your username>
atuin sync

It will ask for your password and encryption key and bring all your history back.

With my config, just hit Ctrl+R to bring up the history search (which from now on will live in a sqlite on your machine). Read the documentation for more features.

DHH set up the Starship prompt using the old PS1 variable style. But Starship already has several nice prompts that are easy to use as “presets”. I picked Pure Prompt, which I like, but there are plenty of others. If you want something flashier and more colorful, there’s this Pastel Powerline:

Pick your favorite on the Presets page and change ~/.config/zsh/prompt on this line:

starship preset bracketed-segments -o ~/.config/starship.toml

Finally, I left some ENVs in ~/.config/zsh/envs that work for my Ollama tests and things like that, but it’s good for you to know they’re there so you don’t find it weird if your Ollama is behaving strangely. Edit the ~/.config/zsh/envs file to set the envs you prefer:

# envs
export OPENAI_API_BASE="https://openrouter.ai/api/v1"
export DEFAULT_MODEL="o1-mini";
export OLLAMA_API_BASE=http://127.0.0.1:11434
export OLLAMA_HOME=http://127.0.0.1:11434
export OLLAMA_MODELS=/mnt/gigachad/ollama/models

Also modify the ~/.config/zsh/aliases file to include aliases you prefer:

# aliases
alias monhd="sudo ddcutil -d 1 setvcp 60 0x12"
alias mondp="sudo ddcutil -d 1 setvcp 60 0x0F"

alias sgpt='docker run --rm -e OPENAI_API_BASE=${OPENAI_API_BASE} -e OPENAI_API_KEY=${OPENROUTER_API_KEY} ghcr.io/tbckr/sgpt:latest txt '

alias git='nocorrect git'
git config --global alias.a 'add'
git config --global alias.ps 'push'
git config --global alias.pl 'pull'
git config --global alias.l 'log'
git config --global alias.c 'commit -m'
git config --global alias.s 'status'
git config --global alias.co 'checkout'
git config --global alias.b 'branch'

The first two aliases are for my dual monitor setup where one of the monitors receives signal from both the HDMI input and the DisplayPort input (I have 2 GPUs). If you didn’t know, you can control that from the shell. Read this post about ddcutil

Next you get the sgpt command. Omarchy already ships with Docker installed. Now from the shell you can ask ChatGPT without having to open a web browser for it:

sgpt "what is the rsync syntax to sync two directories?"

Read the SGPT documentation to learn about other features or which LLMs you can choose.

At the end we have aliases for Git. Omarchy already has an alias making “g” mean “git” and with this one I added you can do:

git add . # old
g a . # new

git commit -m "initial commit" # old
g c "initial commit" # new

git commit --amend -m "initial commit"
g ca "initial commit"

git push origin master
g ps origin master

git pull origin master
g pl origin master

git log
g l

# and so on

More practical and less verbose. Add more aliases as your workflow demands in ~/.config/aliases.

And I think that’s it, now my Omarchy is organized the way I like. Make your own tweaks so everything fits your style too!

In my case, I spent 10 years using Manjaro GNOME as my daily driver. Manjaro is an Arch derivative. The reason was the easier install and the pre-made configs. But these days, with archinstall, I don’t think it’s worth it anymore. I know there are other derivatives, but it’s better to stick with the original.

For Ubuntu folks or those coming from Debian derivatives, Fedora, etc, there’s a small learning curve on the package manager: Pacman and Yay instead of Apt or Dnf. But once you understand the AUR, you’ll never want anything else. It has literally everything you need, without having to deal with third-party repositories.

I took a while to test Omarchy because I was already using Hyprland before Omarchy was created. DHH previously had Omakub, which was a set of scripts to customize Ubuntu into a good development environment. I liked it, but since I preferred Manjaro, I made a fork called Omakub-MJ. After that I decided to uninstall GNOME and GDM and install another set of scripts called ML4W, which makes Hyprland look great as well. So Omarchy wasn’t that novel, for me.

The thing is, I’d been using the same Manjaro for years. It had a ton of old configs and scripts all mixed up. My Manjaro GNOME no longer even had GNOME. My Hyprland was a Frankenstein. The only barrier was my QEMU/Libvirt setup to run Windows with GPU passthrough, which is what I used to edit videos back when I was still posting on my YouTube channel.

But since I stopped editing videos, that Windows isn’t as important anymore. I had another Windows VM with GPU passthrough for games. But currently I have a separate mini-PC with Windows that I use just for games. I also had another VM with another Linux just for my AI experiments, but since then I migrated to running natively while isolating everything with Docker. In other words, my VMs are no longer important. Check my previous blog posts to learn about AI in Docker.

With the release of Omarchy 2.0, it looks like a good time to reinstall Arch from scratch with Omarchy on top and start over clean and beautiful.

1 - My Setup

Every case will be different. This post’s main purpose is to serve as my personal reference for the future, in case I need to reinstall everything again.

No, I’m not going to use NixOS. I really don’t think it’s worth it. It only pays off if you’re a computer lab admin or server infrastructure admin and your day-to-day involves rebuilding identical setups reliably. For a normal user who only reinstalls every 2 or 3 years, the learning curve and maintenance work aren’t even remotely worth it. It’s a waste of time. I’d spend days learning now, finish the setup, go 2 years and I’d already have forgotten everything. Arch Linux by itself is stable enough that I don’t need this.

My setup is still the same from the days I was editing videos for the channel. It’s a Ryzen 9 7850X3D with 16 cores, 32 threads, 5GHz peak. It’s still an excellent CPU with power to spare for my use cases, which is why I don’t see myself wanting to upgrade anytime soon. It’s rare for me to saturate all those cores at those speeds at the same time. Better yet: it has an integrated AMD GPU which makes installing Linux a thousand times easier than if I had NVIDIA.

But I also have a separate discrete GPU, the NVIDIA RTX 4090 (no, I don’t need a 5090, it has the same amount of VRAM). It’ll stay for secondary tasks and not for carrying my graphical environment. Things like Cycles rendering in Blender, or running LLMs with ollama and the like. Before I used GPU passthrough to a VM in QEMU/Libvirt to run Windows in parallel with Linux. Both to edit videos and to game.

Since I no longer edit videos, I don’t need this complicated setup, so I won’t bother installing Libvirt back. If I need Windows, I’ll leave it in dual boot. If I need to edit video, these days we have DaVinci Resolve Studio which runs natively on Linux (a thousand times better than Adobe Premiere). For games I have a separate mini PC with an RTX 4060 hooked up to my TV. The best thing is to have a totally separate PC for games.

So this setup is meant to be pure Linux, with access to my Synology DS 1821+ NAS with 100TB. The only extra thing I’ll need is to configure NFS mounts, as I’ve already detailed in this other post.

One detail is that I have 4 NVMEs in this PC. 2TB for my old Linux. 2 TB for dual boot/Windows VM. 2 TB just as a Steam drive and 1 TB for random stuff. Since I’m wiping the Steam VM, I also no longer need to dedicate an entire NVME just for that. Instead, I’ll make the new Linux’s “/home” directory this entire 2 TB.

This will let me stop worrying about Docker filling my drive and freezing my entire system from lack of space. Last time I had “solved” this by making a remote drive with iSCSI on my NAS (which has infinite space). Since removing my Steam VM will give me 2TB back, I’ll solve the problem locally and with fewer configurations.

RAM I have in spades, 96GB of DDR5. With that, I also don’t need to worry about a swap partition. Swap only matters if you have less than 32GB of RAM, if you’re running lots of Docker and keep hitting the max RAM consumption very fast. Or if you’re on a laptop and want the option of hibernation (being able to record RAM to disk, fully power off the machine, and come back later exactly where you left off — which is different from suspend, which still uses power).

If you want to hibernate, you need a bit more than the size of your RAM. So if you have 32GB, it’s good to leave a margin, around 34GB or more of swap. Since my PC is a desktop at home, I don’t need hibernation, just enable ZRAM for the rare cases where there’s a spike over 96GB (which is super rare). Plus, it’s easier for me to just bump up to 128GB of RAM if I really need it. Swap to compensate for RAM only pays off on laptops that don’t have room for more real RAM.

2 - Why Omarchy?

As I said, I’ve been an Arch user for a decade and I don’t see any package repository bigger and more complete than the AUR. The only other repository that actually competes is NixOS’s. But since Nix is ruled out for my use case, the AUR remains unbeatable.

Arch has Pacman as its package manager. To access the AUR you need a second manager. There are several like the old Pacaur, Paru, and many others. But the best, in my opinion, is Yay. It has exactly the same syntax as Pacman and replaces Pacman. In practice, we just use Yay for everything.

To search packages by name just do yay -Ss spotify.

To remove packages just do yay -Rns spotify.

To update all system packages just do yay -Syu

To remove orphan packages that pile up over time just do sudo pacman -Rns $(pacman -Qdtq)

And those are the commands I use 99% of the time.

I’ve already used every type of desktop manager out there: GNOME (which behaves more like a Mac), KDE (which behaves more like Windows for power users), XFCE (which is GTK-based and lighter), Cinnamon (also GTK-based), i3 (which is a tiling window system), Sway (like i3, also tiling but if I’m not mistaken was designed with Wayland in mind).

In practice, everyone uses apps in two ways: a full-screen window or 2 vertical windows splitting the monitor in the middle (editor on one side, browser on the other), or 3 windows (a vertical editor taking half the monitor, a browser taking 1/4, and a terminal taking another 1/4). Then we organize more open apps into virtual desktops/workspaces. That’s the easiest way to work.

This means being able to drag floating windows is a waste of time. I prefer that windows already open sized into one of these layouts I mentioned above. You can configure GNOME or KDE to do that. But it smells like a kludge. Instead it really is better to use i3 or Sway.

Setting controversies aside (yes, I’m a bit wary of Wayland and I like that XLibre exists). But it’s a fact that X11 is behind the times and is a very old and complicated architecture. Wayland really does have a better “appeal,” despite having taken a while to round off basic things like screen sharing (OBS, Zoom). But I’ve been using Wayland for some years now without headaches. These days I’d say it’s pretty stable. I’ve been using GNOME on Wayland for a long time. I don’t stop using things because I’m wary of them: with technology I’ll always be absolutely promiscuous and use everything.

Knowing I’ll use Wayland and knowing I want automatic window layouts, and don’t need floating windows, the best is a desktop manager with a tiling windows system (tiles are “azulejos” and we’re talking about tiles being side by side and never one on top of another), which organizes windows side by side in a smart and automatic way.

In this case we only have 2 options: Sway or Hyprland (either one is good). Hyprland, installed from scratch, is completely bare — it has absolutely nothing. We need to configure everything through files in .config/hypr. It’s simple enough, but it’s work.

The only good option for having a pre-configured and well-done Hyprland was ML4W, which I was already using. But now we have Omarchy, which installs and pre-configures everything to work smoothly on Hyprland. This is the best option we have today.

Besides configuring Hyprland to work with Waybar, Rofi, and other components, it has its own system for switching themes and styles to leave the system with the “look and feel” you want (and all the ones that come with it are super pretty), but it also installs things I’ve been using for a long time like Neovim with the LazyVim package (in my opinion, the easiest way to make Neovim not fall short compared to VS Code), Mise (the best way to organize development environments to have multiple versions of your favorite programming language).

If you’re installing a distro from scratch, the only two things you need to have are Mise and LazyVim. Plus Docker and LazyDocker. That’s enough to start a productive development environment. And Omarchy already brings all of that pre-configured. No one “needs” Omarchy, but it already brings everything integrated and beautiful. So why bother doing everything from scratch to end up almost the same?

Also, this is Linux. Don’t like one of the components? Just swap it out.

3 - Back Up

The vast majority of everything I have already lives on the remote server, my 100TB Synology NAS. That already helps a lot. Even so, there’s still a good amount of stuff locally on my PC, so the first thing to do is copy everything to the NAS. If you don’t have a NAS, then an external HD. Any server will do; the important thing is to guarantee you won’t lose anything before installing a new OS from scratch.

Don’t forget directories like .config or .local. It’s better to do an rsync -avz --progress .config /mnt/nas/backup/, for example, and copy everything. Even what you think you won’t need. Better to copy more than to be missing stuff. As a rule, the ideal is to copy everything in your $HOME to an external drive or NAS.

Just to make sure I won’t forget anything important, I’m also going to record a list of all the packages I have installed on my old system:

yay -Q > pacotes.txt
flatpak list > flatpak.txt

Also making sure I won’t lose old configs of services I made in systemd, so also copy everything from /etc/systemd/system. It’s also worth recording things like /etc/fstab. Also don’t forget to back up your SSH keys with tar cvfz ssh.tgz ~/.ssh!!

If, like me, you were using QEMU/Libvirt for VMs, it’s good to save the configs of the virtual machines you used. Usually the tool to manage VMs is virsh, so I just did:

sudo virsh list --all
sudo virsh dumpxml <vmname> > <vmname>.xml

If I want to recreate the machines in the future, it will all be in the backup. In my case I keep all virtual drives on my NAS, but if yours are local, you also need to save those files that live in /var/lib/libvirt/images/

rsync -avh --progress /var/lib/libvirt/images/ /backup/libvirt-images/

4 - Is Installing Arch Hard?

Arch, less than Gentoo, has always had a reputation for being the most brutal Linux distro for a beginner to install. That’s not a lie, but the truth is Arch is simultaneously the hardest distro and also the easiest.

Download the official ISO and burn it to a USB drive (on Windows, using Rufus or Balena Etcher). Now press F12 (depends on your BIOS) or configure the BIOS directly to boot from the USB drive. Doing that loads the Arch live environment, which is literally dropping into a command line. With no further help.

From this point you have to follow the Installation Wiki from the excellent ArchWiki and learn how to install a Linux from absolute scratch using only the command line, step by step, through trial and error (more erring than hitting the mark), and in the end you’ll have a much better feel for how a Linux distro actually works.

I didn’t make an Arch video but I did make videos of Slackware to explain how a package manager works. I also made a Gentoo video to show how a distro that compiles everything from scratch works. And I made a video about how the Linux Boot Works to understand where the kernel lives and how it’s structured. But I didn’t make an Arch video because I always left it as an exercise for beginners.

The manual way is viable, but if you’re used to a graphical installer, like Calamaris, which most more popular distros like Ubuntu or Fedora have, you’ll be totally lost. But here comes the bonus: you don’t need to go through all of that to have Arch Linux on your machine.

For that there’s archinstall.

When you boot the Arch USB and drop into the command line, just type archinstall and you’re done — just follow the step by step it provides (which I consider even simpler than Calamaris) and it will install and configure everything automatically for you, the same way installing Fedora or any other distro is. Seriously, it shouldn’t take more than 15 minutes.

archinstall looks like this:

Just go into each of the items on the left and fill in your choices. Configure things like keyboard layout (I normally choose ‘us-acentos’). Edit the hostname of your machine. Choose “NetworkManager” in network configuration (it will configure both ethernet and wifi for you), add Bluetooth and Audio support (choose “Pipewire”). Choose the “desktop” type instead of “minimal” to already get the main packages needed for a desktop. Choose the timezone (“America/Sao_Paulo” in my case).

I also recommend choosing the Hyprland option, I think under Applications or Additional Packages. It will install SDDM to give you a graphical login.

Only two options need more attention: for bootloader, many will be tempted to use Limine, which is more modern and lightweight. But I still recommend using GRUB, I’ll explain why in a moment.

The second important option is “Disk Configuration”. Don’t worry, unlike fdisk, it’s super intuitive. Just choose the correct drive where you want to install (if you have dual boot, careful not to wipe your Windows). Then let it do the automatic partition layout (only edit manually if you have some very special need). Most importantly, choose BTRFS instead of the traditional ext4.

Every Linux always formats its Linux partitions with ext4, which is the oldest, most stable, and best-documented file system. These days I recommend BTRFS; it’s much more modern, safer (has better corruption protection systems), uses less space (learn about CoW - Copy on Write), and most importantly: it has cheap snapshot support (think of Apple Time Machine, only better). It has most of the features of a file system dedicated to a file server but is much simpler and more intuitive to use than the monster that is ZFS (I don’t recommend it for normal users).

It has some maintenance needs that are worth reading about in the Wiki to learn. But overall it’s plug and play, install and forget. In the next sections I’ll show some things you need to know, but trust me: choose BTRFS.

I know Omarchy 2.0 has an option for a pre-configured ISO which I imagine is normal Arch with archinstall and Omarchy on top all at once. But I don’t know if they allow this choice, which is why I preferred going straight to pure Arch first. In the end the effect is the same. Comment below later if the Omarchy ISO also has the same options. Just make sure in the end you have BTRFS. Future you will thank you.

5 - Separate HOME

As I explained before, I used one of my 4 NVMEs as the Linux drive. But now I’ve freed up another NVME and want to move my $HOME there and have 2 TB dedicated just to user space.

I won’t explain how to partition and format that other drive. It’s simple: just use fdisk or later install Gparted which is the graphical version of the parted tool that you can use from the command line. There are several options. The important thing is just to wipe my old Windows partition and also format it with BTRFS.

Each person will have different device and partition names than mine. To find out which are yours, use the lsblk command. See my example:

In my example nvme1n1 is the 1TB drive for random stuff. nvme2n1 is my new Arch Linux. nvme0n1 is the old Windows dual boot drive. nvme3n1 is the Steam drive I formatted with BTRFS to become my new HOME drive.

If you didn’t get it, HOME is the /home/akitaonrails directory. It will live on a separate drive. After archinstall finishes and I boot into the new Linux, I just do the following:

sudo mount -t btrfs /dev/nvme3n1p1 /mnt
sudo btrfs subvolume create /mnt/@home
rsync -aAXHv /home/ /mnt/@home/
sudo umount /mnt

This mounts the new partition, then we use the “btrfs” command to create a new sub-volume called “@home” (again, read the BTRFS Wiki to understand concepts like sub-volumes).

The commands above create the sub-volume and copy everything from the old HOME to the new. Now we need /home to be mounted on this new partition at boot. For this we need to know the UUID of that partition:

~ ❯ sudo blkid /dev/nvme3n1p1
/dev/nvme3n1p1: LABEL="HOME" UUID="84e9a1b7-a30e-...

The blkid command returns the unique UUID of each partition and, with that, we can edit the /etc/fstab file using sudo nvim or sudo nano or the editor of your choice:

# /etc/fstab
...
# /dev/nvme2n1p2
# UUID=da3aea43-...-aeaf8c7224d7 /home      btrfs      rw,relatime,ssd,discard=async,space_cache=v2,subvol=/@home 0 0

# /dev/nvme3n1p1
UUID=84e9a1b7-...-7a6a17fd0395 /home      btrfs      rw,relatime,ssd,discard=async,space_cache=v2,subvol=/@home 0 0
...

See how I commented out the old line that mounted /home and added a new line with the new UUID. The rest is all the same. And that’s it, just boot and from now on my /home will mount on the new drive. Now I have 2 TB dedicated just to my junk downloads lol 🤣

But not only that, I also have space for big things like Docker images or LLM models, without risking filling the operating system drive and running the risk of it no longer booting due to lack of space — as has happened to me several times in the past. Always remember to do maintenance on Docker and LLMs and delete old things.

Speaking of which, BTRFS supports snapshots. And one of the basic mistakes is forgetting that Docker or LLM directories can end up in the snapshots and occupy space without you knowing. To avoid this it’s better to mark those directories to not enter the snapshots. For that we have to tell BTRFS to ignore those directories.

The correct way is to create separate subvolumes for them. For this I’ll mount that same partition on the separate drive where I mounted my $HOME:

~ ❯ sudo mkdir /mnt/temp
~ ❯ sudo mount -o subvolid=5 -t btrfs /dev/nvme3n1p1 /mnt/temp

~ ❯ ls /mnt/temp
 @home   timeshift-btrfs

~ ❯ sudo btrfs subvolume create /mnt/temp/@docker
Create subvolume '/mnt/temp/@docker'

~ ❯ sudo btrfs subvolume create /mnt/temp/@ollama
Create subvolume '/mnt/temp/@ollama'

~ ❯ sudo umount /mnt/temp

Now just edit /etc/fstab to mount correctly just like we did with HOME:

# /etc/fstab
...
# /dev/nvme3n1p1
UUID=84e9a1b7-...-7a6a17fd0395 /home      btrfs      rw,relatime,ssd,discard=async,space_cache=v2,subvol=/@home 0 0
UUID=84e9a1b7-...-7a6a17fd0395 /var/lib/docker      btrfs      rw,relatime,ssd,discard=async,space_cache=v2,subvol=/@docker 0 0
UUID=84e9a1b7-...-7a6a17fd0395 /var/lib/ollama      btrfs      rw,relatime,ssd,discard=async,space_cache=v2,subvol=/@ollama 0 0
...

Done, clean subvolumes. More important in my case: I moved directories that have a tendency to grow without control out of the operating system partition, making it harder to end up with an inaccessible system due to lack of space. Do the same with other similar directories, with things like Kubernetes, for example. Anything that keeps downloading large files, like system images.

Now just mount and bring things back:

# every time you edit fstab, run this:
sudo systemctl daemon-reload

# create the mount points
sudo mkdir /var/lib/docker
sudo mkdir /var/lib/ollama

# mount
sudo mount /var/lib/docker
sudo mount /var/lib/ollama

# copy the contents of the old directory back
sudo rsync -aHAX --inplace /var/lib/docker.old/ /var/lib/docker/
sudo systemctl start docker

Besides space management, what’s the other advantage of making separate subvolumes? Because the next section will be about making the system even more robust by adding snapshot and rollback capability to past snapshots. And the ideal is to keep huge files out of snapshots that will sit in the past. Docker images are easy to recover: just docker pull again, no need for backup.

6 - Installing Omarchy

This is the easiest part. When you’re done installing with archinstall, if you chose the Hyprland option, SDDM will appear for you to log in. And when you enter you’ll be shocked at how raw Hyprland is. You basically can’t do anything.

So this doesn’t become an entire day of manual configuration, we’ll use Omarchy. Hit “Super Enter” to open the terminal and don’t mind how ugly things look right now. It’ll get better.

In the terminal just do this:

curl -fsSL https://omarchy.org/install | bash

Just follow the on-screen instructions and let it do the rest. And that’s it, done, there’s no next step.

I HIGHLY recommend you read the OMARCHY ONLINE MANUAL that DHH made. It’s very clean, simple, and direct. All the keyboard shortcuts, for example, are in the HOTKEYS section. Spend an hour reading the basics to be able to operate it. But by now you already have practically everything you need: Alacritty as terminal, Chromium as browser (you can install Brave if you prefer, as I do).

“Super Alt Space” opens the Omarchy main menu. “Super Space” opens Rofi to type the name of the app you want to open. “Super Enter” opens the terminal. “Super B” opens the browser and so on.

7 - Customizing Omarchy

Omarchy is a customized Hyprland. We can edit whatever we want directly in ~/.config/hypr. And since I was used to ML4W, I decided to tweak a bit to make it good for my setup. Your setup will vary depending on your needs.

Right after I finished installing Omarchy and tried to use Gparted to partition that second NVME of mine for HOME, it had an authentication problem. I don’t remember if this was the solution but it’s good to make sure you have Polkit installed:

# make sure polkit + agent exist
sudo pacman -S --needed polkit polkit-gnome xorg-xhost

# Hyprland: export full env to systemd user bus once
dbus-update-activation-environment --systemd --all

Back to it, the first thing I need to solve is that I have 2 monitors. An Asus 32" 1440p 144fps as the main and another Samsung 24" 4K 60fps vertical on the left side. The way to configure this in Hyprland is by editing a file like ~/.config/hypr/monitors.conf which is normally loaded by ~/.config/hypr/hyprland.conf.

Instead of doing this manually, I prefer to install:

yay -S nwg-displays

Here I configure things like transform 90 degrees to rotate the vertical monitor, resolution scaling, 10-bit color support, etc.

It will save two files: ~/.config/monitors.conf and ~/.config/workspaces.conf. Omarchy doesn’t load this second file, so we have to edit ~/.config/hypr/hyprland.conf to look like this:

...
# Change your own setup in these files (and overwrite any settings from defaults!)
source = ~/.config/hypr/monitors.conf
source = ~/.config/hypr/workspaces.conf`
...

I also took the opportunity to add some extra configurations in this file:

...
# animation
animations {
  enabled = yes
  bezier = easeOutQuint, 0.23, 1, 0.32, 1
  animation = workspaces, 1, 4, easeOutQuint, slide
  # optional extras:
  animation = specialWorkspace, 1, 4, easeOutQuint, slide
  animation = windows, 1, 4, easeOutQuint, popin 80%
  animation = fade, 1, 4, easeOutQuint
}

xwayland {
    force_zero_scaling = false # careful with mixing scaling wayland and x11
}

input {
  numlock_by_default = true
}

# dialogs/splash/utility ONLY
windowrulev2 = float,  xwayland:1, windowtype:^(dialog|splash|utility)$
windowrulev2 = center, xwayland:1, windowtype:^(dialog|splash|utility)$

# never center menus/tooltips
windowrulev2 = tile,   xwayland:1, windowtype:^(popup_menu|dropdown_menu|tooltip)$

Some people don’t like it but I like having a quick animation when I switch from one workspace to another, which is why I added the animations block.

When you use apps made for X11, they’ll run on top of XWayland. One annoying thing is that some of them open “dialog boxes,” which are floating windows. And they can end up in places hard to click, especially on a multi-monitor setup. That’s why I added blocks like xwayland and windowrulev2 rules to force those dialog boxes to always appear centered on screen.

Finally, I have an 8bitdo numpad keyboard connected via Bluetooth, but it doesn’t start up with numlock on. To fix this there’s that input block.

Back to the monitor layout. After nwg-displays generated the files, I still had to modify a bit for my case, like this:

# ~/.config/monitors.conf
# Generated by nwg-displays on 2025-08-28 at 14:30:17. Do not edit manually.

#monitor=HDMI-A-3,2560x1440@143.97,1080x407,1.25,bitdepth,10
#monitor=DP-5,3840x2160@60.0,0x0,1.875,bitdepth,10
#monitor=DP-5,transform,1
#monitor=DP-1,0x0@60.0,-1x-1,1.0
#monitor=DP-1,disable

monitor=HDMI-A-3,2560x1440@143.97,2813x948,1.0,bitdepth,10
monitor=DP-5,3840x2160@60.0,1373x350,1.5,bitdepth,10
monitor=DP-5,transform,1
monitor = DP-1,disable

The monitor file I didn’t have to change anything, really, just remember to disable that DP-1 that appears on my main monitor (I think it’s its DisplayPort, but I use HDMI, so I have to disable DP-1).

# ~/.config/workspaces.conf
# Generated by nwg-displays on 2025-08-28 at 13:07:02. Do not edit manually.

workspace=5,monitor:DP-5,persistent:true
workspace=1,monitor:HDMI-A-3,persistent:true
workspace=2,monitor:HDMI-A-3,persistent:true
workspace=3,monitor:HDMI-A-3,persistent:true
workspace=4,monitor:HDMI-A-3,persistent:true

This one I also didn’t have to change much, in nwg-displays itself I said which workspaces I want on each monitor. In my personal preference I prefer to leave the vertical monitor only with workspace 5 and the others on the main monitor. The difference here was that I added those persistent:true options on all of them, to guarantee that everything will work correctly with the workspaces “pinned” in the right places. Workspaces in Hyprland are quite dynamic; it’s worth reading the documentation later if you want more complicated cases.

This solves my two-monitor setup the way I prefer. Experiment with things like scaling until everything is okay for your setup.

Next I needed to solve the hotkeys (key bindings). I’m used to some combinations that came from ML4W so I decided to copy them directly into ~/.config/hypr/bindings.conf. First, switch chromium for Brave:

# Application bindings
$terminal = uwsm app -- alacritty
$browser = brave # omarchy-launch-browser
...

Then I added a bunch of binds at the end of the same file:

unbind = SUPER, V
bind = SUPER, V, swapsplit
bind = SUPER, M, fullscreen, 1                                                           # Maximize Window
bind = SUPER, T, togglefloating                                                          # Toggle active windows into floating mode
bind = SUPER SHIFT, right, resizeactive, 100 0                                           # Increase window width with keyboard
bind = SUPER SHIFT, left, resizeactive, -100 0                                           # Reduce window width with keyboard
bind = SUPER SHIFT, down, resizeactive, 0 100                                            # Increase window height with keyboard
bind = SUPER SHIFT, up, resizeactive, 0 -100                                             # Reduce window height with keyboard

# Display
bind = SUPER SHIFT, mouse_down, exec, hyprctl keyword cursor:zoom_factor $(awk "BEGIN {print $(hyprctl getoption cursor:zoom_factor | grep 'float:' | awk '{print $2}') + 0.5}") # Increase display zoom
bind = SUPER SHIFT, mouse_up, exec, hyprctl keyword cursor:zoom_factor $(awk "BEGIN {print $(hyprctl getoption cursor:zoom_factor | grep 'float:' | awk '{print $2}') - 0.5}") # Decrease display zoom
bind = SUPER SHIFT, Z, exec, hyprctl keyword cursor:zoom_factor 1 # Reset display zoom

# Workspaces
bind = SUPER, 1, workspace, 1 on HDMI-A-3 # Open workspace 1
bind = SUPER, 2, workspace, 2 on HDMI-A-3  # Open workspace 2
bind = SUPER, 3, workspace, 3 on HDMI-A-3 # Open workspace 3
bind = SUPER, 4, workspace, 4 on HDMI-A-3 # Open workspace 4
bind = SUPER, 5, workspace, 5 on DP-5 # Open workspace 5

bind = SUPER SHIFT, 1, movetoworkspace, 1  # Move active window to workspace 1
bind = SUPER SHIFT, 2, movetoworkspace, 2  # Move active window to workspace 2
bind = SUPER SHIFT, 3, movetoworkspace, 3  # Move active window to workspace 3
bind = SUPER SHIFT, 4, movetoworkspace, 4  # Move active window to workspace 4
bind = SUPER SHIFT, 5, movetoworkspace, 5  # Move active window to workspace 5

bind = SUPER, Tab, workspace, m+1       # Open next workspace
bind = SUPER SHIFT, Tab, workspace, m-1 # Open previous workspace

bind = SUPER CTRL, 1, exec, $HOME/.config/hypr/moveTo.sh 1  # Move all windows to workspace 1
bind = SUPER CTRL, 2, exec, $HOME/.config/hypr/moveTo.sh 2  # Move all windows to workspace 2
bind = SUPER CTRL, 3, exec, $HOME/.config/hypr/moveTo.sh 3  # Move all windows to workspace 3
bind = SUPER CTRL, 4, exec, $HOME/.config/hypr/moveTo.sh 4  # Move all windows to workspace 4
bind = SUPER CTRL, 5, exec, $HOME/.config/hypr/moveTo.sh 5  # Move all windows to workspace 5

Note that the last block of scripts needs a script to move all windows at once to another workspace. I copied this moveTo.sh from ML4W’s GitHub and placed it directly in ~/.config/hypr. Don’t forget to give execute permission with chmod +x moveTo.sh afterwards. The various workspace ones below are how I prefer to move workspaces and move apps to different workspaces.

Omarchy already comes with “SUPER J” to change the orientation of windows, for example, if there are two horizontal windows one on top of the other, with SUPER J they become vertical, but “SUPER V” was missing which I added for “swapsplit” which is swapping windows’ places.

I also like “SUPER M” to temporarily make one of the windows full screen, and “SUPER T” to temporarily make a window floating (like a calculator, for example). I had to unbind the previous SUPER M that opened Spotify, but I barely use Spotify on desktop so I don’t need it. When I want to open that app, I go to SUPER SPACE to open Rofi and type it there.

If you have questions about the default combinations, Omarchy has “SUPER K” to open a window with help for all of them.

I still haven’t modified combinations for specific applications. The ones that come with Omarchy are already very useful, like SUPER A to open ChatGPT as if it were a separate app, or SUPER CTRL A to open Grok in a separate window. SUPER O to open Obsidian is also very useful for me. I recommend playing with these binds to make specific bindings and, again, reading the manual to learn everything else it already brings. But up to here it’s enough to leave Hyprland the way I like to use it.

8 - Timeshift, Snapshots and GRUB

Remember I said to choose GRUB in archinstall? It’s time now. The goal: let the system make periodic snapshots of itself, and in case you install some corrupted package or do things on your system that prevent it from booting, instead of having to resort to a USB drive to try to boot and diagnose the error, it’s easier to just boot, choose a snapshot right before the destructive operation, and come back intact.

Before proceeding, an adjustment I think is important: my 4K monitor makes GRUB letters too small for me to read. I prefer bigger letters. Fortunately GRUB uses bitmap fonts so I can use any. I did the following:

sudo grub-mkfont -s 48 -o /boot/grub/fonts/caskaydia48.pf2 /usr/share/fonts/TTF/CaskaydiaMonoNerdFont-Regular.ttf

This will generate a font in the format that GRUB can load. Choose any one you like; Omarchy already pre-installs several very good ones like JetBrains’s. If size 48 is too big, lower it to 32, experiment until it’s the way you like.

Then just edit /etc/default/grub to, at the end, have this line:

GRUB_FONT=/boot/grub/fonts/caskaydia48.pf2

And now just regenerate the bootloader:

sudo grub-mkconfig -o /boot/grub/grub.cfg

Every time yay -Syu brings a kernel or driver update, GRUB will be regenerated with the same font. Look at how it turned out for me, I think it looks much better (this is a 4K monitor):

Now the entire reason for having chosen GRUB: allowing you to choose BTRFS snapshots to boot into the past, before some destructive operation, as shown in the photo above. For this we need the following:

pacman -S timeshift grub-btrfs
yay -S timeshift-autosnap
systemctl enable --now grub-btrfs.service

Done. From now on, every time GRUB is rebuilt, it’ll have a new option to choose snapshots. We just need to create those snapshots automatically, and for that we have the Timeshift app. Open it and follow its step by step. The important thing is to choose the BTRFS option (yes, you can use RSYNC if you’re on ext4, but that occupies a lot of space, because it will literally keep making copies of your entire system’s files. The beauty of BTRFS is that its snapshots don’t duplicate files).

I leave it making snapshots and accumulating versions of the last hours, last days, last weeks, and months. If later on I remember “damn, there was that file I deleted last month but now I need it” just open Timeshift and browse a snapshot from last month. Like Mac folks do with Time Machine, but occupying almost no extra space.

Besides that, every package upgrade will generate a snapshot beforehand. That way, if by chance a corrupted package comes in or breaks some important config of yours, you can go back exactly to how it was before the update. And if it breaks catastrophically, where your Linux no longer boots, just go to the GRUB extra menu and boot from the previous snapshot, which worked. And everything comes back just like it was before.

Nothing is more important for your system than having automatic snapshots that occupy almost no extra space. This alone makes BTRFS superior to any alternative.

This does not replace external Backup!!

This rollback and the ability to recover things easily is good for day-to-day accidents. But let’s say your NVME breaks somehow, or your PC breaks somehow. That’s what external backups are for (be it external HD, NAS, or Cloud). You want to be sure that, in a catastrophic situation, it’s still possible to recover your files.

I have all the protection layers: local snapshots via BTRFS and Timeshift, backups done remotely to my NAS, and a backup of the most important parts of my NAS on Amazon Glacier which, unlike Amazon S3, is for keeping backups, where storage cost is ultra low but transfer cost is higher (S3 storage is more expensive but transfer is cheap, which is why it serves to serve website assets).

I like being prepared so that, in case my house catches fire, I don’t lose anything important.

9 - NFS on the NAS

Speaking of NAS, one thing I configured differently — since I primarily use Linux instead of Windows — was enabling the NFS server.

But beware that some NAS have a characteristic that can be annoying: your user on the NAS will have a UID and GID different from 1000!

When you create a user on any Linux, the default is to assign UID 1000 to the first user, 1001 to the second, and so on. But since on the Synology NAS the first user receives UID 1026, if I mount with NFS (which passes through UNIX permissions), I’ll have authorization problems.

There are two solutions: try to change the UID on the NAS from 1026 to 1000. I tried that and I’ll tell you up front it’s a waste of time, you can end up breaking your NAS’s configurations catastrophically.

It’s much easier to change the user of your new local Linux to be 1026 and that’s it. It’s pretty easy.

First, we need to log out and leave Hyprland and go back to the SDDM login screen. Then we need to switch to another TTY with CTRL + ALT + F3 (to go to tty3, for example). From there we have to log in as root.

Now we run: systemctl isolate multi-user.target to run in isolated recovery mode, where no other user has processes running. Since we’re going to mess with the user, they can’t be active.

usermod -u 1026 akitaonrails
groupmod -g 1026 akitaonrails
chown -R 1026:1026 /home/akitaonrails

With the commands above we change from 1000 to 1026 and fix the permissions on the local files to reflect this change. Now yes, we can edit /etc/fstab to mount the shared directories on the NAS with NFS:

# NFS
192.168.0.x:/volume1/GIGACHAD /mnt/gigachad nfs4 _netdev,noauto,nofail,bg,x-systemd.automount,x-systemd.requires=network-online.target,x-systemd.after=network-online.target,x-systemd.idle-timeout=60s,noatime,nodiratime,async,rsize=65536,wsize=65536,actimeo=1  0 0
192.168.0.x:/volume1/TERACHAD /mnt/terachad nfs4 _netdev,noauto,nofail,bg,x-systemd.automount,x-systemd.requires=network-online.target,x-systemd.after=network-online.target,x-systemd.idle-timeout=60s,noatime,nodiratime,async,rsize=65536,wsize=65536,actimeo=1  0 0

Don’t forget to create the mount points:

mkdir /mnt/gigachad
mkdir /mnt/terachad

Done, just reboot and everything will work correctly. The file permissions on the NAS — which are UID 1026 and GID 1026 — will be accessible to the local user without problems.

10 - Utilities

Here are the last small tips to keep everything in one place. The first is to replace the ls command with eza which offers a nicer face, with icons and everything, like this:

Just do yay -S eza and add this to your .zshrc or .bashrc:

alias ls='eza --icons --color=auto --group-directories-first'
alias ll='eza -l --icons --color=auto --group-directories-first'
alias la='eza -la --icons --color=auto --group-directories-first'

Second tip is to install Atuin. For anyone who deals with infra, this is extremely important: backup of all the command history you’ve used in your terminal to this day.

Install with yay -S atuin and do:

atuin login
atuin sync

Read the official site, but first you need to create an account and a secret encryption key — yes, you can run it locally on a server at your house, but their cloud option is pretty convenient and secure because it’s all encrypted, so there’s no problem if you upload passwords from your history.

Just put this in your .zshrc:

export ATUIN_NOBIND=true
eval "$(atuin init zsh)"
bindkey "^R" atuin-search

# incremental history search with arrow keys
bindkey "^[[A" history-beginning-search-backward
bindkey "^[[B" history-beginning-search-forward]]

If you’re using ZSH, its autocomplete will work normally but, if you type CTRL+R, it will open the Atuin history. It will save all your commands in a SQLite and sync. That way you can sync several machines and servers you use day-to-day or, as in my case, recover the whole history on a new install.

And to make it better, we can configure it to auto-sync:

mkdir -p ~/.config/atuin
sed -i 's/^#\?auto_sync.*/auto_sync = true/; s/^#\?sync_frequency.*/sync_frequency = "30m"/' ~/.config/atuin/config.toml 2>/dev/null || \
printf 'auto_sync = true\nsync_frequency = "30m"\n' >> ~/.config/atuin/config.toml

Third tip: since we have Docker already installed and configured, I like to use SGPT on the command line for when I want to remember the syntax of some command I rarely use, instead of opening an app or browser. Just add this to my .zshrc:

export OPENROUTER_API_KEY="sk-or-v1-8b8...17"
export OPENAI_API_KEY="sk-or-v1-db...f3"
export OPENAI_API_BASE="https://openrouter.ai/api/v1"

alias sgpt='docker run --rm -e OPENAI_API_BASE=${OPENAI_API_BASE} -e OPENAI_API_KEY=${OPENROUTER_API_KEY} ghcr.io/tbckr/sgpt:latest txt '

I use OpenRouter to have access to different commercial LLMs in a single API, but you can just use your OpenAI key. With this done, I’d use it in the terminal similar to this:

~ ❯ sgpt "what is the pacman command in Arch to find out if a particular file came from an installed package?"
To find out if a particular file came from an installed package in Arch Linux, you can use the following pacman command:

``bash
pacman -Qo /path/to/file
``

Replace "/path/to/file" with the actual path to the file you want to check. This command will show the package which owns the file, or report that the file does not belong to any package if that is the case.

If you want, it supports sessions, so it’ll remember the conversation on each new call. Read the project’s Github.

Since I backed up my old ~/.config, things like open tabs from my Brave browser opened normally in this new Omarchy install and I can keep doing my things exactly from the point I left off. I didn’t lose anything. The same goes for all the other apps like emails that I back up locally via Thunderbird. I don’t need to have it all downloaded again.

If, like me, you have several audio output devices, it’s possible that right after finishing the install you’ll notice that it seems there’s no sound. But that’s not a problem because it may just be that the output is pointing to the wrong device or the wrong profile. Use SUPER ALT SPACE to open the Omarchy menu, choose SETUP and AUDIO to open that program which is text mode (I like text mode programs).

In my case, I use a Topping D70 DAC to process my audio and the “Default” profile doesn’t work but switching to “Pro Audio” worked. Also be careful that there’s a global volume setting and individual volume control per program. Overall, thanks to Pipewire, everything should work normally.

I tested apps like Discord, Blender, Bambu Studio, VLC and everything worked perfectly. Only VLC needed codecs from a separate package:

yay -S extra/vlc-plugin-ffmpeg

Blender too, the best is to install from this package:

yay -S blender-bin

If you use the normal “blender” package, some of its add-ons don’t install right. I had this problem with MACHIN3Tools and MESHMachine, for example.

Speaking of Blender, it’s an X11 app. Wayland runs X11 applications using an adapter layer called XWayland. I had several problems with menu and dialog box positioning, even adding windowrule. One thing that worked, I’m not sure why, was installing Blender and Bambu Studio via Flatpak:

yay -S flatpak
flatpak install org.blender.Blender
flatpak install com.bambulab.BambuStudio

Finally, if you’re new to LazyVim, don’t forget to run the :LazyExtras command to install extra plugins for your favorite languages, like LSP, Linter, syntax highlight, snippets, and more. Pure LazyVim is already complete but without support for many languages so as not to be unnecessarily heavy; you need to install them separately afterwards.

Also learn to use Mise-en-place. In the Omarchy menu there’s an option to install support for various languages and it will use Mise, which is the correct way to manage your languages.

Mise is really easy, in general, from inside your project directory, just do something like:

mise use ruby@3.4.3

With this, only inside your project will Ruby 3.4.3 be available, but outside there can be another global version. Don’t forget to activate it in your .zshrc:

eval "$(mise activate zsh)"

Impressions and Conclusion

Compared to my old Manjaro, there’s a lot I no longer need to configure. For example, because of the amount of space Docker and LLMs needed, I had configured an iSCSI drive on my NAS just for that. But since I freed up 2 TB of local NVME, I no longer need to deal with that, I just use the new BTRFS sub-volumes I created above.

I also no longer need to configure QEMU/Libvirt because I no longer need to use Windows alongside Linux side by side. I kept the NVME with the Windows partitions and I can dual boot to it if I really need something. Overall I never need it, so it’s one less complicated configuration.

I spent months using apps via Flatpak, with the aim of being more secure and isolated from the system. It’s like running apps via Docker. But it’s too annoying. Being isolated means it doesn’t obey system themes, and in the end I’m forced to keep opening permissions for the apps. And if it’s going to keep opening them, it’s easier to install natively via yay and everything works perfectly.

I think that completes my notes of everything I needed to do to leave Omarchy exactly the way I like. As I said repeatedly, what works for me doesn’t mean it’ll work for you. For that there’s documentation like ArchWiki which is “THE” best place to learn everything about Linux. Use and abuse that documentation.

As you can see, there wasn’t all that much I customized in Omarchy, which is why I like it: it already did 95% of the path for me, I just had to touch a few adjustments to leave it the way I need. And now without all the junk that piled up in my old Manjaro. I recommend everyone install Omarchy as a first Linux and learn to actually use it.