config.reference.json

{
    "_docs": "Reference for every config.json key, each shown with its default value. Copy ONLY the keys you actually want to change into config.json; any key you omit keeps the default shown here. The pool target is the native XMRig 'pools' array: each pool needs a 'url' (host:port); every other field falls back to a Pithead-friendly default. A pool's 'user' is the rig's label on the dashboard (defaults to the machine hostname); list multiple entries for failover. Optional pool fields: 'rig-id' is a separate worker label while 'user' remains the login; 'nicehash' enables the pool-assigned nonce protocol; 'algo' pins a supported rx/* algorithm; 'coin' selects a supported RandomX coin by case-insensitive name or code; and 'sni' sends the pool hostname during TLS setup. These five fields are omitted when absent or null; explicit false is preserved for the strict-boolean 'nicehash' and 'sni' fields. 'pass' is the Stratum password or worker name; 'keepalive' sends requests that prevent idle timeout; 'tls' enables encrypted Stratum; and 'enabled' controls whether XMRig may connect to the entry during failover. A pool's 'socks5' (default null) dials that pool through a SOCKS5 proxy given as host:port \u2014 e.g. \"127.0.0.1:9050\" for a local Tor client, which is how a rig reaches a stratum published as an onion service; XMRig sends the hostname to the proxy, so the proxy resolves it. RigForge points the miner at a proxy, it does not install or run one. An empty ACCESS_TOKEN (the default) leaves the rig's read-only HTTP API open (no token) — which matches Pithead's default no-auth stats probe; set a value only to require a Bearer token (then match it dashboard-side). 'ACCESS_TOKENS' (default {}) is an optional name -> token map, one token per Pithead stack that consumes this rig, so rotating the bench's token never touches production's: every entry is accepted on the sister API (:8081, raw or its own HMAC-derived read bearer) and the writable control path (:8082, raw), while XMRig's own :8080 and the control path's pools restore stay ACCESS_TOKEN's alone — a stack that probes :8080 directly must hold the master. 'autotune' is one of \"disabled\" (default — no scheduled tuning), \"performance\" (monthly tune for raw hashrate), or \"efficiency\" (monthly tune for hashrate-per-watt). 'watchdog' set to \"enabled\" installs a timer that health-checks the miner every 'watchdog_interval_min' minutes (default 5) and restarts it after two consecutive checks see 0 H/s or a dead API; 'max_temp_c' (empty = off) additionally stops the miner above that °C and starts it again 5°C below — check what your board's thermal_zone0 reports before setting it. 'miner_user' (empty = run as root, the default) runs the miner as that dedicated non-root system user — RigForge applies the MSR preset root-side; on CPU families without a known preset the ~10-15% MSR boost is skipped. 'api_allow_from' (empty = off) scopes the API port(s) — including the writable control port when 'control' is enabled — to one IPv4 or IPv6 address/CIDR source + loopback via an own nftables table (Linux, needs nft; for an IPv6 source the served port must bind a v6 address, so set 'api_bind'/'control_bind' to \"::\"). Set 'api' to enabled for the sister API: a second read-only port (default 8081) serving XMRig's summary enriched with RigForge tune/power/health/provenance data, gated by the same ACCESS_TOKEN; 'api_port'/'api_bind' place it. Set 'control' to \"enabled\" for the WRITABLE control path (#236): a SEPARATE authenticated port (default 8082, 'control_port'/'control_bind' place it) that lets a Pithead stack apply config changes through RigForge so config.json stays authoritative. Fail-closed: enabling it REQUIRES both ACCESS_TOKEN and api_allow_from (a writable API with no token or no pinned source is refused). Only pools, DONATION, autotune, watchdog(+interval), and max_temp_c are writable through it (and the REMOTE path refuses to disable watchdog or to unset/out-of-band max_temp_c — a rig's thermal protection can only be removed by a local rigforge.sh apply, #257); every change is validated, the old config is snapshotted to config-backups/, and a change that doesn't come back live is rolled back. Set 'control_upgrade' to \"enabled\" (a SECOND opt-in, only valid when 'control' is also enabled) to let the stack trigger this rig to upgrade its own RigForge to the latest release (#308, ADR 0002) — i.e. fetch and run new root code on a remote trigger. Default off, and never on just because 'control' is: the rig refuses any target that isn't a real release newer than the one running, verifies the release commit is reachable on main (the release branch), throttles repeat runs, and health-gates the swap with rollback. It rides the control path's own Bearer token + api_allow_from pin. Releases are checksummed, not signed — GitHub is the trust root (see SECURITY.md). 'tor_socks5' (default null) sends RigForge's own fetches through one SOCKS5 proxy given as host:port, e.g. \"127.0.0.1:9050\" for a local Tor client: upgrade --check, the pinned XMRig source clone and the remote upgrade's git fetch, with remote name resolution and no direct fallback (an unreachable proxy is an error). It does not cover package-manager installs (apt, dnf, pacman, brew, the jq bootstrap), which stay the operator's to route, and it is separate from a pool's 'socks5'. For co-locating a miner on a busy box (e.g. a Pithead stack host), 'hugepages_reserve_extra_mb' (default 0) adds that many MB of HugePages to RigForge's computed mining reservation so the pool covers stack + miner — RigForge stays the sole writer of the reservation and, when the box's existing reservation already covers both, changes nothing and needs no reboot; 'hugepages_pool_ceiling_mb' (default 0 = no ceiling) is a HARD CAP on the runtime pool RigForge will grow to, in MB, distinct from hugepages_reserve_extra_mb (which adds declared headroom into the computed requirement rather than bounding the write) — set it on a RAM-constrained co-resident box so the grow-only write can never exceed the box's honest capacity no matter what the requirement/availability math computes (rigforge#398; an odd MB value floors to the 2MB page below, e.g. 5121 -> 5120MB effective, never rounds up past the declared ceiling). It bounds the PERSISTED reservation too: the 2MB `hugepages=` RigForge merges into the GRUB cmdline is capped the same way, so the pool does not come back up over the ceiling after a reboot, where the grow-only runtime write could never bring it down again (rigforge#410). The 1GB dataset reservation is a separate pool this key has never described and is not capped, so a ceiling below a box's 1GB reservation still leaves it holding more hugepage memory than the ceiling names; 'threads' (empty/null = auto) caps the RandomX thread count (a ceiling — min(auto, threads), e.g. nproc-2) so the miner leaves spare cores, and it sizes the reservation to match. A TLS pool can pin the server certificate with 'tls-fingerprint' (its SHA-256 as 64 hex chars; null = no pin) — XMRig does no CA verification for stratum, so the pin is the only server authentication TLS stratum has. 'xmrig' deep-merges local XMRig settings after tuned overrides and before the threads cap; its randomx.mode (\"auto\", \"fast\" default, or \"light\"), randomx.init (-1 auto or 1..2147483647) and randomx.init-avx2 (-1 auto, 0 off, 1 on) are validated. For example: {\"cpu\":{\"priority\":2,\"yield\":true},\"randomx\":{\"scratchpad_prefetch_mode\":1},\"print-time\":60}. Overlay pins are excluded from tuning. The pool 'coin' lets XMRig choose the algorithm for that coin. Both 'algo' and 'coin' defer to pool algorithm negotiation; avoid 'coin' with NiceHash, where the pool controls the coin. Full descriptions: https://github.com/p2pool-starter-stack/rigforge/blob/main/docs/configuration.md#configuration-reference Optional solo daemon pool example (replace an entry in pools): {\"url\": \"daemon+http://<NODE_AUTHORITY>\", \"user\": \"<PAYOUT_USER>\", \"daemon\": true, \"daemon-poll-interval\": 1000, \"daemon-job-timeout\": 15000}. Optional example: replace NODE_AUTHORITY with your node's host and RPC port, and PAYOUT_USER with its payout identity. RigForge does not install, run or supervise the node. self-select, submit-to-origin and spend-secret-key are unsupported. A daemon+ URL implies daemon: true; explicit false is refused. Timing values are positive JSON integers no greater than 9007199254740991 milliseconds; integral decimal and exponent values are written in integer notation. Omit optional fields to use XMRig defaults. Daemon pools cannot use socks5 or tls-fingerprint because the pinned miner ignores them. Daemon HTTPS encrypts without authenticating the peer; doctor's HTTPS RPC check uses curl's CA verification.",

    "pools": [
        {
            "url": "<YOUR_POOL_HOST>:3333",
            "user": "",
            "pass": "x",
            "rig-id": null,
            "nicehash": false,
            "algo": null,
            "coin": null,
            "keepalive": true,
            "tls": false,
            "tls-fingerprint": null,
            "sni": false,
            "socks5": null,
            "enabled": true
        }
    ],

    "ACCESS_TOKEN": "",
    "ACCESS_TOKENS": {},
    "api_allow_from": "",
    "miner_user": "",

    "api": "disabled",
    "api_port": 8081,
    "api_bind": "0.0.0.0",

    "control": "disabled",
    "control_port": 8082,
    "control_bind": "0.0.0.0",
    "control_upgrade": "disabled",
    "tor_socks5": null,

    "DONATION": 0,
    "autotune": "disabled",
    "watchdog": "disabled",
    "watchdog_interval_min": 5,
    "max_temp_c": "",
    "add_to_path": false,

    "hugepages_reserve_extra_mb": 0,
    "hugepages_pool_ceiling_mb": 0,
    "threads": null,
    "shared_host": false,
    "xmrig": {
        "randomx": {
            "mode": "fast",
            "init": -1,
            "init-avx2": -1
        }
    },

    "HOME_DIR": "DYNAMIC_HOME"
}