paradox / handbook
Everything paradox 0.5 does, what you type to make it do it, and an honest list of what it can't do yet.
You are reading the 0.5 handbook. If your machine reports a different version at login, use the handbook for that release — every version is documented on its own terms rather than as a list of changes.
paradox is a Linux distribution built with the Linux From Scratch method — every package compiled from upstream source rather than pulled from another distribution's archive. There is no Debian, no Arch and no Red Hat underneath it.
0.5 is the first release you can simply download. new in 0.5 Earlier versions existed, but you had to be us to get one.
The live image boots on both UEFI and legacy BIOS machines — an older BIOS-only box will start the ISO and run the installer perfectly well. The system it installs is UEFI-only. The installer writes a UEFI GRUB bootloader and nothing else, so on a BIOS-only machine you would complete an install that then refuses to boot.
Legacy BIOS installs need a 32-bit BIOS GRUB that the current build toolchain cannot produce. It is a known gap, not an oversight.
The 0.5 image is published and downloadable — the first one that is.
iso.paradoxlinux.com/0.5/paradox-0.5.iso (about 2.1 GB).sha256 on the end.sig on the endiso.paradoxlinux.com/latest.txt returns the current version, if you want to script itThis is worth being clear about, because it is easy to misread as a paradox step. It is not. You run these commands on the machine you downloaded to — your existing Mac, Windows or Linux computer — right after downloading and before writing the USB stick. You do not have paradox yet at this point, and the installed system is identical whether or not you bother.
Two checks, doing two different jobs:
You need gpg and sha256sum on that machine. Both are built in
on Linux and macOS. On Windows, use something like Gpg4win, or just do the checksum.
# import the paradox signing key $ curl -fsSL \ https://repo.paradoxlinux.com/paradox-linux.gpg \ | gpg --import # check the file arrived intact $ sha256sum -c paradox-0.5.iso.sha256 paradox-0.5.iso: OK # check it is genuinely ours $ gpg --verify \ paradox-0.5.iso.sig paradox-0.5.iso gpg: Good signature from "paradoxadmin"
Key 0956915D16CAA24F signs the image and every package in the repository.
Import it first, or the signature check fails with an unhelpful error. gpg will also warn
that the key is not certified by anyone you trust — expected, not a failure.
"Good signature" is the line you want. "BAD signature" means throw the file
away.
Also on your own machine:
$ sudo dd if=paradox-0.5.iso \ of=/dev/sdX bs=4M status=progress
On Windows, Rufus in DD mode does the same job. Check /dev/sdX twice —
dd will overwrite whatever you point it at without asking.
Write the image to a USB stick, boot it, and the menu offers two things: install paradox linux, which drops you straight into the installer with no login and no typing, and try paradox live, which gives you the whole system running from the stick.
The installer runs full-screen in the console, and every step clears the screen and redraws — so you only ever see the question you are answering, never a thousand-line scroll with a password prompt buried at the bottom. Nothing is written to disk until you type YES. Ctrl-C quits safely at any point before that.
firmware mode: UEFI this installs paradox linux onto disk(s) you choose. nothing is written until you type YES to confirm. ctrl-c quits safely. press enter to begin ›
0.5 turned "pick a disk" into a proper storage step. Choose a layout first.
⟲ the paradox installer aurora · 0.5 ──────────────────────────────────────────────────── step 1 · storage layout how should paradox lay out your root disk(s)? 1 single disk one disk, straightforward 2 RAID1 · mirror two disks, survives one failing 3 RAID0 · stripe two disks, faster, no safety net 4 RAID10 · 4 disks speed and redundancy pick a layout [1-4, default 1]:
Then pick the disks. A RAID layout asks for each one in turn and won't let you choose the same disk twice.
⟲ the paradox installer aurora · 0.5 ──────────────────────────────────────────────────── step 1 · pick disk(s) choose the 2 disks for your RAID1 mirror: 1 /dev/sda 500.0 GiB Samsung SSD 860 2 /dev/sdb 500.0 GiB Samsung SSD 860 3 /dev/nvme0n1 1.0 TiB WD Blue SN570 pick the FIRST disk [1-3] (q to quit): pick the SECOND disk [1-3] (q to quit): … everything on /dev/sda /dev/sdb will be erased. press enter to continue ›
If any disks are left over, the installer offers to make them into extra storage. This
screen only appears when there is something spare, and it loops until fewer than two
disks remain — so you can build several volumes in one pass. Each gets its own mount
point, defaulting to /data, then /data2, and so on. new in 0.5
⟲ the paradox installer aurora · 0.5 ──────────────────────────────────────────────────── step 1 · additional storage 1 unused disk(s) left — add them as extra storage? /dev/nvme0n1 1.0 TiB 1 no, done leave the rest unused 2 one disk · plain ext4, no RAID pick [1-2, default 1]: mount point [/data]: ✔ plain disk → /data across /dev/nvme0n1
Encryption and swap come last. The encryption prompt only appears for a single-disk root — on a RAID layout it prints a note that full-disk encryption is single-disk only for now and moves on. Swap is asked for separately in GiB, and 0 means none; on a RAID install a nonzero swap is built as its own array at the same level as the root.
⟲ the paradox installer aurora · 0.5 ──────────────────────────────────────────────────── step 1 · encryption + swap encrypt the root disk with LUKS2? [y/N]: encryption passphrase: confirm : … you'll type this passphrase at every boot. there is no recovery if lost. swap size in GiB [0 = none]:
Keyboard, account, timezone and locale, each on its own screen. The keyboard comes first on purpose, so a non-US layout is live before you type a password into it.
⟲ the paradox installer aurora · 0.5 ──────────────────────────────────────────────────── step 2 · keyboard keyboard layout: 1 US English (QWERTY) 2 UK English 3 US Dvorak … (11 built-in layouts) 12 other — type a keymap pick a keyboard [1-12, default 1]:
Then the account — hostname, your single admin username, and the password, alone on a clean screen.
⟲ the paradox installer aurora · 0.5 ──────────────────────────────────────────────────── step 2 · account hostname [paradox]: username [pdxadmin]: password: confirm :
Timezone and locale follow in the same shape: a numbered menu of common choices, with a final "other" option if you want to type something exact.
Everything the installer is about to do, on one screen, before anything happens. This is the last moment nothing has been written.
⟲ the paradox installer aurora · 0.5 ──────────────────────────────────────────────────── step 3 · confirm storage RAID1 mirror — /dev/sda /dev/sdb layout GPT — ESP 1 GiB (fat32) + root (ext4) encryption none swap 8 GiB data plain — /dev/nvme0n1 → /data (ext4) hostname paradox user pdxadmin (wheel/sudo), root disabled locale en_US.UTF-8 · tz America/New_York · kbd us this erases /dev/sda /dev/sdb /dev/nvme0n1. type YES to install:
It partitions, builds any arrays, formats, copies the system, installs a UEFI GRUB bootloader, and sets your identity and localization. The copy is the long part.
⟲ the paradox installer aurora · 0.5 ──────────────────────────────────────────────────── step 4 · installing onto /dev/sda /dev/sdb clearing any previous layout on the target disk(s)… ✔ partitioned ✔ array(s) created (RAID1 mirror) ✔ additional storage ready ✔ formatted copying the system (this is the long part)… ✔ system copied ✔ bootloader installed ✔ identity set (single admin: pdxadmin) ✔ localization set ✔ done ✔ paradox linux is installed on /dev/sda /dev/sdb. mirrored — it survives one disk failing. data volume /data is ready, owned by pdxadmin. remove the installer media, then reboot. [r] reboot now [s] drop to a shell :
The installer renames the live account to the username you chose, so the installed system has exactly one administrator, at uid 1000, in the wheel group, with the password you set. There is no leftover account carrying a factory password, root login is disabled, and the live session's auto-login is stripped during the install.
0.5 can put the root filesystem on software RAID, and turn whatever disks are left over into storage.
Every disk in a RAID root gets its own EFI partition, set up identically, so any surviving disk in a mirror can boot the machine on its own. That is the part people usually discover they were missing at the worst possible moment.
Asked separately, in GiB, with 0 meaning none. On a RAID install a nonzero swap becomes its own array at the same level as the root — mirrored root, mirrored swap.
After the root disks are chosen, any remaining disks can be set up as separate
storage, one group at a time. Each gets its own mount point, defaulting to
/data, then /data2, and so on.
Each volume is formatted, added to /etc/fstab, mounted, and handed to
your admin account — so it is writable the moment you log in, with no chown dance.
user@host:~$ df -h /data Filesystem Size Used Avail Use% Mounted on /dev/md2 1.8T 28K 1.7T 1% /data user@host:~$ cat /proc/mdstat md0 : active raid1 sda2[0] sdb2[1] [UU]
Arrays are recorded in /etc/mdadm.conf, so they assemble themselves at
every boot.
An install can be encrypted with LUKS2 — full-disk, set up during installation, built from source like everything else.
Say yes at the encryption prompt, choose a passphrase, and the root filesystem is created inside the encrypted volume. At every boot after that the machine asks for the passphrase on screen, before anything else loads.
The prompt only appears if you chose a single-disk root. Pick any RAID layout and the installer says so and moves on — encryption and RAID cannot be combined in 0.5.
enter passphrase for cryptroot:
There is no recovery. The installer sets one passphrase and nothing else — no recovery key, no backup keyslot, no way for us to help you. Forget the passphrase and the data is gone. That is what full-disk encryption means, and it is worth being sure you understand it before you type YES.
LUKS2 supports several keyslots, so once the system is installed you can add a second passphrase or back up the header yourself:
user@host:~$ sudo cryptsetup luksAddKey /dev/sda2 user@host:~$ sudo cryptsetup luksHeaderBackup /dev/sda2 \\ --header-backup-file luks-header.img
Keep that header backup somewhere that is not the encrypted disk. The installer does not do either of these for you.
The installer now asks for these instead of assuming a US keyboard in UTC, which was fine for us and irritating for everyone else.
Each is a numbered menu with an "other" option if what you want is not listed. Change your mind later with the usual tools:
user@host:~$ sudo nano /etc/vconsole.conf # keyboard user@host:~$ sudo timedatectl set-timezone Europe/Berlin user@host:~$ sudo nano /etc/locale.conf # language
Picking try paradox live gives you the whole system running from the USB stick, with nothing written to any disk.
It logs you in automatically as pdxadmin — no password needed to reach
the shell — and the prompt tells you how to install if you change your mind:
pdxadmin@paradox:~$ sudo paradox-install
That one command needs no password in the live session. Anything else you run with
sudo will ask, and the live account's password is the image default,
paradox.
This auto-login is live-only. It is removed during installation, so an installed disk never inherits it. If you find yourself dropped at a shell with no login on a machine you installed, something has gone wrong — that is not normal behaviour.
Because the root filesystem is a RAM overlay, everything you change in a live session is gone at the next boot. Good for looking around, bad for anything you want to keep.
Remove the installer media and reboot. On an encrypted install the passphrase prompt comes first; otherwise you go straight to the login.
The kernel is 6.18.10-pdx, built for paradox with the networking,
firewall, RAID, encryption and filesystem support the system relies on.
Boot is quiet by design. You will see very little before the login prompt, which is intentional rather than a sign something stalled.
paradox linux (aurora)
Kernel 6.18.10-pdx on an x86_64 (tty1)
paradox login: pdxadmin
Password:
reality is optional
aurora · 0.5
pdxadmin@paradox:~$
Log in with the username and password you set during the install. The system
identifies itself in /etc/os-release, which reads
VERSION="0.5 (aurora)" — the reliable place to check which release a machine
is running.
Every colour in paradox is deliberate. The rule the theme follows: the colours that tell you who you are stay separate from the colours that tell you what a file is, so nothing is ambiguous at a glance. The hostname is blue rather than cyan specifically so it is never mistaken for a directory.
Root and a normal user differ in exactly one way — the username colour. Yellow means you are root and should be paying attention.
pdxadmin@paradox:~$ whoami pdxadmin root@paradox:~# whoami root
ls is aliased to always use colour. The palette is the "aurora spectrum":
root@paradox:~# ls script.sh test_folder test.txt backup.tar.xz wallpaper.png
The MOTD is the wordmark, a divider, and the wordmark reflected and dimmed beneath it — which way is up. The banner is bright cyan and its reflection a dimmer cyan, reality is optional sits below in yellow, and the release line reads aurora in magenta beside the version in white.
Search matches highlight in magenta. nano is themed to match — cyan title bar with white text, cyan line numbers, bright cyan shortcut keys — and comes configured with line numbers, syntax highlighting, soft wrap, auto-indent, and 4-space tabs that insert spaces.
The Linux text console can only display 16 colours. The prompt and banner are written in 16-colour codes so they are exact, but the file listing palette uses 256-colour codes and will look approximate on the console. Over SSH or in a graphical terminal you see the real thing.
An installed 0.4 system has one administrator — the account you named during the install, at uid 1000, in the wheel group, which is what grants sudo.
Root exists but root login is disabled. Administrative work goes through
sudo, which asks for your password each time.
user@host:~$ id uid=1000(user) gid=1000(user) groups=1000(user),97(wheel)
The paradox- tools are run as your normal user — they ask for your
password themselves at the point they need it, rather than requiring you to remember a
prefix.
If you are running a live session rather than an installed system, the account
is pdxadmin with the password paradox. That account does not
survive the install.
Wi-Fi works. This is the headline of 0.3 and the thing that changes what paradox can be installed on — a laptop with no ethernet port is no longer a dead end.
Two commands cover almost everything. Both are run as your normal user, both figure out the hardware themselves, and both ask for your password only when they are about to change something.
Run it with no arguments and it scans, lists what it found, and connects to whichever
you pick. A network marked psk asks for its passphrase — typed blind, nothing
echoes back. Networks marked open connect straight away.
Once you have joined a network it is saved, so it reconnects on its own after a reboot and will not ask again.
pdxadmin@paradox:~$ paradox-wifi ↻ paradox-wifi scanning the airwaves on wlan0… 1 aurora-5G psk ●●●● (connected) 2 aurora psk ●●●● 3 nebula-guest psk ●●● 4 quasar_lab open ●●● 5 pulsar-2G psk ●● 6 corona_house psk ●● pick a network [1-6] (q to quit): 3 ↻ paradox-wifi connecting to nebula-guest… Passphrase for nebula-guest: (hidden) ✓ connected to nebula-guest radio wlan0 state connected network nebula-guest ip 192.168.10.36/24
The other things it does:
paradox-wifi status — radio, state, network and addressparadox-wifi --disconnect — drop the current connection but keep the network saved, so it reconnects next bootparadox-wifi --forget-networks — erase every saved network, so the machine stops connecting on its ownUnderneath it is iwd, which runs its own DHCP client — there is no
separate DHCP daemon to configure or fight with.
Wired ethernet uses DHCP out of the box and needs no attention. When you want a fixed
address — which on a machine running SSH you usually do — paradox-wired
walks through it and writes the systemd-networkd configuration for you.
pdxadmin@paradox:~$ paradox-wired 1 enp2s0 down 2 enp3s0 up 192.168.10.107/24 pick a nic [1-2] (q to quit): 1 ✎ paradox-wired static ip on enp2s0 ip address : 192.168.10.10 subnet (24 or mask) : 24 gateway (blank=none): 192.168.10.254 dns, comma-separated: 1.1.1.1,8.8.8.8 will write /etc/systemd/network/00-paradox-enp2s0.network: [Match] Name=enp2s0 [Network] Address=192.168.10.10/24 Gateway=192.168.10.254 DNS=1.1.1.1 DNS=8.8.8.8 … if enp2s0 is the link you're on, this can drop the session — reconnect on the new address. apply this? [y/N] y [paradox] password for pdxadmin: ✓ applied static 192.168.10.10/24 on enp2s0
paradox-wired status — list the wired interfaces and their addressesparadox-wired --dhcp — hand a port back to automatic addressingRead the warning it prints before answering yes. If you are connected over the port you are reconfiguring, applying the change drops your session and you reconnect on the new address — worth thinking about before doing this remotely over the only link you have.
The base ships firmware for the common Wi-Fi families — Intel, Atheros, Realtek, Broadcom, MediaTek and Marvell — along with wired NIC blobs, Bluetooth, Intel graphics and the wireless regulatory database, so most machines get online without hunting for anything. It is about 677 MB, and it is the reason a from-scratch distribution can be plug-and-play at all.
Everything else upstream ships — AMD and Nvidia graphics, server SmartNICs, audio and
SoC firmware — is available as linux-firmware-extra in the repository rather
than sitting unused in every install.
paradox now comes up firewalled on every boot. The policy is default-drop on input: unless a rule allows it, incoming traffic is discarded.
What is allowed:
Outbound traffic is unrestricted, and forwarding is off.
pdxadmin@paradox:~$ systemctl status nftables Loaded: loaded (nftables.service; enabled) Active: active (exited) pdxadmin@paradox:~$ sudo nft list ruleset
Default-drop means anything you host yourself is unreachable until you say otherwise. Start a web server, a game server or a database, connect from another machine, and it will simply hang — the service is running fine, the firewall is discarding the packets before they arrive.
Rules live in /etc/nftables.conf. Add a port alongside the existing SSH
line, then reload:
pdxadmin@paradox:~$ sudo nano /etc/nftables.conf tcp dport 22 accept tcp dport 8080 accept # check it parses before loading pdxadmin@paradox:~$ sudo nft -c -f /etc/nftables.conf pdxadmin@paradox:~$ sudo systemctl restart nftables
Check the file with nft -c -f before loading it. A syntax error in a
firewall you are editing over SSH is a bad way to end an evening.
Software is managed with paradox, a wrapper over the pacman package
engine. The verbs are themed; plain synonyms work identically, and any extra arguments
pass straight through.
| command | does | plain form |
|---|---|---|
| paradox glitch <pkg> | install a package | install |
| paradox collapse <pkg> | remove a package and its orphaned dependencies | remove |
| paradox shift | sync the database and upgrade everything | update / upgrade |
| paradox refresh | refresh the package database only | sync |
| paradox seek <term> | search the repository | search |
| paradox info <pkg> | show package details | — |
| paradox list | list installed packages | — |
| paradox help | print the menu | -h / --help |
Packages are served from a self-hosted repository at
repo.paradoxlinux.com, backed by Cloudflare R2. Each arrives as a
.pkg.tar.zst archive with a detached GPG signature, and
SigLevel = Required means an unsigned or badly signed package is refused
rather than installed.
The public key is published at
repo.paradoxlinux.com/paradox-linux.gpg. Verify it against the fingerprint
before trusting it:
0956915D16CAA24FD62E 8750 2D94 217B AAB7 6E21 0956 915D 16CA A24Fparadoxadmin <paradoxlinuxadmin@gmail.com>The private key lives only on the build host and is never shipped in the system.
Eighteen signed packages, up from one in 0.2. Everything is built from source with its own PKGBUILD rather than repackaged from elsewhere.
pdxadmin@paradox:~$ paradox seek tmux paradox/tmux 3.5a-1 pdxadmin@paradox:~$ paradox glitch tmux resolving dependencies... Proceed with installation? [Y/n] ✓ tmux 3.5a-1 installed
Downloads now go through curl rather than pacman's own sandboxed downloader, which was unreliable on some hardware — a change you will not notice except that transfers stop hanging.
linux-paradox is a signed package in the repository like anything else,
which is how future kernels will be delivered.
One honest caveat. The base system is hand-built rather than pacman-tracked, so
a stock 0.4 install still carries its kernel outside package management and
paradox shift will not pull a new one automatically. Moving the packaged
kernel onto an existing install is a deliberate manual step for now. Wiring the base
kernel into package management so shift upgrades it cleanly is now targeted
at 0.6.
The catalogue is thirty signed packages. new in 0.5 What 0.5 added is the machinery behind encryption and RAID — cryptsetup and its dependencies, and mdadm — rather than new everyday applications. Broader tooling is the plan for 0.6.
"No bloat" is only useful if you know what you actually have. This is the tour.
Everyday tools that used to be missing now build as signed packages and ship in the base:
nano, and only nano. vim is not installed. If you are a vi person that is the first thing you will want to change — and now that the repository has eighteen packages in it, building one is a reasonable request rather than a project.
No desktop, no display server, no audio stack, no printing, and no vim. Bluetooth firmware is present but nothing is configured to use it. Nothing runs that you did not start.
paradox runs systemd, so services and logs behave the way they do on any modern distribution. Only a handful of the enabled units are paradox's own choices rather than systemd defaults.
The rest are systemd's own presets: oomd, pstore, sysext, confext, udev credentials and the journald sockets.
pdxadmin@paradox:~$ systemctl status sshd pdxadmin@paradox:~$ systemctl list-unit-files --state=enabled pdxadmin@paradox:~$ journalctl -b -p err pdxadmin@paradox:~$ journalctl -u iwd -f pdxadmin@paradox:~$ sudo systemctl poweroff
Kept current for every release, because finding this out at eleven at night is worse than reading it now.
paradox shift does not replace the base kernel on an existing install — that is still a manual step, targeted for 0.6.Things that have actually caught someone out.
/proc/mdstat occasionally; [UU] is healthy, [U_] means a disk has dropped out.paradox-wired warns you before it applies.--disconnect keeps the network saved on purpose; use --forget-networks if you want it gone.root=PARTUUID=…./var/lib/pacman/db.lck; delete it before retrying./etc/ssl goes missing, downloads fail in ways that look like the network is down./usr/bin/paradox — the package manager wrapper/usr/bin/paradox-install — the installer, on the live image/usr/bin/paradox-info — system information/usr/bin/paradox-wifi · /usr/bin/paradox-wired — the network tools/etc/bashrc — the prompt, LS_COLORS, GREP_COLORS and the aliases/etc/motd — the mirror banner/etc/nanorc — the nano theme and behaviour/etc/os-release — version and identity/etc/pacman.conf — repositories and signature policy/etc/nftables.conf — the firewall ruleset/etc/iwd/main.conf · /var/lib/iwd/ — Wi-Fi config and saved networks/etc/systemd/network/ — wired configuration; paradox-wired writes 00-paradox-<nic>.network here/boot/grub/grub.cfg — the boot menu/etc/ssl/certs/ca-certificates.crt — the CA bundle/etc/mdadm.conf — RAID arrays, so they assemble at boot new in 0.5/proc/mdstat — live RAID status new in 0.5/etc/vconsole.conf · /etc/locale.conf — keyboard and language new in 0.5/etc/fstab — written by the installer, root by UUID, ESP at /boot/efiGPT with two partitions: a 1 GiB fat32 EFI system partition and an ext4 root. The
kernel command line is root=PARTUUID=… ro quiet loglevel=3.
The first release anyone can actually download, and the one where the installer grew up — encryption, RAID, data volumes and localization.
Unchanged from 0.4: the LFS base and toolchain, the single-wheel-admin model, systemd init, the custom 6.18.10-pdx kernel, and the colour and mirror theme.
The release where paradox learned to install itself — a hybrid live ISO and a guided installer, proven on real hardware but never published. Read the 0.4 handbook.
The release where paradox learned to get online anywhere — a custom kernel, Wi-Fi end to end, and a firewall at every boot. Read the 0.3 handbook.
The release where the package manager became real. Read the 0.2 handbook.
The first bootable state. Read the 0.1 handbook.
paradox shiftEvery version → — each release, its handbook, and whether an image exists