[Daniel-Parke]

Status (17 August 2026)

This PR is the whole of dev since main. The original v1.4 write-up below is
kept as-is. Everything that landed after it is in the sections at the end:
NVIDIA real-hardware testing, the four AMD-rig installer bugs, Intel labelled
untested, a NVIDIA retest after those AMD fixes, and the CI reversal-test fix.

Hardware tested by us: NVIDIA RTX 3090 Ti, AMD RX 7900 XTX, CPU /
--cpu. Intel Arc / Intel iGPU: not tested by us.

---

What this is

v1.4, the correctness release. 17 commits, 39 files, +13,740/-142.

Almost everything here is a fix to something already shipping. People are
downloading these scripts on the strength of the videos, and several of the bugs
below could cost them an evening.

Every external fact was checked against a first-party source on 15 August 2026:
the Hugging Face API, the upstream repository's own source, or the vendor's own
documentation. Where something could not be confirmed, it is marked unverified
rather than guessed.

---

The three that matter most

1. --models-max 0 meant unlimited, not none

The CPU path set --models-max 0 believing it was the restrictive value. From
llama.cpp's own common/arg.cpp:

maximum number of models to load simultaneously (default: 4, 0 = unlimited)

Three sites in tools/server/server-models.cpp treat <= 0 as no limit,
switching off the capacity check, LRU eviction and the idle queue. Since -c
applies per model and each model is a separate child process, this was unbounded
memory growth, on exactly the machines least able to survive it. Now 1
everywhere. The manual guide taught the same error and is corrected too.

2. The GPU was doing nothing on installs before 18 June 2026

