Truebit Node Installation Guide

This guide will walk you through the process of setting up a Truebit Decentralized Verification Node, enabling your system to participate in verifying Truebit tasks on the network.

System Requirements for a Truebit Node

Truebit Node is designed to run on cloud infrastructure (such as AWS or Google Cloud) or can alternatively be installed locally on your computer.

For optimal uptime and reliability, cloud deployment is strongly recommended. This approach ensures your verification node remains online 24/7 without the stability risks of running it on a personal machine. For cost-effective deployment, a cloud provider's free tier is an acceptable option.

Creating a FREE Tier Cloud instance

If you're new to cloud deployment, these official guides will help you create a compatible VM:

• AWS: Launch an EC2 t3.small instance

• Google Cloud: Create an e2-micro VM

Note: Select Ubuntu 22.04 LTS or later as your OS, then install Docker using the official installation guide.

Prerequisites

• Wallet Address — Ethereum-Compatible (EVM)

Create a new wallet address — don’t use an existing one. You’ll need to share its private key with the node, so it must be used only for this server.

Why: this keeps your personal funds safe and ensures you stay in control if the server is lost or replaced.

Steps:

1. Create a new wallet with MetaMask or MyCrypto.

2. Export and securely store the private key.

3. Use this wallet only for running the node.

• AVAX balance: The node operator pays for the Avalanche Gas used in registration and de-registration transactions.

• $TRU stake: Running a Truebit node requires 2,000 TRU tokens to be staked. This stake is essential for the slashing and reward mechanism that ensures honest participation and secure verification.

We run a limited-capacity Stake Sponsorship Program to support selected node operators. If you’d like to be considered for an invitation, please submit your request via http://forms.truebit.io/

Setup The Truebit Node

Create Docker-compose.yml File

Create a new file named docker-compose.yml and paste the configuration below.

You can use any plain-text editor — for example: nano docker-compose.yml or vim docker-compose.yml

name: truebit_runner_node
services:
  runner-node:
    image: truebitprotocol/runner-node:prod
    platform: linux/amd64
    container_name: runner-node
    pull_policy: always
    stop_signal: SIGINT
    stop_grace_period: 30s
    environment:
      - RABBITMQ_URL=amqps://runneruser:[e-mail]:30010/truebit-nextgen
      - FILESYSTEM_URL=https://prod-minio.truebit.network
      - FILESYSTEM_ACCESS_KEY=eHSCx431M1khHMc
      - FILESYSTEM_SECRET_KEY=6DnIQrM2wIyY09rT
      - PRIVATE_KEY= (to be added by the user)

Replace the PRIVATE_KEY field with your own private key that has already been staked with $TRU.

If your private key starts with 0x, remove the 0x prefix before pasting it.

Start Truebit Node

docker compose -f docker-compose.yml up -d 

Node status

Use these checks right after you start the node.

Check the container is running

docker compose -f docker-compose.yml ps

You should see runner-node in a running state.

Watch the node logs

docker logs runner-node -f

Use this to confirm the node connects to the network and stays online.

Confirm the node is registered on-chain

On startup and shutdown, the node registers and de-registers via the Node Registry smart contract.

For a quick UI check (registration + recent slashing history), use: Node Status.

The node address is the EVM address derived from the PRIVATE_KEY you configured.

If you need to stop your Truebit Verification Node, run the following command:

docker compose -f docker-compose.yml down -v

If you want, you can check the logging command by executing this:

docker logs <CONTAINER_NAME> 

docker logs <CONTAINER_NAME> -f

IMPORTANT! For reliable node operation, you must use docker compose down when performing a shutdown. Any other shutdown method may cause registration inconsistencies. If the Node fails to properly de-register, and the Hub subsequently assigns it a task, the Node will be forcibly de-registered after failing to respond.