If you like this project, don't forget to leave a star. ⭐

A lightweight, containerized and performance-optimised XMRig miner. Provide your pool details and start mining — no setup, no dependencies, no fuss.

Features

• 🔒 Isolated and sandboxed — runs as non-root, self-contained, host stays clean, removes without a trace
• 🏔️ Lightweight Alpine image — native CPU builds for amd64 & arm64
• 🟢 CUDA GPU support — dedicated NVIDIA GPU image for accelerated mining
• 🎯 Ready to mine — sensible defaults pre-configured, all algorithms enabled

Available Images

Image	Tag	Platform	Description
CPU	latest, <version>	amd64, arm64	CPU mining
CUDA	cuda, cuda-<version>	amd64	CPU + NVIDIA GPU mining

Quick Start

CPU Mining

docker run --rm -it ghcr.io/xterna/xmrig -o <pool_url> -u <wallet_address> -p <worker_name>

GPU Mining (CUDA)

Docker Desktop (Windows) — GPU support is built in. Just run:

docker run --rm -it ghcr.io/xterna/xmrig:cuda -o <pool_url> -u <wallet_address> -p <worker_name>

Linux / WSL2 (Docker Engine) — one-time setup, then mine:

# Install NVIDIA Container Toolkit (one-time)
curl -fsSL https://github.com/XternA/xmrig/raw/main/nvidia-toolkit.sh | bash

# Start mining
docker run --rm -it ghcr.io/xterna/xmrig:cuda -o <pool_url> -u <wallet_address> -p <worker_name>

To remove the toolkit later:

curl -fsSL https://github.com/XternA/xmrig/raw/main/nvidia-toolkit.sh | bash -s -- --uninstall

Miner runs in interactive mode. Press Ctrl+C to stop and remove the miner.

Flags

Flag	Description
-o	Pool address and port
-u	Your wallet address
-p	Worker name
--no-cpu	Disable CPU mining — GPU only (CUDA image)
--no-gpu	Disable GPU mining — CPU only (CUDA image)
--cli	Bypass config entirely, pass all flags directly to XMRig

Usage

Zero Configuration (Recommended)

Pass your pool details directly. The miner starts immediately with a pre-optimised config:

docker run -d --name xmrig ghcr.io/xterna/xmrig -o <pool_url> -u <wallet_address> -p <worker_name>

For GPU mining, use the cuda tag:

docker run -d --name xmrig ghcr.io/xterna/xmrig:cuda -o <pool_url> -u <wallet_address> -p <worker_name>

As environment variables:

docker run -d --name xmrig ghcr.io/xterna/xmrig -o $POOL_URL -u $WALLET_ADDRESS -p $WORKER_NAME

The miner is now running as a daemon.

---

Mounted Config File (Flexible Control)

For advanced configuration — custom thread counts, multiple pools, algorithm tuning.

Generate a config using the XMRig Wizard Helper and mount your config file:

docker run -d --name xmrig -v /config_path/config.json:/app/config.json ghcr.io/xterna/xmrig

Your custom config is now used instead.

Ensure your config has "autosave": false and "watch": false. Auto-saving and file watching serve no purpose in a container. It will also inflate your config file, making it harder to maintain and remember your preferences.

Changes to config.json require a container restart to take effect.

See Config Wiki for all available options.

---

Direct CLI Mode

Pass --cli to bypass the internal config entirely and send all arguments directly to XMRig. This gives you complete control over every XMRig flag:

docker run -d --name xmrig ghcr.io/xterna/xmrig \
  --cli -o <pool_url> -u <wallet_address> -p <worker_name> -k --tls ...

In CLI mode, the internal optimised config is not loaded. You control all settings via flags. Use docker run --rm ghcr.io/xterna/xmrig --cli --help for the full list of XMRig options.

Container Management

docker restart xmrig    # restart the miner
docker stop xmrig       # stop the miner
docker logs -f xmrig    # follow live output
docker pause xmrig      # pause without stopping

For help and commands, see XMRig documentation.

docker run --rm ghcr.io/xterna/xmrig --cli --help

Donations

• Default donation 1% (1 minute in 100 minutes) can be increased via the donate-level option in the config file.
• XMR: 87LGyTzNrRCFGAAGVkKD6wL4a3xFpLAfh7JL3RbmbvhUgWW1BHbtrkT7M5wkMWEEvSQdz2VJemvfgYvVWnC49e7S6BRA9Xv

CPU Optimisation (RandomX)

Huge Pages

Enabling huge pages on supported systems reduces TLB pressure, lowering memory management overhead and improving CPU hashrate by up to 30%.

# Temporary (resets on reboot)
sudo sysctl -w vm.nr_hugepages=1280

# Permanent
sudo bash -c "echo vm.nr_hugepages=1280 >> /etc/sysctl.conf"

# Removing huge pages
sudo sed -i '/vm.nr_hugepages=1280/d' /etc/sysctl.conf

Note: 1280 pages reserves 2560 MB exclusively for huge pages, unavailable for other use. The miner automatically uses the precise number it needs.

Restart the container after configuring.

---

MSR (Model Specific Register)

MSR writes allow XMRig to tune CPU microarchitectural settings for RandomX, achieving optimal hashrates on supported hardware.

Supported CPUs:

• Intel (Nehalem, Westmere, Sandy Bridge, Ivy Bridge, Haswell, Broadwell and newer)
• Ryzen (All Zen based CPUs: Ryzen, Threadripper, EPYC)

Load the MSR module on the host:

sudo modprobe msr

Run the container with the --privileged flag:

docker run --rm -it --privileged ghcr.io/xterna/xmrig -o <pool_url> -u <wallet_address> -p <worker_name>