xterna/xmrig repository overview

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

⁠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

⁠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.

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 ...

⁠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

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>