Pithead

Private Monero + Tari merge mining stack

Pithead is a containerized stack for running a private Monero full node, P2Pool, and Tari merge mining. An interactive setup script takes you from clone to mining in a few minutes.

---

What it does

• ⛏️ Zero-fee, decentralized payouts. Mines Monero on P2Pool: no pool operator, no fees, rewards paid straight to your own wallet. Every hash also merge-mines Tari at no extra power or config cost.
• 🧠 XvB yield optimizer. An algorithmic engine watches the XMRvsBeast raffle and shifts hashrate to catch bonus rounds. It donates only the minimum needed to hold your tier and returns every spare cycle to your own P2Pool payouts.
• 🧅 Tor-first networking. A built-in Tor daemon gives Monero, Tari, and P2Pool onion addresses, so your router stays closed and your home IP is never advertised to an inbound peer. Two outbound yield paths still touch clearnet in v1.0; the privacy guide maps every connection and how to harden it.
• 🔌 One endpoint for every rig. Point all your workers at a single address. Wallets and per-rig pool config stay out of the miner; the stack routes the hashrate.
• 📊 Live dashboard. Shows hashrate, your P2Pool/XvB split, the PPLNS window, and every worker update, served over HTTPS on your LAN.
• 🚀 Interactive setup. A script handles dependencies, config, Tor, and (on Linux) RandomX kernel tuning. It asks before touching GRUB, then offers to start the stack.
• 🔒 Hardened defaults. Least-privilege containers, SHA256-verified binaries, pinned versions, localhost-only RPC, and least-privilege Docker socket proxies (a read-only one for stats, plus a separate start/stop-only one for node-down worker failover).

---

🚀 Quick Start

# Grab the latest release — pulls the published, tested images (no local build)
curl -fsSL https://github.com/p2pool-starter-stack/pithead/releases/latest/download/pithead.tar.gz | tar xz
cd pithead
cp config.minimal.json config.json   # then set your Monero + Tari payout addresses
./pithead setup

For every tunable, copy config.reference.json instead. To build from source (a dev build), e.g. to contribute, see Install from source.

NOTE: Prereqs are Ubuntu Server 24.04 LTS, 16 GB+ RAM, an SSD (~300 GB pruned / ~500 GB full minimum; the chains grow ~100+ GB/year, so 2–4 TB avoids a later resize), and your Monero + Tari payout addresses. Full sizing in Hardware Requirements.

setup checks dependencies (and offers to install them on Ubuntu), asks for your wallet addresses, provisions Tor, tunes the kernel for RandomX, and offers to start the stack. Then:

1. Open the dashboard at https://<your-hostname> (the script prints the exact URL).
2. Let it sync. On first boot the dashboard shows Sync Mode while your Monero and Tari nodes catch up to the network, then switches to the live view automatically once synced. p2pool and the proxy stay parked until then, so the sync logs stay clean.
3. Connect your miners by pointing any XMRig rig at YOUR_STACK_IP:3333 (no wallet address needed). New to mining? RigForge provisions a tuned worker in one command.

Full walkthrough: docs/getting-started.md

NOTE: Already have a synced Monero node? Point the stack at your existing blockchain to skip the wait. See Reusing an existing node.

---

📚 Documentation

Guide	What's inside
Getting Started	Prerequisites, install, first-run setup, and what to expect while the node syncs.
Hardware Requirements	Minimum vs. recommended specs for the stack host (CPU, RAM, disk, network), and how to run leaner. (Miner specs live in RigForge.)
Configuration	Every config.json key, applying changes safely, reusing an existing node, and remote Monero nodes.
The Dashboard	Sync Mode and a tour of the live operational view.
Connecting Miners	Point any existing rig at the stack, or spin up a tuned miner with RigForge.
Architecture	The nine services, the privacy model, and the algorithmic XvB switching engine.
Privacy & Network Egress	Every off-box connection: what's Tor-routed, what's clearnet today, and how to harden it.
Operations & Maintenance	Full command reference, upgrades, backups, and troubleshooting.

Browse the full index at docs/.

---

🏗️ How it works

