Configuration - XOXNO Docs

config.toml schema, environment variables, override layering, and the mxnode config commands.

Shortest commands

mxnode config show                        # print the merged config
mxnode config get network.environment     # one dotted-path lookup
mxnode config set network.environment testnet

mxnode reads a layered configuration. The config file lives at ~/.config/mxnode/config.toml (auto-created on first use); a system-wide /etc/mxnode/config.toml is also honored. CLI flags override both.

Resolution order

Highest-precedence layer wins:

CLI flags — mxnode upgrade --binary-tag v1.11.5 beats anything in the file.
User config — ~/.config/mxnode/config.toml.
System config — /etc/mxnode/config.toml.
Built-in defaults — compiled into mxnode-config.

Inspect what won where:

mxnode config show --origin

Each leaf is annotated default, system, user, or flag.

Auto-created config

On the first state-changing command:

# mxnode config — generated automatically on first use.
# Edit freely; mxnode preserves unknown keys on round-trip.
# Switch network with: `mxnode config set network.environment <testnet|devnet>`.

schema_version = 1

[network]
environment = "mainnet"

[paths]
custom_home = "/home/<you>"
custom_user = "<you>"
node_keys = "{custom_home}/VALIDATOR_KEYS"

Auto-detected $USER / $HOME come from $USER → $LOGNAME → $HOME (in that order).

Full schema

schema_version = 1

[network]
environment = "mainnet"      # mainnet | testnet | devnet
github_org = "multiversx"    # override for forks
gateway = "https://gateway.multiversx.com"   # used by `mxnode dashboard` for trie stats

[paths]
custom_home = "/home/<you>"
custom_user = "<you>"        # systemd User=
node_keys = "{custom_home}/VALIDATOR_KEYS"
binaries = "{custom_home}/mxnode/binaries"
state = "{XDG_STATE_HOME}/mxnode"
runtime = "{XDG_RUNTIME_DIR}/mxnode"

[node]
api_port_base = 8080         # node-N listens on api_port_base + N
log_level = "*:DEBUG"
limit_nofile = 4096
restart_sec = 3
extra_flags = ""             # appended to the node ExecStart line
name_template = "mx-chain-{env}-validator-{index}"

[proxy]
server_port = 8079
observers_shards = [0, 1, 2, 4294967295]   # 4294967295 == metachain

[install]
artifact_source = "source"   # source | release | auto
binary_keep = 3              # how many tags to retain in the binstore

[overrides]
configver = ""               # pin mx-chain-config tag
proxyver = ""                # pin mx-chain-proxy-go tag
binaryver = ""               # pin mx-chain-go tag
goversion = ""               # pin Go toolchain version (default 1.22.12)

# Apply these dotted-path edits to every node's prefs.toml after install
[overrides.prefs]
"Preferences.Identity" = "your-github-handle"

# Apply these to every node's config.toml
[overrides.config]
"DbLookupExtensions.Enabled" = true

[metrics]
enabled = false
listen = "127.0.0.1:9090"

[branding]
title = "By XOXNO ✦ TrustStaking"   # dashboard top bar

Path placeholders

[paths] values support these placeholders:

Placeholder	Resolved to
`{custom_home}`	The value of `paths.custom_home`
`{home}`	The OS-detected `$HOME`
`{XDG_STATE_HOME}`	`$XDG_STATE_HOME` if set, else `$HOME/.local/state`
`{XDG_RUNTIME_DIR}`	`$XDG_RUNTIME_DIR` if set, else `<state>/run`

Environment variables

Only one is read:

Variable	Purpose
`MXNODE_GITHUB_TOKEN`	GitHub PAT for authenticated API requests. Lifts the unauthenticated rate limit (60 req/h).

export MXNODE_GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxx

Tokens are never written to disk by mxnode.

Inspecting config

mxnode config show                      # pretty-print merged config
mxnode --json config show               # JSON for scripts
mxnode config show --origin             # annotate per-leaf origin
mxnode config get network.environment   # dotted-path lookup

Modifying config

mxnode config set network.environment testnet
mxnode config set install.artifact_source release
mxnode config set --scope system network.gateway https://gateway.example.com
mxnode config edit                       # opens in $EDITOR

config set round-trips through toml_edit, so operator comments and section ordering are preserved.

Validation

mxnode config validate
mxnode config validate --strict          # adds network reachability

Artifact source

Controls how mxnode install and mxnode upgrade acquire binaries:

Value	Behaviour
`source` (default)	`git clone --depth=1` + `go build`
`release`	Download `multiversx_*_linux_<arch>.zip` from GitHub Releases + sha256 verify
`auto`	Try release first; fall back to source if no matching asset exists

Running from a fork

[network]
github_org = "your-org"

mxnode then resolves tags from https://api.github.com/repos/your-org/mx-chain-go/releases and clones from https://github.com/your-org/mx-chain-go.git.

Sample configs

Multikey primary, mainnet
Observer squad on a fork
Testnet observer with custom log level

schema_version = 1

[network]
environment = "mainnet"

[paths]
custom_home = "/home/operator"
custom_user = "operator"

[overrides.prefs]
"Preferences.Identity" = "operator-org"

schema_version = 1

[network]
environment = "mainnet"
github_org = "myfork"

[install]
artifact_source = "release"
binary_keep = 5

[overrides]
binaryver = "v1.11.5"
configver = "v1.11.5.0"

schema_version = 1

[network]
environment = "testnet"

[node]
log_level = "*:INFO"
extra_flags = "-profile-mode"

​Shortest commands

​Resolution order

​Auto-created config

​Full schema

​Path placeholders

​Environment variables

​Inspecting config

​Modifying config

​Validation

​Artifact source

​Running from a fork

​Sample configs