🔥 RigForge

Provision a hardware-tuned XMRig miner in one command.

RigForge turns a fresh Ubuntu/Debian (or macOS) machine into a fully tuned XMRig mining worker — it installs the toolchain, compiles XMRig from source, applies kernel- and CPU-level tuning for maximum RandomX hashrate, and runs it as a managed service. You point it at a pool and walk away.

It's built as the companion miner for the Pithead — connect as many RigForge workers as you like to your stack's single endpoint — but it works against any RandomX Stratum pool.

RigForge is not a custom miner. It compiles stock, upstream XMRig and wraps it in the setup, hardware tuning, and service management that are otherwise fiddly to get right by hand.

---

✨ What it does

• Automated setup — installs build dependencies (cmake, libuv, hwloc, …) and compiles XMRig from the latest source.
• Hardware-aware tuning — detects the CPU (e.g. AMD EPYC, Ryzen X3D) and applies a matching performance profile (NUMA binding, ASM, thread layout, MSR registers).
• Kernel & system tuning (Linux) — topology-aware HugePages (1 GB and 2 MB), MSR access for hardware-prefetcher control, and hugetlbfs mounts + memlock limits.
• Service management (Linux) — runs XMRig as a systemd service with a cpupower performance governor and automatic log rotation.
• Interactive config — if no config exists, it asks for the one thing it needs: your pool / stack hostname or IP.

---

🛠 Hardware Requirements

A worker is where the actual RandomX hashing happens, so its CPU is what determines your hashrate. The requirements themselves are modest — most of the performance comes from tuning, which this script applies for you.

Resource	Requirement	Recommended
CPU	64-bit x86 with AVX2 support	A high-core-count CPU (e.g. AMD Ryzen / EPYC) — more and faster cores mean more hashrate. The script auto-detects the CPU and applies a matching profile.
RAM	~2.3 GB free for RandomX fast mode — a 2080 MB dataset + 256 MB cache — plus ~2 MB of L3 cache per mining thread	4 GB+; budget more on high-core-count CPUs
HugePages	Optional, but a significant speedup	The script configures 2 MB and 1 GB HugePages (plus MSR access) for you — Linux only, and it needs a reboot to take effect
OS	Ubuntu 22.04+, Debian 12, or macOS	—
Network	Reach your pool / stack host on its Stratum port (Pithead uses 3333)	Local network; workers do not need Tor

RandomX light mode needs only 256 MB of RAM but is far slower — fast mode (the default) is what you want for real hashrate. These memory figures are from XMRig's own RandomX optimization guide.

Miner version

There's no required XMRig version — RigForge always builds the latest upstream XMRig, and any RandomX-capable XMRig (5.0+, 2019) speaks the standard Stratum protocol that Pithead's proxy and P2Pool accept. The stack's component versions don't dictate a miner version.

---

🔌 Connecting to a pool or stack

RigForge points XMRig at a single Stratum endpoint. With the Pithead that's the stack's xmrig-proxy on port 3333 — the stack handles pool selection, payouts, and the P2Pool/XvB split centrally, so the worker config stays minimal and you never put a wallet address in it.

During setup RigForge asks for your stack/pool hostname or IP and writes it into config.json (the P2POOL_NODE_HOSTNAME field). A short hostname is resolved over mDNS as <host>.local; pass a full hostname or IP to skip that.

To connect any XMRig instance by hand instead, this is the whole pool config:

{
    "pools": [
        {
            "url": "YOUR_STACK_IP:3333",
            "user": "my-rig-01"
        }
    ]
}

• The user field is just a label for the rig — use its hostname so you can tell workers apart on the dashboard.
• The endpoint must be reachable from the worker; if the host has a firewall, allow the Stratum port (3333) on the LAN.
• Workers talk to the pool over plain Stratum on your local network — they do not need Tor.

---

🚀 Deployment

On the machine you want to turn into a miner:

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

The script needs root to install packages and tune the system. On first run it creates a minimal config.json interactively (you provide your stack/pool hostname); you can also pre-create one from config.json.template:

{
    "HOME_DIR": "DYNAMIC_HOME",
    "DONATION": 1,
    "WORKER_CONFIG_FILE": "./worker-config/example-config.json.template",
    "P2POOL_NODE_HOSTNAME": "YOUR_STACK_IP_OR_HOSTNAME"
}

• P2POOL_NODE_HOSTNAME — the only field you must set: your stack/pool host.
• HOME_DIR — where worker files live. DYNAMIC_HOME defaults to data/ inside this folder.
• WORKER_CONFIG_FILE — the XMRig config template to tune from; the default suits most setups.
• DONATION — XMRig donate level (patched into the build).

Reboot (Linux only)

To apply HugePages and other kernel tuning, a reboot is required on Linux — the script tells you when. After the reboot the xmrig service starts automatically. (macOS needs no reboot.)

sudo reboot

---

🛠️ Maintenance & logging (Linux)

sudo systemctl status xmrig     # service status
sudo systemctl stop xmrig       # stop the miner
sudo systemctl start xmrig      # start the miner
sudo journalctl -u xmrig -f     # live logs

• Log file: <WORKER_ROOT>/xmrig.log (e.g. data/worker/xmrig.log).
• Rotation: a logrotate policy is installed automatically to compress and archive logs.

---

🔍 Verification (Linux)

After rebooting, confirm the optimizations applied:

HugePages

grep Huge /proc/meminfo

HugePages_Total, HugePages_Free, and Hugepagesize should be non-zero and match what the script configured.

MSR (Model-Specific Registers)

grep -i msr <WORKER_ROOT>/xmrig.log

If you see MSR errors, you may need to disable Secure Boot in your BIOS/UEFI.

---

Hardware sizing for the stack host

RigForge sizes the miner. The stack host these workers connect to (Monero node, P2Pool, proxy, dashboard) is sized separately — see Pithead's Hardware Requirements.

---

📝 License

Provided "as-is" under the MIT License.