Configuration

All configuration options for the XE node and its deployment environment.

Node flags

The xe binary takes these flags on its node subcommand (xe node [flags]). Go's flag package accepts either -flag or --flag. The version string is printed by the separate xe version subcommand, not by a flag.

General

HTTP API

Embedded web UI

The explorer and wallet ship inside the node binary as plain HTML and ES modules (core/web) — there is no separate build step. The UI server reverse-proxies its own /api/* to the API server, so -ui requires -api; starting with -ui and -api=false is a fatal error.

Provider mode

Provider auto-accept policy

Optional local filters applied before the stake, resource, and certificate gates. A zero or unset value means "no constraint", so the default policy is permissive. Inverted ranges (min above max) are rejected at startup.

[!WARNING] Non-baseline price multipliers are simulation-only Values other than 1000 are for simulation today; they require anti-cheat gates before production use.

Examples

Minimal standalone node:

xe node

Production node with bootstrap peers:

xe node \
  -port 9000 \
  -api-port 8080 \
  -api-bind 0.0.0.0 \
  -data /var/lib/xe-node \
  -dial /ip4/203.0.113.10/tcp/9000/p2p/12D3KooW...

Provider node with SSH gateway:

xe node \
  -provide \
  -vcpus 4 \
  -memory 8192 \
  -disk 100 \
  -ssh-port 2222 \
  -data /var/lib/xe-node \
  -dial /ip4/203.0.113.10/tcp/9000/p2p/12D3KooW...

[!WARNING] API bind address The default -api-bind 127.0.0.1 only allows local connections, which is all a same-host reverse proxy needs. Only widen it to 0.0.0.0 if something off-host must reach the API directly, and never expose the API to the internet without a reverse proxy in front of it. The same applies to -ui-bind.

Environment variables

Read by the node process

Read by the xe CLI

Deployment .env

Used by the pm2/Caddy deployment on the test network, at /opt/xe/deploy/.env:

The ecosystem.config.js reads NODE_FLAGS from the .env file and passes it as command-line arguments to the xe-node binary, so the value must start with node: the binary dispatches on its first argument and exits with unknown command if it sees a flag there. Caddy reads DOMAIN and CORE_DOMAIN via --envfile.

Data directory

The -data flag points to a directory containing all persistent state:

[!NOTE] Identity persistence The host.key file determines the node's peer ID on the network. If this file is deleted, the node generates a new identity and all other nodes' -dial flags must be updated. Back up this file if peer identity continuity matters.

Data directory sizing

BadgerDB stores all blocks, chains, pending sends, votes, conflicts, leases, and state chain data. For a test network, 1 GB is sufficient. Lima VMs consume additional disk for QCOW2 images (typically the lease's disk_gb value per VM).

Port summary

Process management

On the bootstrap nodes the node is managed by pm2 with the config at /opt/xe/deploy/ecosystem.config.js. The binary is installed as /usr/local/bin/xe-node and started with the node subcommand plus NODE_FLAGS.

Common pm2 commands:

pm2 list                     # Show process status
pm2 logs xe-node             # Stream node logs
pm2 restart xe-node          # Restart the node
pm2 restart caddy            # Restart Caddy
pm2 delete xe-node           # Remove from pm2 (for config reload)
pm2 start ecosystem.config.js --only xe-node   # Start from config
pm2 save                     # Persist process list across reboots

[!TIP] Config reload pm2 restart does not reload the ecosystem.config.js. To pick up new NODE_FLAGS from .env, you must pm2 delete xe-node and then pm2 start ecosystem.config.js --only xe-node.

Provider nodes are managed by systemd instead — see Provider Node Setup.

State chain genesis

The state chain genesis block (statechain/genesis.json) is embedded in the binary at compile time. It configures:

[!DANGER] Timekeepers must be in genesis Provider nodes refuse to start without sys.timekeepers configured. Timekeeper attestations are mandatory for lease acceptance and settlement — there is no fallback to self-reported timestamps.

The genesis is produced by the gen-genesis script in the core repo. -canonical regenerates the committed placeholder (deterministic keys, network_id of testnet) that lets a fresh clone build and test; a real deploy passes the live bootstrap node key seeds instead, which also mints a fresh random network ID so blocks from previous networks are rejected:

go run ./scripts/gen-genesis -canonical
go run ./scripts/gen-genesis -ldn-seed <hex> -ffm-seed <hex> -nyc-seed <hex>

[!NOTE] Ledger genesis is separate statechain/genesis.json above is the state chain genesis. The ledger genesis block — the one that mints the 42,000,000 XE launch supply — is a different embedded file and carries its own optional lease-timing pins.

See also

• Node CLI -- the xe command surface
• Bootstrap Node Setup -- host preparation and initial deployment
• System Constants -- hard-coded system constants