Install shapes - XOXNO Docs

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

# 1 validator
mxnode install

# 4-shard multikey squad (one node per shard)
mxnode install --role multikey

# 4-shard observer squad
mxnode install --role observer --squad

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

For other roles, --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

See multikey + redundancy for the full setup recipe.

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`

​Shortest commands

​All flags

​Common shapes

​Why multikey doesn’t take --squad

​Backup machines

​What changes per role

​Misuse rejections