Configuration

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

[!WARNING] 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

[!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

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

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

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.

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

To regenerate the genesis for a different network:

go run ./scripts/gen-genesis/ mainnet

See also

• Node CLI -- interactive commands and flag usage
• Infrastructure Setup -- setup-node.sh and initial deployment
• System Constants -- hard-coded system constants