LLAMA_VERSION defaulted to master. Until upstream tag b9702 the router
parsed -ngl, -c and --jinja and then silently discarded them
(ggml-org/llama.cpp#24760), so every model ran on upstream defaults with the
card idle. ?reload=1 likewise only exists from b9023. Now pinned to b10313.

3. The Odysseus clone address could have been taken over

pewdiepie-archdaemon/odysseus resolves only as a GitHub rename redirect over a
name slot that account no longer uses; its only remaining public repo is
dionysus. Had that name been reused, the installer would have cloned and run
python setup.py from whatever landed there, directly beneath a banner telling
users never to blind-run code from the internet. Now clones
odysseus-dev/odysseus and pins commit cf4e240a, since upstream publishes no
tags.

---

Also fixed

• Re-running destroyed hand-edited service files. The guide tells users to
  edit them (Step 10 adds an API key, Step 11 changes the bind address) while the
  installer promised re-running was safe. Both could not be true. Units are now
  checksummed: ours get updated, yours get kept and backed up. --replace-units
  overrides.
• The Odysseus password was never captured. Upstream branches on
  sys.stdin.isatty(), which is true under the installer, so it took the
  interactive getpass path and never printed the line being grepped for.
  PatterOS now sets the password itself and writes it to a root-only file
  instead of printing it to the terminal.
• The firewall could lock you out. It allowed the OpenSSH profile (port 22 by
  definition) then force-enabled ufw. Anyone with sshd elsewhere lost access to
  their own machine. The real port is now read from sshd -T.
• Driver health was misread on non-English systems. Classification greps
  English words in nvidia-smi output, so a translated "mismatch" fell through
  to "broken" and triggered the reinstall the check exists to prevent. Now
  LC_ALL=C.
• --full could run a card out of memory. It claimed to need 24 GB and
  checked neither card nor disk, then downloaded ~26 GB. The Part 1 BOM sells an
  8 GB card. Disk and VRAM are now checked first, and -ngl is computed from the
  actual card instead of hardcoded to 999. Override with NGL=<n>.
• Downloads reported success when nothing arrived. Now verified for existence
  and plausible size, with a huggingface-cli fallback when hf is absent.
• The uninstaller exited 1 on success and 0 on a dry run, exactly backwards,
  because its last statement was a bare [[ "${DRY}" == "yes" ]] && warn.
  Confirmed pre-existing against unmodified main.
• The uninstaller assumed default ports, deleting rules never added and
  leaving the user's real ports open. It now reads them back from the installed
  units.
• The uninstaller left users in groups PatterOS added. It now removes them,
  and only the ones it recorded adding, so a pre-existing video membership
  survives.
• Download verification could check the wrong file. After each download the
  installer confirmed a file had arrived at a plausible size, but it searched
  ~/models for anything matching the quantisation glob and took the first
  result. Every model matches that glob, so with more than one present it could
  size-check a different file and report a perfectly good download as
  incomplete. Found by the new tests, on CI rather than locally, because it
  depends on the order find returns entries.
• The error trap claimed "nothing else was changed", which was untrue by the
  time most errors fire.

Added

• A pre-install hardware check. Shows the detected processor, graphics card,
  memory and free disk and asks for confirmation, so a wrong detection is caught
  while that is still free. States plainly that the driver step is the one part
  carrying real risk, and that nothing has changed yet. Wording adapts to
  --skip-drivers. Skipped under -y.
• AMD Vulkan health checks. Resizable BAR disabled in BIOS roughly halves
  throughput and looks like nothing is wrong (Misc. bug: Vulkan - slow token generation with AMD DGPU Resizable BAR disabled ggml-org/llama.cpp#27097 measures
  37.09 to 13.89 t/s on an RX 7900 XTX). PatterOS now detects it, works around it
  with GGML_VK_DISABLE_HOST_VISIBLE_VIDMEM=1, and names the real BIOS fix. Also
  warns below Mesa 25.2 and when AMDVLK is in use instead of RADV.
• The Part 2 manual setup guide and the Local AI Handbook, in docs/. The
  installer prints "see the guide, Step 10/11/12" and those numbers were correct,
  but they resolved against a Word file that existed only on the maintainer's
  machine. A novice cloning the repo had nothing to open.
• The Part 3 model comparison tests, at docs/model-tests/, with the method,
  the prompt, and the caveats needed to read them honestly.
• A test suite: 25 assertions, and CI.

Changed

• Models switched to the Gemma 4 QAT builds, 0.6 to 1.6 GB smaller each at
  the same UD-Q4_K_XL level, which matters on the 512 GB drive the Part 1 build
  specifies, and matching what the Part 3 tests actually measured. All four repos
  verified: each resolves, each is Apache 2.0 and ungated, each has exactly one
  file matching the glob. Note the casing differs (12B, not 12b). No
  quality claim is made between QAT and standard at the same quantisation,
  because no first-party comparison exists.
• The installer is install_local_ai.sh everywhere. The header, banner, help
  and both die() messages called it setup_local_ai.sh, which is not the
  file's name. The file keeps its name because the Part 2 video description links
  to it directly; everything else was aligned to the file.
• show_help() reads to a sentinel rather than sed -n '2,51p'. Counting
  lines meant any header edit silently truncated the help or spilled code into
  it, and this PR adds header lines.
• The Part 1 BOM guide corrected in place by tools/patch_part1_docx.py,
  because the Part 1 video links to that exact path. 10 paragraphs changed, all
  210 paragraphs and 16 document parts intact, and the tool is idempotent so CI
  uses it as a staleness check. Corrections: ports 8080/7860 to 8020/7000,
  Unsloth Studio to Odysseus, ROCm to Vulkan twice, the multi-GPU claim removed,
  install.sh renamed and "coming soon" dropped, and the YouTube-Repo link
  repointed in both the visible text and the underlying hyperlink relationship.
• The duplicate Budget Build Guide/ tree removed. Git confirmed both script
  copies were the same object. Nothing lost: all nine Part 3 files are
  byte-identical at their new path and the prompt is reproduced verbatim.
• LACT to v0.10.0. Versions matched at v1.4. 44 em-dashes removed for house style.

Removed

• The reference to a "full PatterOS install.sh" holding the heavy provisioning.
  No such file has ever existed; it was an aspiration from the Part 1 guide that
  reached shipped code.

---

Why ROCm was not adopted for AMD

Worth recording, since it was actively considered. Vulkan stays, because on
gfx1100 it is faster for token generation: roughly 167 to 195 t/s against
ROCm's 122 to 167 t/s on llama-2-7b Q4_0, across three first-party llama.cpp
sources (discussions #10879 and #15021, issue #20934). ROCm also does not support
Linux Mint at all, wants ~100 GB free by AMD's own guidance, drops RDNA 2 consumer
cards entirely, and its --usecase=rocm,graphics path plus amdgpu-dkms can
take out the user's desktop graphics.

ROCm is still required for ComfyUI, which has no Vulkan backend, so it will
appear later as an opt-in for image and video generation only. The Part 2 video
chapter "Why Vulkan instead of ROCm" remains correct.

---

Testing

Check	Result
shellcheck 0.9.0 and 0.11.0, --severity=style	clean
bash -n, all scripts	pass
test_install_paths.sh, 10 hardware scenarios	61/61
test_docs_consistency.sh	9/9
test_unit_preservation.sh	8/8
test_uninstall_reversal.sh	8/8
Generated units, via systemd-analyze verify	valid
Part 1 docx staleness	not stale
Secrets scan, every blob in history	clean

86 assertions, all running in CI on every push.

The installer is now actually executed, not just linted. tests/harness/stubs.sh
puts fake external commands on PATH; the installer itself is unmodified, so the
branching, the decisions and the service files are all real. That makes the
paths nobody can safely test for real testable:

• A mismatched NVIDIA driver. Asserts it does NOT reinstall and asks for one reboot.
• A genuinely absent driver. Asserts it does install.
• An 8 GB card asked to hold the --full tier, largest model 17.3 GB. Asserts a
  partial offload is computed rather than claiming 999 layers fit. It chose 23.
• Resizable BAR off. Asserts the workaround reaches the service file.
• SSH on 2222. Asserts the rule is added BEFORE ufw is enabled.
• 4 GB free disk. Asserts it refuses before downloading anything.
• Mesa 24.0.5 and AMDVLK. Asserts both are called out.
• CPU only. Asserts --models-max is 1 and never 0.
• A second run. Asserts an identical service file.

Three bugs in the tests themselves were found and fixed while writing them,
including one where the has/hasnt helpers already pass -- to grep, so a
second -- at the call site became the search pattern. Seven assertions were
matching "--" rather than what they claimed, and several were passing for the
wrong reason.

Still not tested on real hardware. Everything above runs in Ubuntu 24.04
containers against stubbed hardware. No GPU has executed any of this. The
computed -ngl path and the Intel paths in particular are unverified against
real silicon, and the Intel rows ship marked untested.

Notes for review

• PR docs(trademark): add PatterStage to the protected Patter* family #1 was closed rather than merged. Its two commits are ancestors of this
  branch and PatterStage is live in TRADEMARK.md and NOTICE; closing avoided
  two routes to main for the same commits.
• Three paths are load-bearing and must never move, because the video
  descriptions link to them directly:
  scripts/install_local_ai.sh, scripts/uninstall_local_ai.sh,
  docs/PatterOS_AI_Rig_BOM_and_Build_Guide.docx.
• Worth a human eye: the Part 1 .docx renders correctly in Word. The XML is
  valid and the paragraph count is unchanged, but the rendered formatting was not
  visually checked.

🤖 Generated with Claude Code

---

After the original v1.4 write-up

The body above was written before the installer had been run on real silicon.
What follows is the rest of this PR: NVIDIA hardware, the AMD-rig fixes, Intel
honesty, a NVIDIA retest that did not rewrite AMD paths, and the CI failure that
was blocking merge.

NVIDIA, on an RTX 3090 Ti (0727c95)

Ran the real installer twice under a throwaway user (patteros-test), never
against the live daniel account. --skip-upgrade --skip-firewall. Driver
595.71.05 left alone. CUDA build, express models, services started.

GPU was actually used: llama-server held 1788 MiB VRAM; Gemma 4 E2B generated
at 232 tok/s (later retest 236). Live model swap, ?reload=1, --models-max 1.
Host restored: units checksum-matched, ufw numbered ports matched, dpkg 2179/2179.

Bugs found by that run, all "the script said success while doing something else":

• Odysseus pinned commit crash-looped (NameError on a missing Any import);
  the installer now carries that one-line upstream fix and will not print a
  login URL for a workspace that is not answering.
• systemctl is-active was treated as health; a crash-looping unit is "active".
• --lact skipped its purge on a real package list (grep -q + pipefail +
  SIGPIPE, exit 141).
• Uninstaller announced firewall rules gone that were still there.
• Existing ~/llama.cpp ignored LLAMA_VERSION, so the GPU-offload pin never
  applied to people who had cloned by hand.
• Changing a setting rewrote the unit and left the old process running.
• A busy port 8020 was blamed on the NVIDIA driver, then reported healthy
  because something else answered on the port.
• CUDA compile jobs are now capped by free RAM (build_jobs()), so a 16-thread
  / 31 GB box cannot OOM the desktop mid-build; the service is stopped before
  build/ is deleted.
• --drivers / --packages only reverse what PatterOS recorded adding, and
  never purge mesa-vulkan-drivers.
• Default uninstall keeps Odysseus notes in a dated backup.
• Both scripts refuse a home of /.

Tests added for prompts (72), flags, and every uninstall flag. Reversal still
runs only in a disposable container.

AMD, on an RX 7900 XTX (e472e01)

Four real installer bugs, found on that card, plus stub coverage. These are
Vulkan/ReBAR/Mesa fixes. They do not change CUDA on a healthy NVIDIA box.

1. vram_gb() was blind unless mesa-utils happened to be installed. It
   asked nvidia-smi, then glxinfo. glxinfo is not in the base package list,
   so a machine that only has what this installer put on it has neither.
   Resizable BAR detection and partial -ngl both use that number, so an AMD
   (or Intel) card with ReBAR off, and an 8 GB card asked to hold a 19 GB model,
   both took -ngl 999 and skipped the workaround. The function now reads
   /sys/class/drm/card*/device/mem_info_vram_total when the two userland tools
   are missing. NVIDIA still uses nvidia-smi first and never reaches sysfs.

2. The graphics driver was reported as "Mesa Overlay". vulkaninfo --summary
   lists instance layers first, including Mesa Overlay layer. Matching
   /driverInfo|Mesa/ took that line. The parser now reads driverInfo only.

3. -y --replace-units said it had kept the edited unit, then replaced it.
   install_unit() printed "your version is kept" whenever -y was set, and
   only afterwards noticed --replace-units. Vendor-neutral.

4. --cpu --skip-build on an AMD Vulkan install stripped the ReBAR
   workaround from the live service. --cpu skipped PCI detection, so
   vulkan_health never ran, VK_ENV stayed empty, and the unit rewrite dropped
   GGML_VK_DISABLE_HOST_VISIBLE_VIDMEM and RADV_PERFTEST while still running
   the vulkan binary (-ngl 999). The card is still detected under --cpu; if
   the reused engine is vulkan, the workarounds are filled in before the unit is
   written. On NVIDIA, --cpu still sets VENDOR=cpu and builds the CPU engine.

Stub cases added: Mesa Overlay in vulkaninfo, glxinfo stub, AMD --cpu --skip-build keeps ReBAR/RADV, AMD 8 GB VRAM without nvidia-smi,
--replace-units wording.

Intel honesty, then NVIDIA retested (f30b0b6)

No Intel hardware in front of us, so we stopped implying it was supported.

• README hardware table: NVIDIA / AMD / --cpu tested; Intel Arc / iGPU
  untested by us. No bare "Yes" on the Intel row.
• Part 2 Path B no longer lumps "AMD or Intel" as "works on anything".
• Installer warn() when VENDOR=intel; --cpu still says "ignoring any
  graphics card".
• Docs-consistency asserts README, the guide, and the installer all say
  untested. Intel stub case prints the warning; NVIDIA and AMD cases do not.
• .tools/shellcheck (15 MB binary) removed from git; CI uses
  koalaman/shellcheck-alpine.

Then the same 3090 Ti was retested under patteros-test after e472e01,
without rewriting AMD paths:

Check	Result
Layer 0: bash -n, shellcheck 0.9.0 and 0.11.0 --severity=style, CRLF, docs, units, Part 1 docx	0 failures. Docs 14/14.
Stub suites, 180s each	paths 77/77, flags 169/169, interactive 72/72, uninstall_paths 146/146
Real CUDA install	Path A, driver 595.71.05 left alone, Engine built (cuda), -ngl 999, no Vulkan/ReBAR env on the unit
GPU after the AMD commit	llama-server 1788 MiB, 236 tok/s on E2B, live swap, ?reload=1, --models-max 1
--cpu on this NVIDIA card	Path C, no ubuntu-drivers, Engine built (cpu), -ngl 0, libggml-cpu only
Host restore	units checksum-matched, ufw matched snapshot, dpkg 2179/2179, patteros-test deleted

test_uninstall_reversal.sh is not run on a live workstation (it deletes
llama.service).

CI (4e29103)

Job install and remove round trip was red on every push after the firewall
honesty change, including e472e01. The reversal test grepped dry-run output
for 9100/9200. After the uninstaller only reported LAN rules that actually
existed, GitHub's ubuntu:24.04 container (no ufw) never printed those ports
even though read_port had the right numbers.

The uninstaller plan now names the ports recovered from the installed units
(LAN ports from the installed units: 9100 and 9200). The reversal test asserts
that string. The stubbed uninstall suite asserts it too. CI also installs
sudo, python3 and adduser, which the later steps in that job need once
reversal no longer fails first.

AMD paths were not rewritten for the NVIDIA retest or for this CI fix.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.