Node Operator Quickstart

This guide walks you through installing and running the full XChain platform stack on your own machine.

Prerequisites

Docker (Engine 20.10+) and Docker Compose — all XChain services run as Docker containers
Node.js 18 or later — required to run the xchain-node CLI
Disk space — blockchain data is large; plan for at least 600 GB for Bitcoin mainnet, or use testnet/regtest for development
Internet access — the installer downloads service images and blockchain binaries from GitHub

Step 1: Clone and Install xchain-node

xchain-node is the CLI orchestrator that manages every other service.

git clone https://github.com/XChain-Platform/xchain-node.git
cd xchain-node
npm install

Install the CLI globally so the xchain-node command is available from anywhere — every command in this guide assumes it:

npm link

Step 2: Run the Installer

The installer sets up Docker containers for all XChain services. Specify the chain and network you want to run:

# Install everything for Bitcoin mainnet
xchain-node install master all bitcoin mainnet

# Or for Dogecoin testnet
xchain-node install master all dogecoin testnet

# Or for a local regtest environment (recommended for first-time setup)
xchain-node install master all bitcoin regtest

The installer:

Verifies Docker is accessible and creates runtime directories
Installs xchain-hub first (the shared coordination layer)
Clones each service repo from GitHub into modules/
Builds Docker images and starts containers
Downloads and verifies the crypto node binary (Bitcoin/Litecoin/Dogecoin daemon) using SHA-256 hashes
Configures inter-service networking on isolated Docker networks

Installation time varies: regtest finishes in minutes; mainnet requires downloading blockchain data, which can take hours or days depending on your connection and hardware.

Step 3: Start the Services

# Start all services for Bitcoin mainnet
xchain-node start all bitcoin mainnet

# Start a specific service
xchain-node start xchain-explorer

# Start all chains and networks at once
xchain-node start all all all

Step 4: Check Status

# List all running containers
xchain-node ps

# Interactive terminal UI — shows all services with live status
xchain-node -i

The interactive TUI (-i flag) gives you a multi-pane view of all installed containers, their status, and log tails. Use it to quickly see which services are running and spot any that have crashed.

Step 5: Access the Explorer

Once services are running, the XChain explorer web UI is available at:

http://localhost:18080

The JSON-RPC API is at:

http://localhost:18080/api

The REST API is at:

http://localhost:18080/rest

Multi-Chain Setup

A single xchain-node installation can run Bitcoin, Litecoin, and Dogecoin simultaneously. The xchain-hub and xchain-explorer are shared services — one instance serves all chains. Each coin gets its own set of coin-specific services (decoder, indexer, encoder, UTXO tracker).

# Add Litecoin mainnet to an existing installation
xchain-node install master all litecoin mainnet
xchain-node start all litecoin mainnet

# Add Dogecoin mainnet
xchain-node install master all dogecoin mainnet
xchain-node start all dogecoin mainnet

Regtest Mode (Recommended for Development)

Regtest is a local blockchain mode where:

Blocks are mined on demand (no waiting for confirmations)
Coins have no real value
You can reset the chain at any time
The xchain-regtest-miner service automatically mines blocks as transactions arrive

# Install regtest stack
xchain-node install master all bitcoin regtest
xchain-node start all bitcoin regtest

In regtest, the xchain-e2e-test service runs the full end-to-end test suite against your local stack — useful for verifying everything is working correctly.

Common Management Commands

# Stop services
xchain-node stop all bitcoin mainnet

# Restart a specific service
xchain-node restart xchain-indexer bitcoin mainnet

# View logs
xchain-node logs xchain-decoder bitcoin mainnet

# Tail logs live
xchain-node tail xchain-indexer bitcoin mainnet

# Multi-pane log monitor
xchain-node monitor all bitcoin mainnet

# Open a shell inside a container
xchain-node shell xchain-indexer bitcoin mainnet

# Update a service to latest
xchain-node update xchain-indexer bitcoin mainnet

Bootstrap Snapshots

For mainnet deployments, downloading and parsing the full blockchain from genesis can take a very long time. The installer supports bootstrap snapshots — pre-built database dumps that let you start from a recent block:

# Restore from bootstrap snapshot (faster initial sync)
xchain-node bootstrap restore xchain-indexer bitcoin mainnet

To skip bootstrap and force a full parse from genesis:

xchain-node install master all bitcoin mainnet --no-bootstrap

Next Steps

Deployment Guide — production configuration, security, reverse proxies
Docker Reference — container naming, networking, volume management
Regtest Development — full local development setup
Configuration Reference — all environment variables and config parameters

Based on XChain Platform by Dankest, LLC – https://dankest.llc

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later) with a commercial license available for proprietary use.

You may use, modify, and distribute this material under the terms of the License. See LICENSE and NOTICE for full terms. See the licensing overview.