Pithead v2.0.0

Pithead 2.0.0

Released 2026-10-13.

Pithead 2.0.0 is the first release of Pithead OS, the appliance: a bootable image that installs itself on a machine you dedicate to it, is set up from a browser, and updates as one signed image that goes back to the previous version on its own when an update does not boot. The Docker Compose install (DIY) ships in the same release, with the same stack, dashboard and configuration. Everything below applies to both unless it says otherwise.

Upgrading a 1.20.x install? Read Upgrading from 1.20.x first. The Tari 6.0 hard fork needs a one-way database migration.

Full details are in CHANGELOG.md. The appliance guide is docs/appliance.md.

Highlights

Pithead OS, the appliance (new)

• Write the image to a USB stick and boot from it. It installs itself and serves a one-page setup wizard to your browser. You pick a coordinator, a coordinator that also mines with its own CPU, or a mining rig. A machine with no monitor can be set up, and changed later, from a file on the stick.
• Updates use two system copies. The update is written to the idle copy and verified against the release key before install. If the new version does not come up, the machine returns to the previous copy by itself. Update from the dashboard's System update control or with pithead os-update. Chain services start only after the new copy has committed, so a one-way database migration never runs on a version that might roll back.
• Encrypted backups, with restore from the setup wizard on a fresh machine. A restored machine keeps its own identity.
• A config reset (keeps the synced chains, the wallet and the Tor keys) and a factory reset. A data partition damaged by a power cut is repaired, not erased.
• Host tuning built in: hugepages sized to the installed RAM, the performance CPU governor, a hardware watchdog, and the Tor-only egress firewall with IPv6 failing closed.

Tari and P2Pool

• Tari v6.0.1-pre.0 and P2Pool 4.18.1, upgraded together for the Tari 6.0 hard fork at block 350,000. Installs older than 2.0.0 are off the canonical Tari chain until they upgrade.
• A node that followed the dead 5.3.1 branch past 350,000 is rewound on its own (logged in docker logs tari as [pithead fork-check]).
• Monero keeps mining while Tari syncs after you turn it on or re-point it. With Tari optional, it also keeps mining through a Tari outage.

New installs, dashboard and CLI

• New installs start from safer defaults: Tari off unless you say yes (beta), the XvB raffle off, a dashboard login generated and shown once, the first sync over Tor, and the stratum password opt-in. Upgrades keep their configuration.
• Service Diagnostics shows the doctor's detail and a redacted log tail per service, with no shell needed.
• The XMR Network card shows whether monerod is at the tip with peers, and alerts when it is not.
• The onion client key can be revealed from the dashboard (Show client key), so a Tor-authorized onion works on the appliance.
• The dashboard shows where each rig's running configuration came from, and flags a rig running something other than what was applied.
• Tor: a saturated circuit history is detected and alerted, and ./pithead tor-recover can reset it while Monero stays synchronized. With tor.auto_heal and dashboard control on, the gated recovery runs by itself.
• Configuration: a disruptive change asks you to type APPLY. A payout change also asks for the last characters of the new address. Neither depends on Telegram any more.
• pithead doctor --json and pithead support-bundle (redacted for support requests).

Security

• DIY: the Tor-only egress firewall and the LAN-only source rule are restored at boot before Docker starts any container.
• The dashboard warns and sends an alert when the Tor-only egress firewall is missing.
• monero.rpc_lan_access, monero.zmq_lan_access and tari.grpc_lan_access accept connections only from loopback, private and CGNAT addresses.
• The Tari node no longer runs its own in-process Tor. It dials through the stack's Tor.
• The dashboard password stays out of process arguments, and its hash stays out of the appliance journal.

Removed

• Release images no longer accept ssh.* options. A carried 1.x ssh.enabled: true is ignored and reported.
• Telegram is a read-only notification channel. /restart, /apply and the approval tap are gone, and apply removes telegram.control from your config for you.
• The 1.x aliases dashboard.workers[] and xmrig_proxy.* are migrated once, in place, to workers.list[] and xvb.*.

Also fixed in this release

These fixes are in the v2.0.0 tag. The tagged CHANGELOG lists them under Unreleased.

