Deployment Center/Install

Install an X2 cluster node

For a single-server service, use the permanent standalone installation guide.

Initialize the first cluster member or enroll an additional node, validate membership, and then publish the cluster through a load balancer.

Deployment mode

Single-server installation is always permanent standalone. The commands below initialize or join a planned multi-server cluster; a first bootstrap node is a cluster seed, not an alternative single-server mode.

Select the X2 Node platform

All steps and commands below update for the selected operating system.

Operating system

DockerComing soon KubernetesComing soon

Architecture

Linux

Linux production installation

Install one independent X2 Node as a systemd service and validate it with systemctl.

Install an X2 cluster member as a systemd service, validate membership, then place NGINX or HAProxy in front of the node pool.

Windows

Windows production installation

Install one independent X2 Node as a Windows service and validate it with PowerShell.

Install an X2 cluster member as a Windows service, validate membership, and use a dedicated load-balancer host for production traffic.

macOS

macOS production installation

Install one independent X2 Node as a launchd service and validate it with launchctl.

Install an X2 cluster member as a launchd service, validate membership, and use a dedicated load-balancer host for production traffic.

Before you begin

Choose the intended storage disks and system-volume paths. Production deployments need synchronized time, trusted TLS, and a deliberate encryption decision. Cluster members also need stable private addresses and mesh connectivity.

Decide encryption first Review cluster installation

Prepare the host

Supported 64-bit Linux, Windows, or macOS host
Administrator/root access for service installation
Unique node ID and routable mesh address
One or more object-data roots
A durable system volume (--metadata) for WAL, manifests, configuration, and node state
TCP 8443 for client and Console access
TCP 8443 for clients and TCP 9443 between nodes

Download X2 Node

The selected platform and architecture are applied to the signed release catalog automatically.

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 storage paths

Replace every value enclosed in <...>. Keep these variables in the same terminal while completing the remaining steps. The --metadata option selects the system volume and its persistent configuration. Metadata snapshots are replicated on storage disks; this does not make distributed-mode system volumes disposable.

X2_DISK_PATHS='<DISK_PATHS>'
X2_METADATA_PATH='<METADATA_PATH>'

$X2DiskPaths = '<DISK_PATHS>'
$X2MetadataPath = '<METADATA_PATH>'

X2_DISK_PATHS='<DISK_PATHS>'
X2_METADATA_PATH='<METADATA_PATH>'

X2 listens on 0.0.0.0:8443 for public traffic and 0.0.0.0:9443 for the cluster mesh by default. It discovers the node's advertise IP automatically. Use the optional Network Overrides in Command Assist only for a non-standard port, a specific interface, or an externally visible public URL.

Configure this machine

Configure this cluster node

Single-server deployments use permanent standalone setup; the cluster commands below are not a single-server alternative.

Choose whether this machine creates the cluster or joins one. Storage, service installation, and verification remain platform-specific.

Initialize X2 on this machine

Initialize the first cluster 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 --deployment-mode distributed "${X2_DISK_PATHS}" \
  --metadata "${X2_METADATA_PATH}"{{X2_NETWORK_OPTIONS}} \
  --admin-user '<ADMIN_USER>' --admin-password '<STRONG_ADMIN_PASSWORD>'
sudo test -s "${X2_METADATA_PATH}/.x2/config/node.yaml"

.\x2-node.exe configure --deployment-mode distributed $X2DiskPaths `
  --metadata $X2MetadataPath{{X2_NETWORK_OPTIONS}} `
  --admin-user '<ADMIN_USER>' --admin-password '<STRONG_ADMIN_PASSWORD>'
if (-not (Test-Path -LiteralPath (Join-Path $X2MetadataPath '.x2\config\node.yaml'))) { throw 'Configuration was not created' }

chmod 0755 ./x2-node
sudo ./x2-node configure --deployment-mode distributed "${X2_DISK_PATHS}" \
  --metadata "${X2_METADATA_PATH}"{{X2_NETWORK_OPTIONS}} \
  --admin-user '<ADMIN_USER>' --admin-password '<STRONG_ADMIN_PASSWORD>'
sudo test -s "${X2_METADATA_PATH}/.x2/config/node.yaml"

