Run your own Humanode
The following documentation will help you run your own Humanode peer and join the Humanode testnet.

Downloading and extracting the project

After your system is fully prepared, you are ready to download, configure and run the Humanode peer to participate in the consensus, produce blocks and interact with the Humanode testnet.
Download and unzip the archive you've received from our team by email. Open the terminal and navigate to the unzipped folder. Let's call a new opened terminal - PEER-TERMINAL.
For starters, use the ls command to check if you're in the right directory. You should have the following:
$ ls
binaries chainspec.json
$ ls binaries/
Darwin-arm64 Darwin-x86_64 Linux-x86_64Figure out which binary to use. We provide binaries for various Operating Systems and CPU architectures, and you can use the following command to find a binary that corresponds to your platform: echo "$(uname -s)-$(uname -m)".
Extracting .zip and opening the terminal
Install the humanode-peer binary for your platform with the following command:
sudo install -m 0755 "./binaries/$(uname -s)-$(uname -m)/humanode-peer" /usr/local/bin
This command will ask you for the sudo password, and then install the humanode-peer command to the /usr/local/bin directory. If you are running as root you don't need to use sudo and can just run install command.
The install command does not produce output, but it will do the job.

Configuring your peer

Please proceed with the following steps to properly configure your Humanode peer.

Network settings

Before running the peer, make sure that you've followed the recommendations from the prepare your system page.

Keys management

