> For the complete documentation index, see [llms.txt](https://skyneticlabs.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://skyneticlabs.gitbook.io/docs/security/tools/horcrux-distributed-signer-setup.md).

# Horcrux Distributed Signer Setup

### Overview

Horcrux is a distributed signing system designed for Cosmos-based validators.\
It allows a validator’s private key to be split into multiple encrypted parts and stored across independent servers.\
A threshold number of co-signers must participate to produce a valid signature, improving both resilience and security.

***

### System Requirements

#### Validator Node

| Component  | Requirement                                   |
| ---------- | --------------------------------------------- |
| CPU        | 4 cores                                       |
| RAM        | 16 GB                                         |
| Disk       | 250 GB SSD                                    |
| Network    | Reliable high-bandwidth connection            |
| Open Ports | 26656 (P2P), 1234 (private signer connection) |

#### Co-signer Nodes

| Component  | Requirement              |
| ---------- | ------------------------ |
| CPU        | 4 cores                  |
| RAM        | 4 GB                     |
| Disk       | 80 GB SSD                |
| Network    | 1 Gbps                   |
| Open Ports | 2222 (Horcrux), 22 (SSH) |

***

### Base Environment Setup

Update the system and install required dependencies:

```bash
sudo apt update -q
sudo apt upgrade -qy
sudo apt install -qy git curl jq lz4 build-essential
```

Enable NTP to synchronize system clocks:

```bash
sudo apt install ntp -y
sudo systemctl enable --now ntp
```

***

### Install Go

```bash
curl -L https://go.dev/dl/go1.24.6.linux-amd64.tar.gz | sudo tar -C /usr/local -xzf -
echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' | tee -a ~/.bashrc
source ~/.bashrc
go version
```

***

### Install Horcrux

Run these commands on each co-signer node:

```bash
git clone https://github.com/strangelove-ventures/horcrux.git
cd horcrux
make install
```

Verify installation:

```bash
horcrux version
```

***

### Initialize Configuration

On one co-signer node, create the shared configuration file:

```bash
horcrux config init \
  --node "tcp://10.0.0.10:1234" \
  --cosigner "tcp://10.0.0.11:2222" \
  --cosigner "tcp://10.0.0.12:2222" \
  --cosigner "tcp://10.0.0.13:2222" \
  --threshold 2
```

**Parameters:**

* `--node`: validator’s private signing address
* `--cosigner`: each co-signer’s IP and port
* `--threshold`: number of required signers to approve a signature

Copy the generated `config.yaml` file to each co-signer, adjusting IPs as needed.

***

### Generate ECIES Keys

Generate encryption keys for secure communication between co-signers:

```bash
horcrux create-ecies-shards --shards 3
```

This creates directories containing key files:

```
cosigner_1/ecies_keys.json
cosigner_2/ecies_keys.json
cosigner_3/ecies_keys.json
```

Each file must be transferred to its corresponding co-signer node.

***

### Split the Validator Private Key

Copy the validator’s `priv_validator_key.json` into the working directory and run:

```bash
horcrux create-ed25519-shards \
  --chain-id mychain-1 \
  --key-file ./priv_validator_key.json \
  --threshold 2 \
  --shards 3
```

Output example:

```
cosigner_1/mychain-1_shard.json
cosigner_2/mychain-1_shard.json
cosigner_3/mychain-1_shard.json
```

After splitting, delete the original `priv_validator_key.json` or store it offline in secure storage.

***

### Create Systemd Service

Create the service unit file:

```bash
sudo tee /etc/systemd/system/horcrux.service <<EOF
[Unit]
Description=Horcrux Co-signer Service
After=network-online.target

[Service]
User=$USER
ExecStart=$(which horcrux) start
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF
```

Reload and start the service:

```bash
sudo systemctl daemon-reload
sudo systemctl enable horcrux
sudo systemctl start horcrux
```

***

### Synchronize Consensus State

Before starting Horcrux, synchronize the validator state across all co-signers.

On the validator node:

```bash
sudo systemctl stop <validator_service>
cat ~/.<chain_home>/data/priv_validator_state.json
```

Example output:

```json
{
  "height": "543210",
  "round": 0,
  "step": 3
}
```

Create a simplified version containing these fields and copy it to each co-signer:

```
~/.horcrux/state/mychain-1_priv_validator_state.json
```

***

### Configure the Validator

In the validator’s `config.toml`, set the remote signing address:

```toml
priv_validator_laddr = "tcp://0.0.0.0:1234"
```

Restart the validator:

```bash
sudo systemctl restart <validator_service>
```

View Horcrux logs:

```bash
sudo journalctl -u horcrux -f
```

***

### Verification

* Ensure the validator successfully connects to Horcrux.
* Check that signing requests appear in Horcrux logs.
* Confirm that blocks are being signed and included on-chain.

***

### Security Best Practices

* Limit SSH access to trusted keys and IP addresses.
* Use firewall rules to restrict traffic between validator and co-signers only.
* Keep Horcrux and the OS updated.
* Store all configuration backups and key shares in encrypted offline storage.
* Never place multiple key shares on the same machine.