Install and configure the first X2 node

Complete these steps in order. Encryption and multi-node expansion are separate workflows linked at the exact points where they become relevant.

Before you begin

Use empty data and metadata paths. Production deployments need static node addresses, synchronized time, trusted TLS, and a deliberate encryption decision.

Decide encryption first Review cluster topology

Prepare the host

Supported 64-bit Linux, Windows, or macOS host
Administrator/root access for service installation
Unique node ID, public URL, and routable mesh address
One or more empty object-data roots
A separate durable metadata root
TCP 8443 for clients and TCP 9443 between nodes

Download X2 Node, XC, and the installer

Select your OS and architecture. Commands are populated from the signed release catalog.

Operating system

Architecture

Loading release catalog…

Loading release catalog…

Loading release catalog…

Verify the binary

sha256sum ./x2-node
# Compare with the release manifest
chmod 0755 ./x2-node

Get-FileHash .\x2-node.exe -Algorithm SHA256
# Compare Hash with the release manifest

shasum -a 256 ./x2-node
# Compare with the release manifest
chmod 0755 ./x2-node

Do not install an artifact whose digest or size differs from the immutable release manifest.

Choose paths and network identities

Replace every value enclosed in <...>. Keep these variables in the same terminal while completing the remaining steps. The configuration path is operator selected; it is not required to use the platform default.

X2_CONFIG_PATH='/etc/x2/node.yaml'
X2_RUNTIME_ROOT='/var/lib/x2'
X2_DISK_PATHS='/data/x2/disk{1...4}'
X2_METADATA_PATH='/data/x2/metadata'
X2_PUBLIC_URL='https://<PUBLIC_DNS_OR_IP>:8443'
X2_MESH_ADVERTISE='<NODE_MESH_IP>:9443'

$X2ConfigPath = 'C:\ProgramData\X2\config\node.yaml'
$X2RuntimeRoot = 'C:\ProgramData\X2\runtime'
$X2DiskPaths = 'D:\x2\data{1...4}'
$X2MetadataPath = 'D:\x2\metadata'
$X2PublicUrl = 'https://<PUBLIC_DNS_OR_IP>:8443'
$X2MeshAdvertise = '<NODE_MESH_IP>:9443'

X2_CONFIG_PATH='/usr/local/etc/x2/node.yaml'
X2_RUNTIME_ROOT='/usr/local/var/lib/x2'
X2_DISK_PATHS='/Volumes/X2Data/disk{1...4}'
X2_METADATA_PATH='/Volumes/X2Metadata'
X2_PUBLIC_URL='https://<PUBLIC_DNS_OR_IP>:8443'
X2_MESH_ADVERTISE='<NODE_MESH_IP>:9443'

The public URL is the exact URL clients will use. Keep :8443 for direct node access; omit the port when an HTTPS proxy exposes X2 on the standard port 443. The mesh advertise address is this node's stable inter-node address, including port 9443 unless you intentionally configured another mesh port.

Configure the first node

Encryption checkpointIf production data requires provider-backed encryption, finish the encryption guide before starting this node.

chmod 0755 ./x2-node
sudo ./x2-node configure "${X2_DISK_PATHS}" \
  --metadata "${X2_METADATA_PATH}" --root "${X2_RUNTIME_ROOT}" \
  --address '0.0.0.0:8443' --public-url "${X2_PUBLIC_URL}" \
  --internal-address '0.0.0.0:9443' --internal-advertise "${X2_MESH_ADVERTISE}" \
  --admin-user admin --admin-password '<STRONG_ADMIN_PASSWORD>' \
  --config "${X2_CONFIG_PATH}"
sudo test -s "${X2_CONFIG_PATH}"

.\x2-node.exe configure $X2DiskPaths `
  --metadata $X2MetadataPath --root $X2RuntimeRoot `
  --address '0.0.0.0:8443' --public-url $X2PublicUrl `
  --internal-address '0.0.0.0:9443' --internal-advertise $X2MeshAdvertise `
  --admin-user admin --admin-password '<STRONG_ADMIN_PASSWORD>' `
  --config $X2ConfigPath
if (-not (Test-Path -LiteralPath $X2ConfigPath)) { throw 'Configuration was not created' }

chmod 0755 ./x2-node
sudo ./x2-node configure "${X2_DISK_PATHS}" \
  --metadata "${X2_METADATA_PATH}" --root "${X2_RUNTIME_ROOT}" \
  --address '0.0.0.0:8443' --public-url "${X2_PUBLIC_URL}" \
  --internal-address '0.0.0.0:9443' --internal-advertise "${X2_MESH_ADVERTISE}" \
  --admin-user admin --admin-password '<STRONG_ADMIN_PASSWORD>' \
  --config "${X2_CONFIG_PATH}"
sudo test -s "${X2_CONFIG_PATH}"

This command creates the restart-safe snapshot containing the disk and metadata roots. The service installer must receive this same configuration path.

Install the operating-system service

Installation validates that the selected configuration exists and registers the service without starting it. Running the installer again replaces the installed binary and service definition while preserving configuration and data; a running service is restarted and a stopped service remains stopped.

sudo bash ./install-x2-node.sh \
  --binary "$(realpath ./x2-node)" \
  --config "${X2_CONFIG_PATH}"

Set-ExecutionPolicy -Scope Process Bypass
.\install-x2-node-service.ps1 `
  -BinaryPath (Resolve-Path .\x2-node.exe) `
  -ConfigPath $X2ConfigPath

sudo bash ./install-x2-node.sh \
  --binary "$PWD/x2-node" \
  --config "${X2_CONFIG_PATH}"

Run the configured node in the foreground instead

./x2-node server --config="${X2_CONFIG_PATH}"

.\x2-node.exe server --config $X2ConfigPath

./x2-node server --config="${X2_CONFIG_PATH}"

Start and verify

sudo systemctl enable --now x2-node
systemctl status x2-node
curl --fail --cacert '<PUBLIC_CA_FILE>' "${X2_PUBLIC_URL}/health/ready"

Start-Service X2Node
Get-Service X2Node
Invoke-WebRequest "${X2PublicUrl}/health/ready"

sudo launchctl bootstrap system /Library/LaunchDaemons/com.edgedrive.x2-node.plist
sudo launchctl print system/com.edgedrive.x2-node
curl --fail --cacert '<PUBLIC_CA_FILE>' "${X2_PUBLIC_URL}/health/ready"

Open the public URL, sign in with the bootstrap administrator, and confirm the node, metadata root, and disks are healthy.

Configure XC

chmod 0755 ./xc
./xc alias set x2 "${X2_PUBLIC_URL}" '<ACCESS_KEY>' '<SECRET_KEY>' --ca-file '<PUBLIC_CA_FILE>'
./xc admin info x2

.\xc.exe alias set x2 $X2PublicUrl '<ACCESS_KEY>' '<SECRET_KEY>' --ca-file '<PUBLIC_CA_FILE>'
.\xc.exe admin info x2

chmod 0755 ./xc
./xc alias set x2 "${X2_PUBLIC_URL}" '<ACCESS_KEY>' '<SECRET_KEY>' --ca-file '<PUBLIC_CA_FILE>'
./xc admin info x2

Installation complete

For additional nodes continue to the cluster guide. For production encryption configure the provider before storing data.

Add nodes →Enable encryption →