Your biometric identity will be linked to your validator keypair, so you need to obtain and manage the keypair properly and keep it secret.
First, we need to generate a new keypair. It can be easily done by executing the following command:
humanode-peer key generate
The output should be like this:
Secret phrase `behind cube stock matrix proof warfare retreat front eagle enemy genre later` is account:
Secret seed: 0x4a6324d09ce30d3da1f1039f76924f9374b3b0c6d15c3f2912f02bbca4482b00
Public key (hex): 0x466b7f2b777f2f3a5b30fd3a390d1652a689b5090ea2ad0d35e869d5f442c63c
Public key (SS58): 5Df39CwSkwPg6TbKXTVBjfQE7mbxXDdpM4qg6ZjbHP84wnGg
Account ID: 0x466b7f2b777f2f3a5b30fd3a390d1652a689b5090ea2ad0d35e869d5f442c63c
SS58 Address: 5Df39CwSkwPg6TbKXTVBjfQE7mbxXDdpM4qg6ZjbHP84wnGg
As you can see, a secret phrase, a secret seed, a public key in hex and _[_SS58]( format, an account ID in hex and in SS58 format have been generated. They all correspond to the same keypair, and all of the values can be derived from the secret phrase or secret seed (or the private key itself). The secret seed is your private key in hex encoding, and the secret phrase is your private key in the mnemonic form. Also, there are public keys, account IDs in hex and SS58 formats.
Key generation
Once your key is generated you need to import the newly generated key to the Humanode peer's key store. Copy the secret phrase and use it in the following command:
humanode-peer key insert --key-type aura --suri "$SECRET_PHRASE" --chain chainspec.json
  • --key-type aura - key type that is used in Humanode testnet.
  • --suri "$SECRET_PHRASE" - your secret phrase (i.e. mnemonic) from the previous command.
  • --chain chainspec.json - path to the Humanode testnet chain specification file.
For our case, it should be:
humanode-peer key insert --key-type aura --suri "behind cube stock matrix proof warfare retreat front eagle enemy genre later" --chain chainspec.json
Make sure that you have inserted only 1 key. In case you inserted more than 1 key you will have a panic during running a node (Remember: 1 Human = 1 Node = 1 Key). To fix it follow this instruction.
Keep in mind that your bioauthentication is tied to your validator keypair, so if you lose this mnemonic you won't be able to use the system anymore. After you enroll with the bioauth subsystem, you will have to use the same mnemonic for all subsequent runs. Save your mnemonic at a secure location, and keep it private.
Key insertion

Configuring ngrok

In this section, we'll configure ngrok to allow connections to the peer's TCP port 9933 from the public internet over HTTPS, with a proper certificate and public domain name. This is required to make your handheld device connect to the peer's RPC endpoint to conduct the biometric information exchange. If you know what you're doing, you can skip this step and use your own RPC URL later.
You should have installed ngrok while preparing your system, if you didn't follow these instructions. Now we need to open a new one terminal and navigate to the directory where ngrok is installed for configuring and running ngrok. Let's call it NGROK-TERMINAL.
To start the tunnel, use the following command:
./ngrok http --bind-tls true 9933
The output should be like this:
Session Status online
Account Your account name (Plan: Free)
Version 2.3.40
Region United States (us)
Web Interface
Forwarding -> http://localhost:9933
Connections ttl opn rt1 rt5 p50 p90
3 0 0.00 0.00 41.19 375.05
From the output above you'll need to note the URL. In this case it is, but it is unique on every run, and you'll get a different one.
You don't need to visit that URL!
After launching ngrok it’s ok to see 502 bad gateway error and it will disappear after biometric authentication.
After that you need to keep ngrok process working. To do it don't press Ctrl+C and don't close NGROK-TERMINAL.
ngrok configuration

Running the peer

Before starting the Humanode peer perform the last checks that your environment is ready.
Make sure:
  • All the requirements for your operating system are fulfilled.
  • The system has the correct date and time.
  • You are using ngrok, or expose port 9933 in such a way that it's accessible from the web app running on your handheld device.
  • The peer's configuration is done.
  • Your validator secret phrase is saved in a secure way.

Registration (enrollment)

Once the configuration is complete, you can run the peer. Let' return to our PEER-TERMINAL.
There are 2 options to execute the enrollment command:
  • Using --rpc-url-ngrok-detect subcommand to automatically detect RPC URL from ngrok that you have already launched before.
    humanode-peer --name "$NAME" --validator --chain chainspec.json --rpc-url-ngrok-detect --rpc-cors all --bioauth-enroll
  • You can manually specify RPC URL from ngrok output console.
    humanode-peer --name "$NAME" --validator --chain chainspec.json --rpc-url "$RPC_URL" --rpc-cors all --bioauth-enroll
  • --name "$NAME" - where $NAME is your Humanode peer name.
  • --validator - means that you join the network as a block producer.
  • --chain chainspec.json - a path to the file that contains Humanode testnet chain specification.
  • --rpc-url "$RPC_URL" - the peer's RPC URL, where $RPC_URL is the URL that you noted at the ngrok configuration step, or your own URL if you're not using ngrok.
  • --rpc-url-ngrok-detect - to detect peer's RPC URL automatically from ngrok (mutually exclusive with --rpc-url).
But we strongly recommend to use --rpc-url-ngrok-detect subcommand to avoid facing unexpected issues.
In our case, the final command should look like this:
humanode-peer --name "ikarisinji" --validator --chain chainspec.json --rpc-url-ngrok-detect --rpc-cors all --bioauth-enroll
After you run it, the console output should be like this:
2021-08-21 18:24:33 Humanode Node
2021-08-21 18:24:33 ✌️ version 0
2021-08-21 18:24:33 ❤️ by Humanode Team <[email protected]>, 2021-2021
2021-08-21 18:24:33 📋 Chain specification: Humanode Testnet 1
2021-08-21 18:24:33 🏷 Node name: ikarisinji
2021-08-21 18:24:33 👤 Role: AUTHORITY
2021-08-21 18:24:33 💾 Database: RocksDb at /data/humanode-peer/chains/huamnode_testnet1/db
2021-08-21 18:24:33 ⛓ Native runtime: humanode-100 (humanode-1.tx1.au1)
2021-08-21 18:24:33 Using default protocol ID "sup" because none is configured in the chain specs
2021-08-21 18:24:33 🏷 Local node identity is: 12D3KooWS4HqyQSYcSojQhuBKVoUvhqnZf3RB6MwMvL9iNgNbjWA
2021-08-21 18:24:33 📦 Highest known block at #123
2021-08-21 18:24:33 〽️ Prometheus exporter started at
2021-08-21 18:24:33 Listening for new connections on
2021-08-21 18:24:33 Bioauth flow starting up
Running the humanode-peer
The output contains the QR code. Use it to open Humanode web app and scan your face to bind your biometric data to the node.
The node will enroll you into the system, and then it will print a QR code again - this time to perform authentication.


Open the QR code and scan your face again.
The node will authenticate itself with the blockchain and will be ready to produce and validate blocks.
Now your console output should look like this:
2021-08-21 18:25:01 Bioauth flow - authentication complete
2021-08-21 18:25:01 We've obtained an auth ticket auth_ticket=[128, ..., 0]
2021-08-21 18:25:02 💤 Idle (3 peers), best: #10 (0x4f96…fdec), finalized #0 (0x8f13…e745), ⬇ 0.7kiB/s ⬆ 0.3kiB/s
2021-08-21 18:25:06 ✨ Imported #11 (0x5594…e8a0)
2021-08-21 18:25:07 💤 Idle (3 peers), best: #11 (0x5594…e8a0), finalized #0 (0x8f13…e745), ⬇ 0.4kiB/s ⬆ 0.2kiB/s
2021-08-21 18:25:12 💤 Idle (3 peers), best: #11 (0x5594…e8a0), finalized #0 (0x8f13…e745), ⬇ 0 ⬆ 0
2021-08-21 18:25:12 ✨ Imported #12 (0x5ed2…da60)
2021-08-21 18:25:17 💤 Idle (3 peers), best: #12 (0x5ed2…da60), finalized #0 (0x8f13…e745), ⬇ 0.4kiB/s ⬆ 0.2kiB/s
2021-08-21 18:25:18 🙌 Starting consensus session on top of parent 0x5ed206762d36e0a47bffa4294d47bd9f4d85d959ced8d385017983ab8a8fda60
2021-08-21 18:25:18 🎁 Prepared block for proposing at 13 [hash: 0xa5396adaad72e875a61d71efe64984684e81b14e17a8f2892a1b6240b35c8600; parent_hash: 0x5ed2…da60; extrinsics (1): [0x4240…c102]]
2021-08-21 18:25:18 🔖 Pre-sealed block for proposal at 13. Hash now 0xa0ab5f3df7dc82a378b9206712b01f0c04ef1d08076626457aedb4c24479911a, previously 0xa5396adaad72e875a61d71efe64984684e81b14e17a8f2892a1b6240b35c8600.
2021-08-21 18:25:18 ✨ Imported #13 (0xa0ab…911a)
2021-08-21 18:25:22 💤 Idle (3 peers), best: #13 (0xa0ab…911a), finalized #0 (0x8f13…e745), ⬇ 0.1kiB/s ⬆ 0.4kiB/s
2021-08-21 18:25:24 ✨ Imported #14 (0xd65c…c7f1)
Congratulations, your Humanode peer has joined the Humanode testnet and produces blocks! You are one of the first human nodes in the Galaxy!

Authentication ticket expiration and getting a new one

To prevent extra malicious activity Humanode uses a concept of authentication tickets to allow the peers to participate in consensus for blocks production.
Unlike mainnet where human nodes will have to go through the bioauthentication every month, during the first testnet each authentication ticket is valid only for 72 hours after passing bioauthentication procedure. Therefore, to continue taking part in consensus you need to get a new one authentication ticket by passing bioauthentication procedure again.
The following console output indicates that your authentication ticket has been expired.
2021-08-24 17:26:48 💤 Idle (3 peers), best: #11322 (0x0787…f440), finalized #0 (0x8f13…e745), ⬇ 0.3kiB/s ⬆ 0.2kiB/s
2021-08-24 17:26:53 💤 Idle (3 peers), best: #11322 (0x0787…f440), finalized #0 (0x8f13…e745), ⬇ 0 ⬆ 0
2021-08-24 17:26:54 ✨ Imported #11323 (0x2591…a139)
2021-08-24 17:26:58 💤 Idle (3 peers), best: #11323 (0x2591…a139), finalized #0 (0x8f13…e745), ⬇ 0.4kiB/s ⬆ 0.2kiB/s
2021-08-24 17:27:00 ✨ Imported #11324 (0x21f4…6314)
2021-08-24 17:27:03 💤 Idle (3 peers), best: #11324 (0x21f4…6314), finalized #0 (0x8f13…e745), ⬇ 0.3kiB/s ⬆ 0.2kiB/s
2021-08-24 17:27:06 ✨ Imported #11325 (0x699b…82f2)
2021-08-24 17:27:08 💤 Idle (3 peers), best: #11325 (0x699b…82f2), finalized #0 (0x8f13…e745), ⬇ 0.3kiB/s ⬆ 0.4kiB/s
2021-08-24 17:27:12 ✨ Imported #11326 (0x9e13…1d61)
2021-08-24 17:27:13 💤 Idle (3 peers), best: #11326 (0x9e13…1d61), finalized #0 (0x8f13…e745), ⬇ 0.4kiB/s ⬆ 0.4kiB/s
2021-08-24 17:27:18 ✨ Imported #11327 (0xe92e…3eca)
Note there are no rows with Starting consensus session on top of parent....
To get a new authentication ticket you have to stop the peer by pressing Ctrl+C in the terminal window, and run it again with the following command:
humanode-peer --name "$NAME" --validator --chain chainspec.json --rpc-url-ngrok-detect --rpc-cors all
This is the same command we used before, except it doesn't include the --bioauth-enroll flag.
You will see the QR code again that can be used in the same way as before.
As a result, your Humanode peer will start producing blocks again.
Copy link
On this page
Downloading and extracting the project
Configuring your peer
Network settings
Keys management
Configuring ngrok
Running the peer
Registration (enrollment)
Authentication ticket expiration and getting a new one