• pithead apply finishes a Caddy restart that an earlier, interrupted apply left pending, so the dashboard login always matches the config (#3332).
• On the appliance, pithead restore after pithead config-reset no longer refuses with "could not verify that the stack is stopped" (#3346).
• A fleet workers.api_port outside 1-65535, or not an integer, is refused at preview and by pithead apply (#3358).
• A Configuration preview made before the live config changed is rejected at commit, so a stale preview in another tab cannot overwrite a newer edit (#3352).
• A one-field save in Configuration no longer adds untouched default arrays to a minimal config.json (#3355).

Upgrading from 1.20.x

Upgrading from 1.x is best-effort. A fresh setup may be required.

• Take ./pithead backup --with-chains before upgrading.
• Leave free space for the Tari migration. The old and new database copies sit on the data volume together at the peak. ./pithead upgrade needs the current data.mdb size plus 5 GiB free, and refuses before touching any container otherwise.
• Tari reads "loading" for about 2.5 hours during its first-start migration. Do not stop, restart or apply the stack until it finishes. Follow its phases with docker logs tari.
• If tari.mode is remote, upgrade the serving node to v6.0.1-pre.0 before this stack.
• The Tari node and wallet database migrations are one-way. There is no way back to 1.x Tari.
• The first time 2.0.0 reads a 1.x configuration, it migrates the old aliases once. The next apply drops telegram.control, and a carried ssh.* setting is ignored and reported.

Beta in 2.0.0

Beta means the feature is optional and off unless you turn it on, and a defect seen only with it enabled may ship as a known issue. Dashboard beta badges come in 2.0.1.

• Tari merge-mining: off by default in the setup wizards. Upgrades and configs that omit tari.mode keep the bundled node. A yes in a new-install wizard also sets dashboard.tari_required: false (#3333).
• XvB raffle: off for new installs.
• Payout confirmation (monero.view_key, tari.view_key). With Tari payout confirmation on, someone who knows your Tari address can make the view-only wallet show a fake incoming amount. It cannot spend (GHSA-g2r4-jvjg-h942).
• Remote rig control: an appliance rig listens for control pinned to its coordinator and gated by its token. Dashboard writes to a rig need adoption first. On rigs whose home directories are mode 0750 (the stock Ubuntu default), dashboard adoption and control do not work. Mining is unaffected (rigforge#362).

Known issues in 2.0.0

Appliance

• The built-in miner can stay at 0 H/s after a dashboard backup or a recovery boot. Run sudo systemctl restart xmrig or reboot. Fixed in 2.0.1 (#3375).
• After a dashboard update, the appliance can mint a new self-signed certificate for the same addresses, so the browser asks you to trust it again. Fixed in 2.0.1 (#3414).
• New: after an update from System update, reopening System update in the same tab can still offer the version you just installed, with Download. Reload the page before using System update again. Fixed in 2.0.1. During an update the page runs the code of the release you are updating from, so the fix applies to updates started from 2.0.1 onward: reload after the 2.0.0 to 2.0.1 update too (#3430).
• A restore started from the command line while the setup page is still starting can leave the setup page up instead of the dashboard. Mining is unaffected. Fixed in 2.0.1 (#3390).
• On an appliance rig, a pool changed from Worker Inspect reverts at the next reboot, because the rig's rig.json owns the pool. Change it in rig.json instead. The other Worker Inspect edits survive a reboot (rigforge#583).

Tor

• Tor auto-heal needs dashboard control. Without dashboard.control.enabled, which includes every appliance set up with No login, tor.auto_heal only detects and logs Tor trouble. Turn dashboard control on, or restart Tor with ./pithead restart tor (#3166).
• Automatic Tor recovery restarts Tor on its own, and its long-run behaviour has had little soak time.

Dashboard and Configuration

• New: after a command-line restore over an existing install (down, restore, up), the dashboard keeps serving the pre-restore configuration, including in the earnings calculator. The first save from Configuration can then re-propose the old values and undo part of the restore. Run ./pithead apply once, then ./pithead restart. A restore from the setup wizard is not affected. Fixed in 2.0.1 (#3432).
• Updated: a saved workers.api_port: null means the default port, 8080, but the preview shows it as "unset". It also stops the dashboard from attaching worker API read tokens for workers that use the fleet port, so their authenticated worker API reads fail. Omit workers.api_port, or set it to 8080. Fixed in 2.0.1 (#3377).
• Setting the stratum port in Configuration to a port another service already uses is not caught by the preview. Apply then fails part-way with the proxy stopped. Configuration's recovery restores it (#3417).
• After a rejected stale Configuration change, the message can say it was saved (#3376).
• The preview can warn about a sidechain/PPLNS reset for a routing-only change (#3382), or about Tari sync settings that are off (#3383).
• The dashboard can show a LAN stratum URL for a loopback-only listener (#3384).
• An Advanced JSON edit that slips in a null webhook entry saves it without the preview listing it. Nothing is sent. Fixed in 2.0.1 (#3388).
• Dark mode can make text in dialogs (#3378), password placeholders (#3379) and the empty Workers Alive card's guide link (#3380) hard to read. The Advanced topology heading can be clipped (#3381).

DIY (Docker Compose)

• New: the dashboard's HTTPS certificate comes from Caddy's internal CA, which issues 12-hour certificates and renews them before they expire. If you accepted the certificate itself in the browser, the warning comes back after each renewal. Trust Caddy's local root CA once instead: docker cp caddy:/data/caddy/pki/authorities/local/root.crt caddy-local-root.crt copies it out (use sudo if your user cannot run Docker); add it to your system or browser trust store. Fixed in 2.0.1 (#3435).
• On a host whose GRUB configuration has malformed quoting, later update-grub runs can fail. Run setup with --skip-optimize, or remove /etc/default/grub.d/zz-pithead-hugepages.cfg (#3305).
• The order of the DIY firewall rules against Docker at reboot is untested (#2677).
• DIY shows the appliance-only built-in-miner toggle (#3357).
• Recovery after an interrupted image build during DIY source setup is undocumented (#3348).

RigForge

• New: RigForge 1.18.0 does not apply the threads setting or its tuned thread count. XMRig 6.26.0 ignores the value as RigForge writes it and runs its own automatic, cache-sized profile instead, which can use every core. A threads cap cannot keep cores free in this release; leave threads empty. The appliance's built-in miner sets no cap and is unaffected. Fixed in a RigForge patch release that Pithead 2.0.1 pins (rigforge#588).

Components

• Pithead v2.0.0, commit c59e5ad6fc7c1fe82eb7558a2f962c18c1266299.
• Mining-rig role: RigForge 1.18.0, commit b2d4c3d9ca1da74d0e6d5ccce772d401acc8be03.
• Tari node and console wallet v6.0.1-pre.0-mainnet (pinned by digest) and P2Pool 4.18.1. Every component version and image digest is in ingredients-v2.0.0.md.

Verify your download

SHA-256:

• pithead-os-v2.0.0.img.xz: 7958223c077bcaf4a4673e492471c763e564199fdb9663f4aa12504ac3573f63
• pithead-os-v2.0.0.raucb: 58e690e73bb5224fdfe64ee39f814161d26d10f54e9f60d55bb03cdca58ea0b6
• pithead.tar.gz: 761600817639dae92ebcffed2aae2e166d9bad70b9ff7afca4722408af42dcca

Appliance image (pithead-os-v2.0.0.img.xz): download it with pithead-os-v2.0.0.img.xz.sha256 into the same folder, then run sha256sum -c pithead-os-v2.0.0.img.xz.sha256 (macOS: shasum -a 256 -c pithead-os-v2.0.0.img.xz.sha256). A good download prints OK.

Appliance update bundle (pithead-os-v2.0.0.raucb): check it the same way with pithead-os-v2.0.0.raucb.sha256. The appliance also verifies the bundle's signature before it installs anything.

DIY install bundle (pithead.tar.gz): ./pithead upgrade verifies the bundle and every first-party image against the cosign.pub already on your host. The release key is the same one 1.20.x ships. To check by hand with cosign:

cosign verify-blob --key cosign.pub --signature pithead.tar.gz.sig --insecure-ignore-tlog=true pithead.tar.gz
cosign verify --key cosign.pub --private-infrastructure ghcr.io/p2pool-starter-stack/pithead-dashboard:v2.0.0

Repeat the image check for each image in ingredients-v2.0.0.md.

Asset	SHA-256
pithead-os-v2.0.0.img.xz	7958223c077bcaf4a4673e492471c763e564199fdb9663f4aa12504ac3573f63
pithead-os-v2.0.0.raucb	58e690e73bb5224fdfe64ee39f814161d26d10f54e9f60d55bb03cdca58ea0b6
pithead.tar.gz	761600817639dae92ebcffed2aae2e166d9bad70b9ff7afca4722408af42dcca
cosign.pub (release key, at the tag)	7548180938a28654ff273920875a6cea12e871f73633090f375b9592f4e97453

Ingredients — Pithead v2.0.0

• Version: 2.0.0
• Commit: c59e5ad6fc7c1fe82eb7558a2f962c18c1266299
• Built: 2026-10-13T19:24:00Z

Published images (ghcr.io/p2pool-starter-stack, tags v2.0.0 + latest)

• ghcr.io/p2pool-starter-stack/pithead-tor:v2.0.0
  • digest: ghcr.io/p2pool-starter-stack/pithead-tor@sha256:ac5b3dc2cdfca77066c0a2afb8905b3fcf3dc226f2f14ff0940090f7d35cacb4
• ghcr.io/p2pool-starter-stack/pithead-monero:v2.0.0
  • digest: ghcr.io/p2pool-starter-stack/pithead-monero@sha256:c4ef1923863b9716e7fd462e30633519c16043517219685e53777f70b10eec35
• ghcr.io/p2pool-starter-stack/pithead-p2pool:v2.0.0
  • digest: ghcr.io/p2pool-starter-stack/pithead-p2pool@sha256:789913c8b0b8841f5adaa4f17243b4e4c229a9a34ba49a77ecd44f699b7407d0
• ghcr.io/p2pool-starter-stack/pithead-xmrig-proxy:v2.0.0
  • digest: ghcr.io/p2pool-starter-stack/pithead-xmrig-proxy@sha256:44d56bd4bb610d31f9e27c27346c61e7b3d75d7a6ad93d28e05a08d255f661e4
• ghcr.io/p2pool-starter-stack/pithead-dashboard:v2.0.0
  • digest: ghcr.io/p2pool-starter-stack/pithead-dashboard@sha256:edc822a53ccba0d6d45c54409bf5da679ac3b5ec6efc21cbb1d1cc737cf94f7a
• ghcr.io/p2pool-starter-stack/pithead-os-rootfs:v2.0.0
  • digest: ghcr.io/p2pool-starter-stack/pithead-os-rootfs@sha256:6ef616ffe715af55aa9d088b410b40486854e71414356e0c64090da2620f609b

Upstream component pins

• p2pool: v4.18.1
• monerod: v0.18.5.1
• xmrig-proxy: 6.26.0
• tor base: alpine:3.24@sha256:294b683cb724975bec92580e1e685676bd4b50bda910ddb8c51d4cabeaec77e6
• tari node: ghcr.io/tari-project/minotari_node:v6.0.1-pre.0-mainnet@sha256:23ce381b74e48cf67677dfe85c800daf54a155a610c595c94b16db6b186950ec
• tari console wallet: ghcr.io/tari-project/minotari_console_wallet:v6.0.1-pre.0-mainnet@sha256:6f1f7d8990d304466f70a0379dcef4825c29b785c10d7fc7dff4d89163ed1b9d
• caddy: caddy:2.11.7@sha256:f2a1290d0463aad60660d4ec134943f183ee2a5f6c3eb7bf32dd984f2f020772
• docker-socket-proxy: tecnativa/docker-socket-proxy:v0.5.0@sha256:1f5038b54f06c3e18422902cf00ba21803d1c97805aae032e5e6673d532d3459
• rigforge: b2d4c3d9ca1da74d0e6d5ccce772d401acc8be03
• bundle sha256: 761600817639dae92ebcffed2aae2e166d9bad70b9ff7afca4722408af42dcca