Pithead

Private Monero + Tari merge-mining stack

Docker Compose stack for Monero + Tari merge-mining on P2Pool, with a Monero full node, Tari base node, and a Tor daemon. Both setup wizards enable Tari when the data disk fits the whole stack, leave XvB off, and generate a dashboard login. Networking is Tor-first by default; see the privacy guide for its scope and exceptions. The pithead script renders config, provisions Tor, and drives docker-compose. It ships two ways: Pithead OS, a bootable appliance image for a machine you dedicate to mining, and the Compose stack you run on a host you manage.

---

What it does

• ⛏️ P2Pool payouts, Tari merge-mined. Mines Monero on P2Pool: no pool operator, no fee, rewards paid to your own wallet. Every hash can merge-mine Tari on the same work — the appliance's setup wizard asks, and a machine that declines mines Monero alone. P2Pool's PPLNS payouts are lumpy, and Tari's solo merge-mining payouts are lumpier still; see payout expectations.
• 🧠 XvB switching engine. Watches the XMRvsBeast raffle and shifts hashrate to hold your tier, donating the minimum needed and routing the rest to your P2Pool payouts.
• 🧅 Tor-first networking. A built-in Tor daemon gives P2Pool an onion address, and the Monero and Tari nodes one each while they run locally. Upstream runtime traffic uses Tor by default; the privacy guide maps the firewall's scope, opt-in clearnet paths, directly dialled remote nodes, and one-time install downloads.
• 🔌 One endpoint for every rig. Point all workers at a single address on port 3333. No wallet address in the miner config for workers pointed at Pithead; the stack routes the hashrate.
• 📊 Live dashboard, with history. Hashrate, the P2Pool/XvB split, the PPLNS window, and per-worker stats over HTTPS on your LAN — and a time-series store keeps blocks found, XvB credit, network difficulty, disk growth, and per-rig hashrate as trends, not just the latest reading.
• 🎛️ Configure and tune from the browser. Opt in with dashboard.control.enabled to edit config.json from a guided form — or raw JSON, with file upload — upgrade to a new release, and read the access and config-change audit logs. Inspecting rig configuration, retuning, and tracking hashrate against config versions require an adopted RigForge rig with its control token and control API enabled; plain XMRig rigs are monitoring only. Every change is gated host-side behind a login. See Worker Inspect and The Dashboard.
• ⚙️ One config, tuned to your setup. A local or remote Monero node, pruned or full, and a local or remote Tari node; the P2Pool tier (main, mini, or nano); XvB donation strategy; per-worker power and API settings; four alert channels; timezone, memory limits, and every privacy toggle — around 90 keys across 14 sections, all in one config.json and validated on every apply. Most have defaults you'll never touch. See Configuration.
• 💡 Energy-aware earnings. Set your electricity cost and coin prices — typed in, or fetched live from CoinGecko over Tor with the opt-in price feed — and add each rig's watts; the earnings card shows fiat estimates per coin, fleet power draw, efficiency in hashes per watt, and estimated profit after power, always stating which price the figures use.
• 📟 Telegram operator bot. Opt-in alerts for a downed node, a worker that dropped off, sync finishing, low disk, a clearnet leak, or a sustained hashrate drop — plus a daily digest and read-only commands (/status, /hashrate, /workers, /earnings). Routed over Tor. The same alerts also push to a generic JSON webhook or an ntfy topic. See the Telegram guide.
• 🔔 Dead-man's switch. An optional Healthchecks.io ping tells you when the whole box goes dark — the one failure a monitor running on that box can never report.
• 💾 Encrypted backups. ./pithead backup writes config, secrets, and onion keys to a single AES-256 archive (the blockchains too, with --with-chains); restore brings a box back on new hardware with the same onion address.
• 🚀 Interactive setup. ./pithead setup checks dependencies, writes config, provisions Tor, and (on Linux) tunes HugePages for RandomX. It prompts before any GRUB change, then offers to start.
• 🔒 Hardened defaults. Non-root containers, SHA256-verified binaries, digest-pinned base and third-party images, localhost-only RPC, and two scoped Docker socket proxies: a read-only one for stats and a separate start/stop-only one for node-down worker failover.

---

📀 Two ways to run it

	What you get	Start here
