EloPool is a high-performance Bitcoin Cash mining pool for StartOS, built on ckpool. It provides dual-mode operation — pool mining and solo mining — with a built-in web dashboard.
- Pool Mining (port 3333) — Shared block rewards among all miners
- Solo Mining (port 4567) — Winner takes the entire block reward
- Web Dashboard (port 80) — Real-time hashrate, workers, blocks found
- Stratum Protocol — Compatible with all ASIC miners (Antminer, Whatsminer, Bitaxe, etc.)
- Auto-configured — Automatically connects to your Bitcoin Cash Node (BCHN or Knuth)
- Multi-architecture — Runs on x86_64 and aarch64
┌─────────────────────────────────────────────────────┐
│ EloPool Package │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ Pool ckpool │ │ Solo ckpool │ │ Web UI │ │
│ │ :3333 │ │ :4567 │ │ :80 │ │
│ │ (shared) │ │ (solo) │ │ (nginx) │ │
│ └──────┬───────┘ └──────┬───────┘ └─────┬──────┘ │
│ │ │ │ │
│ └────────┬────────┘ │ │
│ │ │ │
│ ┌───────▼────────┐ ┌──────────▼───────┐ │
│ │ /data volume │ │ stats-api.sh │ │
│ │ (ckpool runs) │◄────│ (logs → JSON) │ │
│ └───────┬────────┘ └──────────────────┘ │
│ │ │
└─────────────────┼────────────────────────────────────┘
│ RPC (8332)
┌────────▼────────┐
│ Bitcoin Cash │
│ Node (BCHN │
│ or Knuth) │
└─────────────────┘
| Package | Required | Notes |
|---|---|---|
| Bitcoin Cash Node | Yes | BCHN, BCHD or Knuth. Must be fully synced with txindex enabled. |
- Install Bitcoin Cash Node on your StartOS server and wait for full sync
- Install EloPool from the marketplace
- Configure — Set your BCH payout address via Actions → Configure
- Point your miners at:
- Pool mode:
stratum+tcp://<your-server>:3333 - Solo mode:
stratum+tcp://<your-server>:4567
- Pool mode:
- Monitor via the Web Dashboard
| Setting | Value |
|---|---|
| URL | stratum+tcp://<host>:3333 (pool) or :4567 (solo) |
| Username | Your BCH address |
| Password | Anything (or d=DIFFICULTY for custom difficulty) |
Every stratum binding can be exposed over Tor so remote miners connect over the Tor network without touching your LAN.
- Open StartOS → EloPool → Interfaces.
- For
Pool Mining,Solo Mining, orWeb Dashboard: tap Add, choose Tor. - StartOS generates a
.onionaddress automatically. Point your Tor-aware miner at:stratum+tcp://<xxxx>.onion:3333 # pool stratum+tcp://<xxxx>.onion:4567 # solo - Re-run
setup-vm-forwarding.sh— it will auto-detect the enabled.onionURLs and print/save them alongside your LAN URLs.
The onion keys survive StartOS reboots and are preserved by the standard StartOS backup system.
- Accepted — integer count of accepted share submissions — equivalent to what your ASIC's own cgminer API reports as
Accepted(e.g. Avalon'sAccepted: 6). Because ckpool stores only a diff-weighted sum per-worker (worker->shares += diff), we derive the count by dividing that sum by the worker's current vardiff (client->diff). The vardiff is read live from ckpool's Unix control socket by a helper loop in the pool subcontainer (seeassets/pool-entrypoint.sh) and staged at/data/{mode}/log/clients.jsonfor the UI subcontainer. - Rejected — integer count of rejected share submissions, aggregated from ckpool's own per-share JSONL sharelog at
/data/{mode}/log/{blockheight}/*.sharelog. Every share submission — accepted or rejected — is written as one line with fields includingworkername,result(true/false), andreject-reason. We group byworkernameand countresult: falseentries. Scan is bounded to the 500 most-recently-modified sharelog files so long-running pools stay fast. - Shares (Σdiff) — the same accepted shares viewed as diff-1–weighted WORK (e.g.
182.00 M). Useful for comparing contribution across workers with different vardiff targets. - Best Share — highest individual share difficulty ever submitted by this worker. When Best Share approaches network difficulty (~355 EH on BCH right now), a block is about to be found.
- Last Share / Status — Status is derived from the pool's
lastshareunix timestamp (authoritative, updated on every accepted share): under 5 min = Alive, under 1 h = Idle, older = Dead. Hashrate averages are only used as a last-resort fallback whenlastshareis missing, so the badge cannot get stuck at "Alive" after a miner goes dark. - Found Blocks (main card) — counted directly from files in
/data/pool/log/pool/blocks/(ckpool writes one file per solved block). A true integer count, not derived from share work.
If you run StartOS inside a libvirt/KVM virtual machine (e.g. via virt-manager), miners on your local network cannot reach the VM directly because libvirt uses a NAT bridge (virbr0). You need to forward the mining ports from your host machine to the VM.
This works with any connection type — wired (Ethernet), wireless (WiFi), or both simultaneously.
Download and run the setup script:
curl -fsSL https://raw.githubusercontent.com/BitcoinCash1/bch-elopool-startos/master/scripts/setup-vm-forwarding.sh -o setup-vm-forwarding.sh
chmod +x setup-vm-forwarding.sh
sudo ./setup-vm-forwarding.shThat's it. The script will:
- Auto-detect your StartOS VM and its IP address
- Pin the VM's IP so it doesn't change on reboot (static DHCP lease)
- Install a libvirt qemu hook that automatically forwards ports whenever the VM starts
- Detect all your physical network interfaces (wired + wireless) and forward on each
- Print the exact stratum URLs to use for your miners
- Best-effort: detect any
.onionaddresses you have enabled for the pool and print those too (see Tor / Onion Mining)
The rules persist across host reboots automatically — the hook is invoked by libvirt every time the VM starts, so there is no cron job or systemd unit to maintain.
$ sudo ./setup-vm-forwarding.sh
[OK] Found VM: Start9OS
[OK] VM IP: 192.168.122.129
[OK] eno1 (192.168.0.55) ← wired
[OK] wlp4s0 (192.168.0.156) ← wireless
[OK] Hook installed at /etc/libvirt/hooks/qemu
[OK] Forwarding rules active
Miner configuration — use ANY of these addresses:
via eno1 (192.168.0.55):
EloPool: stratum+tcp://192.168.0.55:3333
EloPool Solo: stratum+tcp://192.168.0.55:4567
via wlp4s0 (192.168.0.156):
EloPool: stratum+tcp://192.168.0.156:3333
EloPool Solo: stratum+tcp://192.168.0.156:4567
# Check current status
sudo ./setup-vm-forwarding.sh --status
# Completely remove (restores system to default)
sudo ./setup-vm-forwarding.sh --remove
# Specify VM name manually (if auto-detect fails)
sudo ./setup-vm-forwarding.sh "My StartOS VM"The script installs /etc/libvirt/hooks/qemu — the official libvirt hook mechanism. When the VM starts, the hook adds iptables DNAT rules that forward incoming connections on ports 3333, 4567, and 80 from every physical network interface to the VM. When the VM stops, the rules are automatically removed.
┌─────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Miner │────▶│ Host Machine │────▶│ StartOS VM │
│ 192.168.0.x │ │ eno1/wlp4s0 │ │ 192.168.122.x │
│ │ │ (iptables DNAT) │ │ (virbr0 NAT) │
└─────────────┘ └──────────────────┘ └──────────────────┘
stratum+tcp:// port forwarding ckpool listening
192.168.0.55:3333 3333 → VM:3333 on :3333
No bridges, no NetworkManager changes, no DNS changes. Just iptables rules managed by the official libvirt hook system.
Supports VirtualBox and Hyper-V. Open PowerShell as Administrator and run:
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/BitcoinCash1/bch-elopool-startos/master/scripts/setup-vm-forwarding.ps1" -OutFile setup-vm-forwarding.ps1
.\setup-vm-forwarding.ps1The script will auto-detect your VM and hypervisor, set up port forwarding, save a Miner-Connection-Info.txt to your Desktop, and open a copyable popup with your stratum URLs.
# Management
.\setup-vm-forwarding.ps1 -Status # show current state
.\setup-vm-forwarding.ps1 -Remove # uninstall everything
.\setup-vm-forwarding.ps1 -VMName "My VM" # specify VM nameSupports VirtualBox and UTM. Open Terminal and run:
curl -fsSL https://raw.githubusercontent.com/BitcoinCash1/bch-elopool-startos/master/scripts/setup-vm-forwarding-mac.sh -o setup-vm-forwarding-mac.sh
chmod +x setup-vm-forwarding-mac.sh
sudo ./setup-vm-forwarding-mac.shSame features: auto-detect, Desktop txt file, popup with Copy to Clipboard button.
sudo ./setup-vm-forwarding-mac.sh --status # show current state
sudo ./setup-vm-forwarding-mac.sh --remove # uninstall everythingTip (all platforms): If you use Bridged Networking instead of NAT, the VM gets its own LAN IP and miners can connect directly — no port forwarding script needed.
| Problem | Solution |
|---|---|
| Script says "VM not found" | Run virsh list --all to see VM names, then pass it: sudo ./setup-vm-forwarding.sh "exact name" |
| Script says "Cannot determine VM IP" | Start the VM first, wait 30 seconds for it to get an IP, then run again |
| Miner connects but pool shows no hashrate | Check that the pool service is running on StartOS (Actions → Start) |
| Port forwarding stops after reboot | The hook should auto-apply when the VM starts. Run sudo ./setup-vm-forwarding.sh --status to verify the hook file exists |
| Want to undo everything | sudo ./setup-vm-forwarding.sh --remove restores your system completely |
| Windows: "execution policy" error | Run Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass first |
| macOS: VBox rules need VM stopped | Shut down the VM, run the script, then start the VM |
| macOS UTM: need guest IP | Find it inside StartOS (System → Network) and enter when prompted |
# Prerequisites: StartOS SDK, Docker, Node.js 20+
git clone https://github.com/BitcoinCash1/bch-elopool-startos.git
cd bch-elopool-startos
npm install
make| Port | Protocol | Purpose |
|---|---|---|
| 3333 | Stratum (TCP) | Pool mining |
| 4567 | Stratum (TCP) | Solo mining |
| 80 | HTTP | Web dashboard |
| Option | Default | Description |
|---|---|---|
| Payout Address | (required) | BCH address for coinbase rewards |
| Pool Fee | 1% | Fee percentage for pool mode (solo is always 0%) |
| Pool Identifier | EloPool |
Coinbase signature visible on block explorers |
| Starting Difficulty | 64 | Initial share difficulty for new workers |
EloPool runs two independent ckpool instances from the same Docker image:
- Pool instance shares rewards proportionally based on submitted shares
- Solo instance directs the entire block reward to whichever miner finds it
Both instances connect to your Bitcoin Cash Node via RPC. The web dashboard reads ckpool's log files directly and serves stats as static JSON via nginx.
You can point different miners to different modes simultaneously — no reconfiguration needed.
- skaisser/ckpool — EloPool fork of ckpool
- bitcoin-cash-node — Bitcoin Cash full node
GPL-3.0 — matches upstream ckpool license.
AI Reference Prompt
package: bch-elopool
type: startos-service
sdk: "@start9labs/start-sdk@1.0.0"
upstream: skaisser/ckpool
depends_on: bitcoincashd (BCHN or Knuth flavor)
ports:
pool: 3333 (stratum)
solo: 4567 (stratum)
ui: 80 (http)
daemons: 3 (pool-ckpool, solo-ckpool, ui-nginx)
volumes: main (/data)
dependency_mount: /mnt/bitcoincashd (reads store.json for RPC creds)
critical_tasks: txindex=true, prune=null, zmqEnabled=true
config_fields: payoutAddress, poolFee, poolIdentifier, poolDifficulty
webui: nginx serving static HTML + stats-api.sh background (logs → JSON)
build: multi-stage Docker (ubuntu build-ckpool → node:20-bookworm-slim runtime)