Skip to main content

Run a Trinity Node in 5 Minutes

info

Example outputs in this guide show representative values. Actual values will vary based on your hardware, network conditions, and workload.

This guide gets you from zero to earning $TRI as fast as possible.

Prerequisites​

You need one of the following:

MethodRequirement
Docker (recommended)Docker 20.10+
Build from sourceZig 0.15.x

Minimum hardware:

  • 2 CPU cores
  • 4 GB RAM
  • 20 GB free disk space
  • Stable internet connection

1. Pull the Image​

docker pull ghcr.io/ghashtag/trinity-node:latest

2. Run​

docker run -d --name trinity-node \
  -p 8080:8080 -p 9090:9090 -p 9333:9333/udp -p 9334:9334 \
  -v ~/.trinity:/data \
  ghcr.io/ghashtag/trinity-node:latest

Port breakdown:

PortProtocolPurpose
8080TCPHTTP API (REST endpoints)
9090TCPPrometheus metrics
9333UDPPeer discovery
9334TCPJob distribution

The -v ~/.trinity:/data flag persists your node data (wallet, shards, logs) across container restarts.

3. Check Logs​

docker logs -f trinity-node

You should see:

[TRINITY] Node starting...
[TRINITY] Wallet: 0x1a2b3c4d...
[TRINITY] Discovering peers on UDP 9333...
[TRINITY] Found 3 peers
[TRINITY] Status: ONLINE
[TRINITY] HTTP API listening on :8080
[TRINITY] Prometheus metrics on :9090
[TRINITY] Ready to earn $TRI

4. Stop / Restart​

docker stop trinity-node    # Stop
docker start trinity-node   # Restart (keeps data)
docker rm trinity-node      # Remove (data persists in ~/.trinity)

Option B: Build from Source​

1. Clone the Repository​

git clone https://github.com/gHashTag/trinity.git
cd trinity

2. Build the Node​

zig build              # Build all targets
zig build tri          # Build the unified Trinity CLI

3. Start the Node​

# Using the unified TRI CLI (recommended)
zig build tri

# Or run the built binary directly
./zig-out/bin/tri node start --port 8080 --data-dir ~/.trinity

4. Build for Production​

For production deployments, use the release build for maximum performance:

zig build release      # Cross-platform release builds

This produces optimized binaries for:

  • Linux x86_64
  • macOS x86_64
  • macOS ARM64 (Apple Silicon)
  • Windows x86_64

Verify Your Node​

Check Health​

curl http://localhost:8080/health

Expected response:

{
  "status": "ok",
  "model": "loaded"
}

Check Server Info​

curl http://localhost:8080/

Expected response:

{
  "name": "TRINITY LLM",
  "version": "1.4.0",
  "endpoints": ["/v1/chat/completions", "/health", "/metrics"],
  "metrics": {
    "total_requests": 0,
    "active_requests": 0,
    "total_tokens": 0,
    "throughput_tok_s": 0.00
  }
}

Check Prometheus Metrics​

curl http://localhost:9090/metrics

Check Your Earnings​

View Wallet Balance​

curl http://localhost:8080/v1/node/stats

Example response:

{
  "status": "earning",
  "operations": 1247,
  "earned_tri": 3.892,
  "pending_tri": 0.045,
  "uptime_hours": 72.5,
  "wallet": "0x1a2b3c4d5e6f..."
}

Claim Pending Rewards​

curl -X POST http://localhost:8080/v1/node/claim

What Happens Next​

Once your node is online, it automatically:

  1. Discovers peers via UDP broadcast on port 9333
  2. Accepts jobs from the job dispatcher on port 9334
  3. Performs useful work -- VSA operations, storage hosting, benchmarks
  4. Earns $TRI for every completed operation
  5. Reports metrics to Prometheus on port 9090

Your node will transition through these states:

OFFLINE -> SYNCING -> ONLINE -> EARNING

The EARNING state means your node has successfully completed at least one paid operation.

Troubleshooting​

Node stays in SYNCING state​

Ensure UDP port 9333 is open in your firewall:

# Linux
sudo ufw allow 9333/udp

# macOS (no firewall by default)
# Check System Preferences > Security & Privacy > Firewall

Cannot reach the API​

Verify the container is running and ports are mapped:

docker ps --filter name=trinity-node

Low earnings​

Ensure your node has:

  • Sufficient bandwidth for storage operations
  • Enough RAM for VSA operations (4 GB minimum)
  • A stable connection (intermittent disconnects lose job assignments)

See Reward Rates for strategies to maximize earnings.

Next Steps​