Join an existing cluster

In the existing cluster, sign in as a system administrator and open Nodes → Install New Node. Enter this server's node name, private IP address, and mesh port, then paste the generated link into Command Assist below.

chmod 0755 ./x2-node
sudo ./x2-node configure --deployment-mode distributed "${X2_DISK_PATHS}" \
  --metadata "${X2_METADATA_PATH}"{{X2_NETWORK_OPTIONS}} \
  --join-link '<CLUSTER_JOIN_LINK>'
sudo test -s "${X2_METADATA_PATH}/.x2/config/node.yaml"

.\x2-node.exe configure --deployment-mode distributed $X2DiskPaths `
  --metadata $X2MetadataPath{{X2_NETWORK_OPTIONS}} `
  --join-link '<CLUSTER_JOIN_LINK>'
if (-not (Test-Path -LiteralPath (Join-Path $X2MetadataPath '.x2\config\node.yaml'))) { throw 'Configuration was not created' }

chmod 0755 ./x2-node
sudo ./x2-node configure --deployment-mode distributed "${X2_DISK_PATHS}" \
  --metadata "${X2_METADATA_PATH}"{{X2_NETWORK_OPTIONS}} \
  --join-link '<CLUSTER_JOIN_LINK>'
sudo test -s "${X2_METADATA_PATH}/.x2/config/node.yaml"

The join link is single-use, bound to this node's requested mesh endpoint, and expires after 15 minutes. Selecting this tab adds --join-link; first-node commands omit it.

This creates .x2/config/node.yaml beneath the first metadata root. State and secrets are placed in that metadata-owned .x2 directory. Logs use the platform-standard X2 log directory.

Install the operating-system service

The executable installs itself and references the configuration under metadata, registers the native service, configures restart recovery, and starts it. No separate installer or service-definition download is required.

sudo ./x2-node service install --metadata "${X2_METADATA_PATH}"

.\x2-node.exe service install --metadata $X2MetadataPath

sudo ./x2-node service install --metadata "${X2_METADATA_PATH}"

Run the configured node in the foreground instead

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

.\x2-node.exe server --config (Join-Path $X2MetadataPath '.x2\config\node.yaml')

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

Verify the running service

Set the public URL to the endpoint clients will actually use: the node’s configured public URL for a single-node installation, or the load-balancer URL after a cluster is published. The listen address binds a local socket, the node/advertised address identifies peer reachability, and neither is automatically the client URL.

Establish certificate trust first.

Copy only the issuing public CA certificate to the verification host, confirm the URL hostname or IP appears in the server certificate SAN, and keep every CA private key on its protected issuer host. Then run the HTTPS readiness request.

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

$X2PublicUrl = '<X2_PUBLIC_URL>'
Get-Service X2Node
Invoke-WebRequest "${X2PublicUrl}/health/ready"

X2_PUBLIC_URL='<X2_PUBLIC_URL>'
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.

Add a production load balancer

NGINX and HAProxy can run on dedicated Linux load-balancer hosts in front of the X2 Linux nodes. Keep client traffic on the public listener and never send the node mesh through the load balancer.

Keep X2 on Windows and run NGINX or HAProxy on a dedicated Linux load-balancer host. NGINX for Windows is a beta build whose own documentation does not recommend it for high performance or scalability.

Keep X2 on macOS and run NGINX or HAProxy on a dedicated Linux load-balancer host for production traffic. This keeps TLS, health checks, and backend rotation independent from the storage nodes.

NGINX Streaming S3 requests, verified upstream TLS, health-aware node pools, and WebSocket upgrades. Open NGINX setup → HAProxy Least-connection balancing, active readiness checks, long-lived streams, and verified backend TLS. Open HAProxy setup →

X2 accepts valid forwarded headers without a CIDR allowlist. Restrict trusted load-balancer CIDRs only when direct access to the X2 listener must not be allowed to assert forwarded values.

0809

Configure XC

XC is optional and downloaded separately from the downloads page when command-line access is needed.

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

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

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

Single machine installation complete Cluster-node installation complete

Open the Console, create a storage account, and connect XC or an S3 application. Configure a KMI provider before storing data that requires provider-backed encryption.

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

Add nodes →Enable encryption →