RigForge v1.1.0

RigForge turns a fresh Ubuntu/Debian machine into a fully tuned XMRig mining worker in one command. v1.1.0 is the first release with user-facing changes since v1.0.1 — the headline is a default change that makes a stock rig pair with a Pithead dashboard out of the box, plus a round of supply-chain/CI hardening.

Validated end to end on a real Ryzen 7800X3D rig — full provision → mine → tune → uninstall gate, connecting to a live pool and submitting accepted shares.

Highlights

Worker HTTP API is open (read-only) by default (#125)

ACCESS_TOKEN no longer defaults to the rig name. Left unset, the rig's :8080 API is served restricted (read-only) with no token — matching Pithead's default no-auth stats probe, so a stock rig shows up on the dashboard with zero token coordination.

• Want it token-gated? Set ACCESS_TOKEN to require a Bearer token, and match it on the dashboard (workers.api_auth: token / name).
• Mining solo? The API still binds the LAN for the dashboard — firewall :8080 off if you don't run Pithead (see SECURITY.md).
• Pairs with pithead #171 / #172.

Supply-chain & CI hardening (#117, #118, #119)

• Secret scanning & workflow auditing — gitleaks over the full history (plus a pre-commit hook), Dependabot to keep the pinned GitHub Actions current, and zizmor auditing the workflows against the GitHub Advisory Database on a weekly schedule.
• Config/docs lint — .editorconfig, pre-commit orchestration, and yamllint / markdownlint gates, with a scheduled link-checker.
• Licensing — CONTRIBUTING.md now states inbound contributions are MIT-licensed.

Fixed

• Live tuning works under the new open-API default. Every live-hashrate read — autotune and its monthly timer, tune --live, tune --confirm, and the upgrade re-tune — sent an Authorization: Bearer header. With the API now open and untokened, that empty Bearer drew a 401 and aborted the read, silently breaking live tuning on a stock config. The header is now sent only when ACCESS_TOKEN is set, with a regression test covering the real request path.

Upgrading from 1.0.x

Drop-in — config.json and the CLI are unchanged. The only behavior change is the API default above: if you relied on the token defaulting to the rig name, set ACCESS_TOKEN explicitly and update the Pithead side to match. sudo ./rigforge.sh upgrade rebuilds only if the XMRig pin moved; no reboot is needed just to take this release.

Install

git clone https://github.com/p2pool-starter-stack/rigforge.git
cd rigforge && chmod +x rigforge.sh
sudo ./rigforge.sh

Or download a bundle below. Full walkthrough — prerequisites, the Linux reboot, verification — in Getting Started.

Verify the download

sha256sum -c SHA256SUMS

File	SHA-256
rigforge-v1.1.0.zip	19d8ae0564f92a5e4244ce5fa4e361cc116e5600998e9ff3bf2cb8b4b8ae7d06
rigforge-v1.1.0.tar.gz	ce4d6a538bdf4d805ba56a45efce05355854b2232af188f9c7a7e5f17b57e011

---

Full changelog: CHANGELOG.md · v1.0.1...v1.1.0

RigForge v1.0.1

Fixed

• HugePage sizing is now NUMA-aware (1 GB pages) (#111). RandomX fast mode keeps a NUMA-local copy of the
  ~2080 MB dataset per NUMA node, but the reservation math multiplied the per-dataset 1 GB pages by the
  socket count, not the NUMA-node count. On a single-socket, multi-NUMA CPU — e.g. an EPYC 7642 with 4
  NUMA nodes — setup reserved 3× 1 GB instead of 12×, so after a reboot three of four nodes lost 1 GB
  backing and hashrate dropped hard. Sizing now scales the 1 GB reservation (and the pure-2 MB fallback)
  by NUMA nodes, detected via lscpu then /sys/devices/system/node, falling back to the socket count.
  2 MB scratchpad sizing is per-thread total and unaffected. Verified on a 4-NUMA EPYC (now reserves 12).

RigForge v1.0.0

⚠️ Superseded by v1.0.1 — please use that instead.

v1.0.0 has a HugePage-sizing bug on multi-NUMA CPUs (e.g. EPYC, multi-socket). A fresh setup
reserves 1 GB HugePages for a single RandomX dataset copy instead of one per NUMA node, so
after a reboot the other NUMA nodes lose 1 GB backing and hashrate drops. Single-NUMA CPUs (most
desktop Ryzen/Intel) are unaffected, but everyone should use v1.0.1, which fixes it
(#111).

---

First stable release. RigForge turns a fresh Ubuntu/Debian (or macOS) machine into a fully tuned
XMRig mining worker in one command — it compiles stock, upstream
XMRig from a pinned, commit-verified source, applies kernel- and CPU-level tuning for maximum RandomX
hashrate, and runs it as a managed service. Point it at any RandomX Stratum pool and walk away.
MIT-licensed, and validated end to end on a real Ryzen 7800X3D rig.

What you get

• One-command setup. sudo ./rigforge.sh installs the build toolchain, compiles XMRig, tunes the
  kernel and CPU, writes a config from your pool URL, and starts a managed service. Idempotent and
  safe to re-run.
• Real, measured gains. Mining live on a Ryzen 7800X3D: +3.5% hashrate and +7.6% efficiency over
  stock XMRig — faster and cooler, because HugePages stop the CPU stalling on memory. On a 48-core EPYC
  the gap is +6.6%, where the per-CPU live tune also dodged a prefetch setting that halves RandomX
  on that chip. Method and honest caveats in Benchmarks.
• Tuned for your CPU. Builds on XMRig's cache-aware auto-detection (threads, asm, MSR, NUMA) with
  dedicated-miner defaults; tune then searches the fastest knobs for your exact silicon, and opt-in
  autotune keeps it dialed in on a monthly, hands-off schedule.
• Simple to run. doctor (one-stop health check), status / logs / start / stop / restart,
  apply (apply a config edit, no rebuild), upgrade (rebuild when the XMRig pin moves), and
  backup / restore.
• Any RandomX pool — solo, P2Pool, or a public pool like SupportXMR — and it's the companion miner
  for Pithead if you run a stack.

What it does to your machine — and how to undo it

RigForge runs as root, so here is exactly what you are getting into:

• It is not a custom miner. It builds stock upstream XMRig at a pinned commit that is verified
  against a hardcoded hash before it compiles — the same binary you would build yourself, minus the
  fiddly setup.
• No telemetry, ever. The only outbound traffic is your pool, that XMRig clone from GitHub, and your
  distro's package mirrors. No analytics, no version ping, no beacon.
• Honest 1% dev fee. XMRig's donation is left at its 1% upstream default and goes to the XMRig
  project — RigForge substitutes no wallet of its own into the mining path. Set "DONATION": 0 to turn
  it off entirely.
• System changes, all reversible. A systemd service, GRUB HugePage kernel parameters (one
  reboot required on Linux), MSR module access, fstab / limits entries, a cpupower performance
  governor, and a read-only, token-gated stats API on :8080 that binds the LAN for the Pithead
  dashboard — firewall it off if you mine solo (see SECURITY.md). uninstall reverts
  every one of these and keeps your config.json.

Platforms

Ubuntu 22.04+ / Debian 12 is the supported target; other apt/dnf/pacman distros work as a courtesy.
macOS is supported for development and light use — it builds and configures, but does no kernel tuning
and installs no service.

Get started

git clone https://github.com/p2pool-starter-stack/rigforge.git
cd rigforge && chmod +x rigforge.sh
sudo ./rigforge.sh

The full walkthrough — prerequisites, the Linux reboot, and verification — is in
Getting Started.

Full 1.0.0 feature list — every capability and hardening that went into this release

Added

• Privacy & security, documented up front (#109). A new README "Privacy & security" section and a
  SECURITY.md "What RigForge exposes (and what it doesn't)" section state it plainly: no telemetry (the
  only outbound traffic is your pool, the commit-verified XMRig clone, and your distro's package mirrors);
  an honest 1% dev fee that is XMRig's own upstream default and is turned off with "DONATION": 0; and
  a read-only, token-gated stats API on :8080 that binds the LAN for the Pithead dashboard — with the
  exact ufw commands to firewall it off when you don't run Pithead.
• Release gate covers the live auto-tune engine, the periodic-tune timer, and every verb alias (#110).
  The real-hardware gate (tests/e2e-real.sh) now drives autotune — the live prefetch sweep the monthly
  timer runs — against the running miner, asserts the autotune timer install and teardown, and
  exercises the up/down, -v/--version, -h/--help aliases, closing the gaps where the gate
  claimed "every verb" but skipped these.
• Docs: benchmarks — measured stock-vs-tuned results on two CPUs. A new Benchmarks
  page (and a README highlight) reports hashrate and efficiency (H/s per watt) for stock XMRig vs.
  RigForge, measured mining live on a desktop Ryzen 7800X3D (+3.5% H/s, +7.6% efficiency) and a
  48-core EPYC 7642 (+6.6% / +6.0%). On the EPYC RigForge also matched an operator's hand-tuned
  config and the per-CPU live tune avoided a landmine — prefetch mode 2 halves RandomX on the EPYC
  but wins on the X3D, which a fixed profile would get wrong. Honest caveats included (Transparent
  HugePages narrow the stock gap on modern kernels; efficiency and performance tuning converge because
  RandomX power is ~flat across configs on both chips). No code change.
• tune --now --short / --long — pick the depth of an on-demand live re-tune. tune --now (now
  also spelled --short) stays the quick prefetch-only pass the scheduled timer runs; tune --now --long
  runs the full all-knob live sweep (prefetch, cpu.yield, thread count, 1G-pages) against the running
  miner — the same search as tune --live, which remains as an alias. This gives one mental model for
  on-demand tuning: tune --now with a --short/--long depth, instead of remembering --now vs
  --live. (Offline tune / tune --bench is unchanged — fastest and cleanest, but rx/0 only; the live
  --long is the one to use when you mine a non-Monero RandomX variant whose algorithm --bench can't
  measure.)
• Docs: connecting to a public pool (SupportXMR, etc.). Configuration › Pools
  now has two side-by-side, copy-paste recipes — a Pithead stack vs. a public pool — so it's obvious what
  to put where. The public-pool one spells out the one thing that trips people up: your Monero wallet
  goes in pools[].user (the pool pays whoever logs in), plus a worker name in pass and the pool's
  TLS port with "tls": true. Discoverability links added from the README, the docs index, Getting
  Started, and the FAQ; the pool-field reference is no longer framed as Pithead-only. No code change.
• Docs: stratum authentication against a Pithead stack. Pithead can now require a stratum
  password (p2pool.stratum_password); when it's on, a rig must send the matching pool pass or the
  proxy rejects it (Permission denied). Pithead Integration
  and the pass config reference now explain how to set
  it — no code change, the existing pools[].pass field carries the secret. Added tests asserting a
  Pithead-style password (hex and ._:@- literals) flows through verbatim and an invalid pass (with a
  space) is rejected.
• tune --history — a readable summary of this rig's tuning: the winning tune options applied
  right now (from tune-overrides.json), the last full tune run (target, best H/s, candidates tried),
  and — on Linux — the periodic auto-tuner's schedule, next scheduled run, and recent keep/rollback
  decisions (from the systemd journal). Read-only and best-effort; works without a built worker and
  degrades gracefully when nothing's been tuned yet.
• Optional rigforge command on your PATH. Set "add_to_path": true in config.json and setup
  installs a rigforge command — a symlink in /usr/local/bin pointing at the script — so you can run
  sudo rigforge doctor / tune / apply from any directory instead of ./rigforge.sh. The script
  resolves itself through the symlink, so the repo (config.json, util/, the worker build) is still
  found. Off by default — setup makes no system-wide convenience change you didn't ask for.
  Best-effort and idempotent: it never fails a deploy, won't clobber a non-RigForge file already at that
  path, and uninstall removes it.
• tune optimization target — raw hashrate vs. efficiency (#79). tune --efficiency (or
  TUNE_TARGET=efficiency) ranks candidates by hashrate-per-watt instead of raw H/s — for power-cost
  or heat/PSU-constrained rigs. The variance gate (#63) carries over proportionally, and efficiency mode
  requires a power source (built-in RAPL or TUNE_POWER_CMD), falling back to perf with a warning when
  none is available. The chosen target is recorded in rigforge-tune.json. Default stays perf.
• Periodic autotune target — disabled / performance / efficiency (#95). The ...