mxnode install accepts a small set of orthogonal flags that combine into every supported shape. Default is one validator, no squad, no proxy.
Shortest commands
--squad is implicit for --role multikey and explicit for everyone else.
All flags
| Flag | Default | Effect |
|---|---|---|
--role validator|observer|multikey | validator | What kind of node. Drives key handling. |
--squad | off | Pin 4 nodes to shards 0/1/2/metachain. Implicit for multikey. |
--with-proxy | off | Also install the MultiversX proxy alongside the nodes. Rejected for --role multikey — proxies belong with observers, not signing nodes. |
--count <N> | 1 | Number of nodes (without --squad). Each gets Shard::Auto. Rejected for multikey. |
--keys-file <PATH> | auto-detect | Multikey: path to allValidatorsKeys.pem. |
--backup [<N>] | off | Multikey: mark this host as a backup. Pass --backup for level 1, --backup 2 for backup-of-backup, etc. |
--binary-tag <T> | latest | Pin the mx-chain-go tag. |
--config-tag <T> | latest | Pin the mx-chain-mainnet-config tag. |
--proxy-tag <T> | latest | Pin the mx-chain-proxy-go tag (with --with-proxy). |
--dry-run | off | Print the plan without doing anything. |
Common shapes
| Shape | Command | Result |
|---|---|---|
| Multikey squad (primary) | mxnode install --role multikey | Four nodes signing for ~/VALIDATOR_KEYS/allValidatorsKeys.pem. Squad is implicit. |
| Multikey squad (backup) | mxnode install --role multikey --backup | Same allValidatorsKeys.pem; takes over signing if the primary fails. RedundancyLevel = 1. |
| Observer squad | mxnode install --role observer --squad | Four observers, one per shard. No keys to manage. |
| Observer squad + proxy | mxnode install --role observer --squad --with-proxy | The observing-squad gateway shape. |
| Single validator | mxnode install --role validator | Operator drops node-0.zip into ~/VALIDATOR_KEYS/ before mxnode start. |
Why multikey doesn’t take --squad
A multikey host signs for every BLS key in the bundle behind whichever observer is in the right shard. Anything other than one node per shard breaks the model — fewer leaves shards uncovered, more duplicates them. --role multikey is therefore a 4-shard squad:
| Command | Result |
|---|---|
mxnode install --role multikey | 4 nodes, shards 0/1/2/metachain. ✓ |
mxnode install --role multikey --squad | Same. --squad is accepted as a no-op. |
mxnode install --role multikey --count 3 | Rejected — multikey is by-design 4-node. |
--squad is the way to opt into the same 4-shard layout.
Backup machines
The--backup flag stamps Preferences.RedundancyLevel on every node in a multikey install. Both primary and backup must hold the byte-identical allValidatorsKeys.pem:
| Command | RedundancyLevel | Meaning |
|---|---|---|
mxnode install --role multikey | 0 | Primary — signs unconditionally |
mxnode install --role multikey --backup | 1 | Backup — takes over if the primary stops responding |
mxnode install --role multikey --backup 2 | 2 | Backup-of-backup |
mxnode install --role multikey --backup 3 | 3 | And so on |
What changes per role
| Aspect | Validator | Observer | Multikey |
|---|---|---|---|
| Key file | node-{i}.zip per node | None — auto-generated on first start | allValidatorsKeys.pem distributed to every node |
prefs.toml DestinationShardAsObserver | Untouched (only with --squad) | Pinned with --squad | Pinned |
config.toml [DbLookupExtensions] Enabled | false | true | true |
prefs.toml RedundancyLevel | Untouched | Untouched | Stamped (0 primary, 1+ backup) |
mxnode keys check | Verifies zips | Skipped | Skipped |
Misuse rejections
mxnode rejects nonsensical combinations at parse time so you don’t waste a build:| Command | Outcome |
|---|---|
mxnode install --squad --count 4 | clap conflict — --squad is 4-node |
mxnode install --role multikey --count 3 | --count is rejected for --role multikey |
mxnode install --role multikey --with-proxy | --with-proxy is rejected for --role multikey (signing nodes shouldn’t co-host public RPC) |
mxnode install --keys-file foo --role observer | --keys-file only applies to --role multikey |
mxnode install --backup --role observer | --backup only applies to --role multikey |
mxnode install --role multikey (no allValidatorsKeys.pem anywhere) | multikey install requires allValidatorsKeys.pem |