Installing the Client

The Citrate node client, citrated, is the core software for participating in the network as a validator, miner, model host, or oracle. This guide covers three installation methods -- pre-built binaries, building from source, and Docker -- followed by a detailed walkthrough of the configuration file. We recommend starting with pre-built binaries unless you need to customize the client at the source level.

Pre-Built Binaries

The simplest installation method is downloading a pre-built binary for your platform. Releases are published to the Cnidarian releases page and include binaries for Linux (x86_64, ARM64) and macOS (ARM64).

Download the latest release:

curl -L https://releases.cnidarian.cloud/citrated/latest/citrated-linux-amd64.tar.gz -o citrated.tar.gz

Extract the binary and move it into your path:

tar -xzf citrated.tar.gz

sudo mv citrated /usr/local/bin/

sudo chmod +x /usr/local/bin/citrated

Verify the installation:

citrated --version

For macOS:

Download the macOS binary:

curl -L https://releases.cnidarian.cloud/citrated/latest/citrated-darwin-arm64.tar.gz -o citrated.tar.gz

Extract and install:

tar -xzf citrated.tar.gz

sudo mv citrated /usr/local/bin/

Verify:

citrated --version

Building from Source

Building from source gives you access to the latest development features and the ability to customize the client. You need Go 1.22+ and a C compiler (for CGO dependencies).

Clone the repository:

git clone https://github.com/cnidarian/citrated.git

cd citrated

Install dependencies:

go mod download

Build the client:

make build

Move the binary into your path and verify:

sudo mv build/citrated /usr/local/bin/

citrated --version

To build with GPU support for model hosting:

Ensure CUDA toolkit is installed (11.8+):

nvcc --version

Build with CUDA support:

make build-gpu

Move the GPU-enabled binary into your path:

sudo mv build/citrated /usr/local/bin/

Docker Installation

Docker provides the most isolated and reproducible setup. The official Citrate Docker image includes all dependencies and is recommended for production deployments. I'd say Docker is the best option if you want to get running quickly without worrying about dependency management.

Pull the latest image:

docker pull ghcr.io/cnidarian/citrated:latest

Run the node:

docker run -d --name citrate-node -v $HOME/.citrate:/root/.citrate -p 30303:30303 -p 30303:30303/udp -p 8545:8545 ghcr.io/cnidarian/citrated:latest --config /root/.citrate/config.toml

Check the logs to confirm it started:

docker logs -f citrate-node

For model hosting with GPU access, use the NVIDIA runtime:

docker run -d --name citrate-model-host --gpus all -v $HOME/.citrate:/root/.citrate -v /models:/models -p 30303:30303 -p 8545:8545 -p 8546:8546 ghcr.io/cnidarian/citrated:latest-gpu --config /root/.citrate/config.toml

Docker Compose for a multi-service setup:

version: "3.8"
services:
  citrated:
    image: ghcr.io/cnidarian/citrated:latest
    volumes:
      - ./data:/root/.citrate
    ports:
      - "30303:30303"
      - "30303:30303/udp"
      - "8545:8545"
    command: --config /root/.citrate/config.toml
    restart: unless-stopped
 
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"
 
  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=changeme

Configuration File Walkthrough

When you first run citrated init, it generates a configuration file at ~/.citrate/config.toml. Here is a complete annotated configuration:

# Node identity and basic settings
[node]
name = "my-citrate-node"
data_dir = "~/.citrate/data"
log_level = "info"                  # debug, info, warn, error
log_format = "json"                 # json or text
 
# Network configuration
[network]
chain_id = 1337                      # 1337 = mainnet, 1338 = testnet
listen_addr = "0.0.0.0:30303"
max_peers = 50
bootnodes = [
  "enode://abc123...@bootnode1.cnidarian.cloud:30303",
  "enode://def456...@bootnode2.cnidarian.cloud:30303",
]
 
# JSON-RPC API settings
[rpc]
enabled = true
http_addr = "127.0.0.1"
http_port = 8545
ws_addr = "127.0.0.1"
ws_port = 8546
cors_origins = ["*"]
api_modules = ["eth", "net", "web3", "citrate"]
 
# Consensus settings
[consensus]
role = "validator"                   # validator, miner, or full
validator_key = "~/.citrate/keys/validator.key"
stake_address = "0xYOUR_STAKING_ADDRESS"
 
# GhostDAG mining (only if role includes mining)
[mining]
enabled = false
threads = 0                          # 0 = use all available cores
coinbase = "0xYOUR_COINBASE_ADDRESS"
 
# Model hosting (only for model host nodes)
[model_hosting]
enabled = false
gpu_devices = ["cuda:0"]
model_dir = "/models"
max_concurrent_inferences = 16
 
# Metrics and monitoring
[metrics]
enabled = true
prometheus_addr = "0.0.0.0:9100"

After configuring, initialize the data directory and start the node:

Initialize the data directory and genesis state:

citrated init --config ~/.citrate/config.toml

Start the node:

citrated start --config ~/.citrate/config.toml

Installing the Client

Pre-Built Binaries

Building from Source

Docker Installation

Configuration File Walkthrough

Further Reading

On this page