Humanode Docker Image

Single-container Docker image running a Humanode mainnet node.

Run a node

git clone https://github.com/piconbello/Humanode-Docker.git
cd Humanode-Docker
docker compose up -d

Your node is now syncing. Check the logs:

docker compose logs -f humanode

Run a validator

You need your session-key seed mnemonic (not your stash/controller seed — session keys only).

1. Enable validator mode and start the node.

   cp .env.example .env
   sed -i 's/^#VALIDATOR=true/VALIDATOR=true/' .env
   docker compose up -d

2. Insert your session key into the running node.

   read -rsp 'Seed: ' SEED; echo
   printf '%s' "$SEED" | docker compose exec -T humanode /usr/local/bin/insert-key.sh
   unset SEED

   At the Seed: prompt, paste your 12/24-word mnemonic. It won't echo. On success you'll see insert-key: keystore populated for key-type kbai.

   The seed never enters shell history, process argv, or the runtime container.

3. Complete bioauth. The tunnel prints the bioauth link to the logs:

   docker compose logs humanode 2>&1 | grep 'bioauth link:'

   Open that URL in a browser, scan your face, done.

   By default the built-in Humanode WebSocket Tunnel is used (no account needed). If you prefer ngrok, set NGROK_AUTHTOKEN in .env.

Finding your node name

The container auto-generates a name like HND-cedar-a1f3b2 on first boot and persists it across restarts. To find it:

docker compose logs humanode 2>&1 | grep 'node-name:'

If you set NODE_NAME=mynode in .env, the name becomes HND-mynode.

You can look up your node on the Humanode Telemetry dashboard by searching for this name.

Environment variables

Variable	Default	Description
SYNC_MODE	full	Sync strategy: full, warp, fast, fast-unsafe.
NODE_NAME	auto-generated	Suffix for the display name. Always prefixed with HND-.
VALIDATOR	false	Set to true to enable validator mode and bioauth tunnel.
NGROK_AUTHTOKEN	(empty)	ngrok auth token. When set, uses ngrok instead of the default Humanode tunnel. Only applies when VALIDATOR=true.
DB_CACHE	256	Database cache size in MiB. Limits RocksDB memory usage.
STATE_PRUNING	(binary default: 256)	State pruning mode: archive, archive-canonical, or a number of blocks to keep. Can only be set on first run.
BLOCKS_PRUNING	(binary default: archive-canonical)	Block pruning mode: archive, archive-canonical, or a number of blocks to keep.