Configuration Reference¶

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

Node flags¶

The xe binary accepts the following command-line flags (via xe node [flags]):

General¶

Flag	Default	Description
`-version`	`false`	Print version string and exit
`-port`	`9000`	libp2p TCP listen port
`-api-port`	`8080`	HTTP API listen port
`-api-bind`	`127.0.0.1`	API bind address
`-dial`	(none)	Bootstrap peer multiaddr(s), comma-separated
`-data`	`./data`	Storage directory for BadgerDB, identity keys, and Lima VM state
`-cors-origin`	`http://localhost:3000`	Allowed CORS origin for API responses

Provider mode¶

Flag	Default	Description
`-provide`	`false`	Enable compute provider mode
`-vcpus`	`2`	vCPUs to offer for leasing
`-memory`	`2048`	Memory in MB to offer for leasing
`-disk`	`20`	Disk in GB to offer for leasing
`-ssh-port`	`0`	SSH gateway listen port (0 = disabled)
`-limactl-path`	`limactl`	Path to the limactl binary

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

API bind address

The default -api-bind 127.0.0.1 only allows local connections. Set -api-bind 0.0.0.0 to allow connections from the Caddy reverse proxy. Never expose the API directly to the internet without a reverse proxy.

Environment variables¶

Used in the deployment .env file at /opt/xe/deploy/.env:

Variable	Description	Example
`DOMAIN`	Primary domain for Caddy TLS and routing	`ldn.test.network`
`CORE_DOMAIN`	Domain for direct API access	`ldn.core.test.network`
`NODE_FLAGS`	All flags passed to the xe node binary	`-port 9000 -api-port 8080 ...`

The ecosystem.config.js reads NODE_FLAGS from the .env file and passes it as command-line arguments to the xe node binary. Caddy reads DOMAIN and CORE_DOMAIN via --envfile.

Data directory¶

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

Path	Content	Notes
`badger/`	BadgerDB database files	WAL, value log, manifest — all blocks, chains, leases, state chain
`host.key`	libp2p identity private key	Ed25519, determines peer ID. Persisted across restarts.
`node.key`	Node account private key	Ed25519, used for signing blocks and attestations
`ssh_host_key`	SSH gateway host key	Ed25519, generated on first SSH gateway start
`lima/`	Lima VM state (LIMA_HOME)	Per-VM directories with disk images, sockets, logs
`lima-templates/`	Lima YAML templates	Per-VM config files used during `limactl create`
`images/`	VM base images	Ubuntu 24.04 cloud image (~600 MB), auto-downloaded on first provider startup

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¶

Port	Protocol	Service	Exposed
9000	TCP	libp2p (peer-to-peer)	Yes (firewall open)
8080	TCP	HTTP API (xe node)	No (localhost only, via Caddy)
80	TCP	Caddy (HTTP, ACME challenges)	Yes (firewall open)
443	TCP	Caddy (HTTPS, TLS termination)	Yes (firewall open)
2222	TCP	SSH gateway (if `-ssh-port` set)	Optional (firewall open if used)

Process management¶

The node is managed by pm2 with the config at /opt/xe/deploy/ecosystem.config.js:

Process	Binary	User	Description
`xe node`	`/usr/local/bin/xe node`	`xe`	Core node (non-root for Lima compatibility)
`caddy`	`/usr/bin/caddy`	`root`	Reverse proxy and static file server

Common pm2 commands:

pm2 list                    # Show process status
pm2 logs xe node            # Stream xe 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

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.

State chain genesis¶

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

Key	Description
`sys.dao_keyset`	DAO governance keys (3 keys, threshold 2)
`sys.network_id`	Network identifier (e.g. "testnet"). Included in all block hashes.
`sys.timekeepers`	Trusted timekeeper keys + threshold. Required for lease operations.

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.

To regenerate the genesis for a different network:

go run ./scripts/gen-genesis/ mainnet