> ## Documentation Index
> Fetch the complete documentation index at: https://xoxno.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

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

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

## Shortest commands

```bash theme={"system"}
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:

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

Inspect what won where:

```bash theme={"system"}
mxnode config show --origin
```

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

## Auto-created config

On the first state-changing command:

```toml theme={"system"}
# 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

```toml theme={"system"}
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). |

```bash theme={"system"}
export MXNODE_GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxx
```

Tokens are **never written to disk** by mxnode.

## Inspecting config

```bash theme={"system"}
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

```bash theme={"system"}
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

```bash theme={"system"}
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

```toml theme={"system"}
[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

<Tabs>
  <Tab title="Multikey primary, mainnet">
    ```toml theme={"system"}
    schema_version = 1

    [network]
    environment = "mainnet"

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

    [overrides.prefs]
    "Preferences.Identity" = "operator-org"
    ```
  </Tab>

  <Tab title="Observer squad on a fork">
    ```toml theme={"system"}
    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"
    ```
  </Tab>

  <Tab title="Testnet observer with custom log level">
    ```toml theme={"system"}
    schema_version = 1

    [network]
    environment = "testnet"

    [node]
    log_level = "*:INFO"
    extra_flags = "-profile-mode"
    ```
  </Tab>
</Tabs>