Pithead OS — the appliance	A bootable USB image that installs itself on a dedicated machine: no Linux to set up, configured from a browser, updated as one signed OS image with A/B fallback. Fallback covers the OS image only; it cannot undo a one-way data migration such as Tari v6.	The appliance guide
The Compose stack — DIY	The same stack on a host you manage (Ubuntu Server 24.04): you keep the OS, pithead drives Docker Compose.	The Quick Start below

Same stack, same dashboard, same configuration either way. The appliance is the short road; DIY is for a box that already does other things.

---

🚀 Quick Start

This is the DIY path. For the appliance, download pithead-os-vX.Y.Z.img.xz from Releases and follow the appliance guide instead — no Linux to set up, no command line to learn.

# 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
./pithead setup

Leave config.json absent for the setup wizard; have a Monero payout address ready, and a Tari payout address only if you enable merge-mining. For manual configuration, copy config.minimal.json or config.reference.json and edit it before setup; those files inherit reference defaults rather than the wizard's new-install choices. To build from source (a dev build), e.g. to contribute, see Install from source. Release archives include the generated pithead executable and offline operator guides; source clones build the executable with make.

NOTE: Prereqs are Ubuntu Server 24.04 LTS, 16 GB+ RAM, an SSD (600 GB+ in either prune mode with both nodes local, or 370 GB+ with Tari remote; the chains grow ~100+ GB/year, so 2–4 TB avoids a later resize), and your Monero payout address (Tari is optional). Running a node on another machine cuts the disk budget — full sizing in Hardware Requirements.

setup checks dependencies (and offers to install them on Ubuntu), asks for your Monero address and optional Tari merge-mining, provisions Tor, tunes HugePages for RandomX, and offers to start the stack. Then:

1. Open the dashboard at https://<your-hostname> (the script prints the exact URL).
2. Wait for the initial sync. On first boot the dashboard shows Sync Mode while the required nodes catch up, then switches to the live view. Tari is absent when merge-mining is off. p2pool and the proxy stay parked until then.
3. Point any XMRig rig at YOUR_STACK_IP:3333 — no wallet address in the miner. 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
Pithead OS — the appliance	Write a USB stick, install on a dedicated machine, configure from a browser. Signed OS image updates with A/B fallback for the OS only, not one-way data migrations such as Tari v6.
Getting Started	The DIY path: prerequisites, install, first-run setup, and what to expect while the node syncs.
Hardware Requirements	Coordinator only, coordinator plus a local worker, or worker only: separate sizing for each role, and how to run leaner.
Configuration	Every config.json key, applying changes safely, reusing an existing node, and remote Monero or Tari nodes.
The Dashboard	Sync Mode, a tour of the live operational view, and the opt-in control channel: editing config, one-click upgrades, and the audit logs from the browser.
Connecting Miners	Point any existing rig at the stack, or spin up a tuned miner with RigForge.
Architecture	The eleven services (nine on a default install), 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/. Contributing, or just want to know where a subsystem lives? Start with the repo map and contribution guide. Agents share AI_RULES.md; the AI workflow covers task ownership and appliance logs.

---

🏗️ How it works

The stack defines eleven services via Docker Compose — nine on a default install: 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), Caddy for HTTPS, and two opt-in view-only wallets that confirm payouts on-chain. Either node drops out when you point the stack at one running elsewhere.

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 to XvB · Tor"| Tor

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

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

    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 test-alert	Send a marked test message through each configured Telegram, webhook, and ntfy sink; Healthchecks is excluded because a ping moves its dead-man switch.
./pithead doctor	Read-only health report (deps, Docker, AVX2, HugePages, RAM/disk, onion state).
./pithead version	Print the installed stack version on one line (offline; also -V / --version).
./pithead backup	Save config, secrets, the Tor onion keys, and the dashboard's database to a passphrase-encrypted archive under backups/ (--with-chains adds blockchain data; --no-encrypt writes plaintext; -y / --yes skips the prompts).
./pithead restore <archive>	Restore configuration, data, and validated generated secrets from an encrypted or plaintext backup; regenerate .env and Caddyfile from the configuration (asks before overwriting; -y / --yes skips the prompt).
./pithead rotate-secrets	Regenerate the stack's internal credentials after a suspected leak — see Rotating the internal secrets.

Commands chain in one call (./pithead apply upgrade runs both, stopping on the first failure; nonsense like up down is rejected before anything runs), and source pithead-completion.bash adds bash/zsh tab-completion — see Operations › Chaining commands.

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 docs/THIRD_PARTY_LICENSES.md.