The stack orchestrates nine services via Docker Compose: a Monero full node, P2Pool, a Tari base node, an XMRig proxy (your single worker endpoint), Tor for anonymity, the dashboard plus switching engine, a read-only Docker socket proxy (plus a tiny start/stop-only control proxy), and Caddy for HTTPS.

flowchart TB
    %% ── External actors ──
    You(["👤 You · Browser"])
    Workers(["⛏️ XMRig Workers"])
    XvB(["🎲 XMRvsBeast Pool"])
    Net(["🌐 Tor Network / Internet"])

    subgraph stack ["🐳 Pithead"]
        direction TB

        Caddy["🔒 Caddy<br/>HTTPS reverse proxy"]
        Dashboard["📊 Dashboard<br/>+ XvB switching engine"]
        DockerProxy["🛡️ Docker Socket Proxies<br/>read-only + start/stop"]
        Tor["🧅 Tor<br/>anonymity layer"]

        subgraph core ["⚙️ Mining Core"]
            direction TB
            Proxy["🔀 XMRig Proxy<br/>:3333"]
            P2Pool["🔵 P2Pool"]
            Monerod["🟠 Monero Node"]
            Tari["🟣 Tari Node"]
        end
    end

    You ==>|HTTPS| Caddy
    Caddy --> Dashboard
    Workers ==>|"Stratum 3333"| Proxy

    Dashboard -.->|controls| Proxy
    Dashboard -.->|monitors| DockerProxy
    Dashboard -.->|"reads stats & sync"| core

    Proxy ==>|hashrate| P2Pool
    Proxy ==>|hashrate| XvB

    P2Pool <-->|"RPC / ZMQ"| Monerod
    P2Pool -->|merge-mine| Tari

    Monerod <--> Tor
    Tari <--> Tor
    P2Pool <--> Tor
    Tor <--> Net

    classDef ext fill:#1e293b,stroke:#64748b,color:#e2e8f0;
    classDef ctrl fill:#1d4ed8,stroke:#93c5fd,color:#eff6ff;
    classDef priv fill:#6d28d9,stroke:#c4b5fd,color:#f5f3ff;
    classDef mine fill:#047857,stroke:#6ee7b7,color:#ecfdf5;

    class You,Workers,XvB,Net ext;
    class Caddy,Dashboard ctrl;
    class Tor,DockerProxy priv;
    class Proxy,P2Pool,Monerod,Tari mine;

    style stack stroke:#475569,stroke-width:1px;
    style core stroke:#10b981,stroke-width:1px,stroke-dasharray:5 4;

Loading

Read the full breakdown, including the privacy model and the algorithmic switching engine, in Architecture.

---

🛠️ Common commands

Everything runs through pithead (./pithead help lists it all):

Command	Description
./pithead setup	First-time interactive setup.
./pithead apply	Preview and apply config.json changes.
./pithead up / down / restart	Start / stop / restart the stack.
./pithead upgrade	Re-render config, then pull (bundle) or rebuild (source) the images and restart — see Updating.
./pithead logs [service]	Follow logs (all, or one service).
./pithead status	Container status + health-check of every expected service (warns on anything down).
./pithead doctor	Read-only health report (deps, Docker, AVX2, HugePages, RAM/disk, onion state).
./pithead backup	Save config, secrets, the Tor onion keys, and the dashboard's database to backups/ (--with-chains adds blockchain data; -y / --yes skips the prompts).
./pithead restore <archive>	Restore those files from a backup archive (asks before overwriting; -y / --yes skips the prompt).

Full reference: Operations & Maintenance.

---

🤝 Donate

If this stack saved you time, donations to this XMR wallet are appreciated:

486aGn4qhH1MkaASjnEWMDN7stD1SVtPF5fvihmjffeBE5ACL1u1jU95KxiqmoiaPZMexi4R4W11MLXut66XWVVF8wjAE5R

📄 License

Pithead's own code is provided "as-is" under the MIT License. Bundled third-party components keep their own licenses (two, p2pool and xmrig-proxy, are GPLv3, shipped unmodified as separate containers). See THIRD_PARTY_LICENSES.md.