Introduction

What is a workstation?

If a server is a machine whose role it is to serve applications to many people over a network, a workstation is a machine whose role it is to serve a local operator stationed at the computer.

A Linux workstation is therefore a personal computer that you use for “work”: development, administration, writing, research. Your workstation might be a desktop computer, a laptop, or even a headless box that you SSH into. It is the role of the machine that matters, not its form factor.

Your workstation may be connected to a broader network, but it is primarily a client: a terminal, web browser, editor, and control panel for other systems – not a server for a wider audience. That distinction is worth defending, for both security and data hygiene. The two rules are simple: never keep production data on your work machine, and never work directly in production.

Bend those rules however you like, but do so knowingly. A machine that quietly becomes a pet-with-ports costs you the ability to reason clearly about where it is deployed, what it contains, and who depends on it.

Why Arch Linux

Arch installs a base system and then stops. There is no distribution layer sitting between you and the software you run: packages are built close to upstream, defaults are upstream’s defaults, and nothing is configured on your behalf. The practical consequence is that everything you read about a piece of Linux software applies to your machine literally rather than approximately – including the Arch Wiki, which is the best operating system documentation anyone is currently writing, and which assumes exactly the system you are about to build.

It is a rolling release, so there are no version upgrades to schedule and no six-month cliff where everything moves at once. pacman is fast and legible, and pacman -Qe will tell you the complete list of packages you explicitly asked for – which turns out to be most of what you need in order to rebuild a machine.

What Arch does not give you is any guarantee that two machines built from the same instructions are the same machine. The running system is the source of truth, it drifts, and nothing but your own discipline records how it got that way. That is the real trade, and it is the one this book is organized around.

Declarative, or reproducible?

Those two words get used as though they meant the same thing. A declarative system is built from its configuration; a reproducible one is one you can get back to. For servers and for dotfiles I want the first, and NixOS with Home Manager is the best answer anyone has – which is why the dotfiles in this book are still defined in Nix.

A workstation is where I part company, because declaring a machine means knowing it first, and on hardware you have not met you do not: the firmware is odd, the WiFi chip is a surprise, the kernel turns out to be a vendor one. Arch lets you find that out on the machine and write it down afterwards. On a new and unexplored box that makes it the more reproducible of the two – discovery comes first, and the host repo records what you found.

None of that is a reason to stay. If you can spare the disk – the Nix store only grows, and every generation you keep grows it further – NixOS is probably the better platform for a machine you mean to keep for years: upgrades are atomic, a bad one rolls back, and the configuration outlives the hardware it describes.

The install is a command, and a file

The official Arch install is a long sequence of commands typed into a live system, and most of the ways it goes wrong come from typing them: a value lost when an SSH session drops, a step run twice that should have run once, a command typed into the chroot that belonged outside it. This book does not ask you to type them. It uses setup, an installer that ships on the BOOMSTICK and runs those commands for you, in order, from a small description of the machine:

setup host      # describe the machine
setup disk      # partition, format and mount it
setup install   # install, make it boot, network, accounts, SSH
setup reboot    # check everything, then reboot

and, for the rest of the machine’s life, one more command:

admin diff      # what changed on the machine that the repo does not say?
admin save      # write it into the repo, for you to review and commit
admin apply     # make the machine match the repo again
admin upgrade   # pacman -Syu, snapshotted, then apply

Be clear about what that trades away. setup is a long bash script – some fourteen hundred lines – and it makes a great many choices on your behalf, most of which you will never look at. In that sense it is a box you are asked to trust, and this book no longer walks you through every command it runs. What it does instead is keep the box open:

• It prints every command before it runs it, so its output is a transcript of exactly what was done to the machine.
• Everything it leaves behind is plain text: the host repo, and the aconfmgr configuration that describes the machine, are files you can read, diff and change.
• The pages that follow explain each stage – what it is for and why it is there – rather than what to type.
• It is one file, so when you do want to know exactly how something is done, less $(which setup) answers it.

That is less than a literate install, where you type every command and understand each one as you go. It is more than an installer you cannot read, and it does not mistype.

The description it works from is a small git repository, the host repo: a file of answers (hostname, disk, encryption, time zone), a package list, a list of services, and the handful of files that go under /etc. It holds no secrets, and it ends up inside the installed machine, where it is the record of how that machine was built – and, through admin, of every change made to it since.

What you end up with

The core of this book builds a minimal, headless base system: a partitioned and formatted disk, a bootloader, networking, your user accounts, SSH and sudo. That base is deliberately the same work on a desktop PC as on a Raspberry Pi, and it is a perfectly good stopping point if what you wanted was a small server.

On top of that base it is kept maintainable: aconfmgr compares the machine with its host repo in both directions, and snapper takes a btrfs snapshot before and after every pacman transaction.

The graphical desktop comes after that, as its own optional chapter, built on top of that base: sway from Arch, and the user’s environment from Nix and Home Manager.

Create your own custom installer

This is your BOOMSTICK!

Before any of that can happen, you need a way in. So the book starts one step earlier than the install, by building the installer: BOOMSTICK, an Arch live USB that joins your WiFi, brings up a WireGuard tunnel to your own server, and lets you in over SSH with your own keys. It is also where setup lives.

Write one and fill it in – that is the next chapter – and the target machine needs nothing but power and a USB port. No monitor, no keyboard: you plug the stick in, power on, and get a root shell over SSH from your own desk. Everything after that is setup.

Hardware this book covers

• x86_64 PCs, booting UEFI. Legacy BIOS is not covered.
• Raspberry Pi 5, which is the same work with a different bootloader and kernel. setup detects which one it is running on, and where the two differ, this book says so in place.

Where this book sits among the others

• NixOS Workstation – the same goal, built declaratively. If you want the machine described in code and rebuilt from that description, read that one instead.
• Linux Workstation – an older, archived book covering the same ground on Fedora Atomic. It is no longer maintained, but its Solokey hardware-key chapters carry over to any distribution.

This book is written with AI

I write this book with the help of AI, and I would rather say so plainly than pretend otherwise. If that bothers you, that is fine – I am not writing for that objection.

I do it because it makes the book a malleable product. The hard part of documentation has never been producing prose; it is keeping the prose true as the system underneath it changes. On a rolling release that pressure is constant: commands, package names, and defaults move under you. AI lets me revise the affected chapters quickly and keep everything consistent, instead of letting pages quietly rot. A book that is cheap to update is one that stays correct.

What matters here is the information and the flow: that the steps are accurate, that they are in the right order, and that the reasoning behind them is clear. Hitting a particular literary tone or vibe is not the point. I review what goes in, the decisions and the setup described are genuinely mine and what I run, and the goal is simply that you can follow it and end up with a working machine.