Hydra
Docs

Step-by-step guide to installing, registering, and running a Hydra Node.

Setup Guide

This guide walks you through the complete process of setting up a Hydra Node — from installation to verifying it's running on the network.

Step 1: Install the Binary

Choose one of the following installation methods:

Download the latest release for your platform from GitHub Releases:

# Linux (amd64)
curl -L -o hydra-node https://github.com/hydra-network/hydra-node/releases/latest/download/hydra-node-linux-amd64
chmod +x hydra-node
sudo mv hydra-node /usr/local/bin/

# macOS (Apple Silicon)
curl -L -o hydra-node https://github.com/hydra-network/hydra-node/releases/latest/download/hydra-node-darwin-arm64
chmod +x hydra-node
sudo mv hydra-node /usr/local/bin/

# Windows (amd64)
# Download hydra-node-windows-amd64.exe from the releases page

npm

npm install -g @hydra/node

Docker

docker pull ghcr.io/hydra-network/hydra-node:latest

Build from Source

git clone https://github.com/hydra-network/hydra-node.git
cd hydra-node
make build
# Binary at ./bin/hydra-node

Verify the installation:

hydra-node status

Step 2: Create Your Config File

Create the Hydra config directory and a minimal config:

mkdir -p ~/.hydra

Create ~/.hydra/node.yaml with the following content. This example enables only the free sources that need no API keys:

mode: private

server:
  port: 4001
  host: "0.0.0.0"

sources:
  usgs:
    enabled: true
    interval: 5m
  oref:
    enabled: true
  polymarket:
    enabled: true
    marketInterval: 15m
  maritime:
    enabled: true
    interval: 24h

storage:
  dataDir: "~/.hydra/data"
  retentionHours: 24

logging:
  level: "info"

This is enough to start a private node right away. See the Configuration Reference for all options.

Step 3: Test Your Node Locally

Start the node to verify everything works:

hydra-node start

You should see output like:

INFO  hydra-node starting...
INFO  mode=private
INFO  source usgs started (poll every 5m)
INFO  source oref started (stream)
INFO  source polymarket started (poll every 15m)
INFO  source maritime started (poll every 24h)
INFO  server listening on 0.0.0.0:4001
INFO  control plane listening on 127.0.0.1:4002
INFO  metrics server listening on :9090

Verify the node is serving data:

# Health check
curl http://localhost:4001/health

# Node status
curl http://localhost:4001/status

# Recent signals
curl http://localhost:4001/public/signals

# Control plane status
curl http://localhost:4002/control/status

Connect to the live WebSocket stream:

# Using wscat (npm install -g wscat)
wscat -c ws://localhost:4001/stream/live

You should see JSON messages arriving as sources collect data.

Step 4: Register on the Platform (Public Nodes)

Skip this step if you only want a private node.

To submit data to the Hydra network and earn rewards, you need to register your node on the platform.

4a. Open the Create Node Wizard

  1. Go to hydra.fast/platform and log in with your wallet
  2. Select your app (or create one)
  3. Navigate to the Nodes tab
  4. Click Create Node

4b. Choose Deployment Type

Select Self-Hosted if you're running the binary on your own server.

Select Managed by Hydra if you want us to deploy and manage a node for you (zero ops).

4c. Configure Node Details

  • Node Name: A descriptive name like production-eu-west or home-lab
  • Description: Optional notes about the node's purpose
  • Public / Private: Toggle to Public to earn rewards

4d. Select Data Sources

Check the sources you want this node to collect. Sources marked FREE need no API key. Sources marked KEY will prompt you for credentials — these can also be configured later in your node.yaml.

4e. Set Your Endpoint

Enter the public URL where your node's API is accessible from the internet:

  • With a domain: https://node.example.com
  • With an IP: http://203.0.113.5:4001

Make sure port 4001 (or your custom port) is open in your firewall and accessible from the internet. If you're using a reverse proxy (recommended), see Reverse Proxy Setup.

4f. Review and Create

Review your configuration and click Create Node.

4g. Save Your Secret Key

After creation, the platform displays your credentials:

  • Node ID: e.g. node_abc12345
  • Secret Key: e.g. hnd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The secret key is shown once only. Copy it immediately and store it securely. If you lose it, you can regenerate a new one from the Nodes dashboard, but the old key will be invalidated.

Step 5: Configure for Public Mode

Update your ~/.hydra/node.yaml to switch to public mode and add your credentials:

mode: public

node:
  id: "node_abc12345"
  secret: "hnd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

network:
  backendUrl: "https://api.hydra.fast"
  submissionInterval: 60s
  heartbeatInterval: 30s
  batchSize: 100

server:
  port: 4001
  host: "0.0.0.0"

sources:
  usgs:
    enabled: true
    interval: 5m
  adsb:
    enabled: true
    interval: 60s
    apiKeyEnv: "ADSB_API_KEY"
  ais:
    enabled: true
    flushInterval: 60s
    apiKeyEnv: "AISSTREAM_API_KEY"
  cyber:
    enabled: true
    interval: 5m
    apiKeyEnv: "OTX_API_KEY"
  airspace:
    enabled: true
    interval: 10m
    openaipKeyEnv: "OPENAIP_API_KEY"
  oref:
    enabled: true
  telegram:
    enabled: true
    interval: 2m
    channels: ["ukraine_now", "intelslava"]
  polymarket:
    enabled: true
    marketInterval: 15m
  maritime:
    enabled: true
    interval: 24h

storage:
  dataDir: "~/.hydra/data"
  retentionHours: 24

logging:
  level: "info"
  streamToBackend: true

Alternatively, keep the secret out of the YAML and pass it as an environment variable:

export HYDRA_NODE_SECRET="hnd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Set your source API keys as environment variables:

export ADSB_API_KEY="your-rapidapi-key"
export AISSTREAM_API_KEY="your-aisstream-key"
export OTX_API_KEY="your-otx-key"
export OPENAIP_API_KEY="your-openaip-key"

Step 6: Run as a Service

For production, run the node as a background service so it starts automatically on boot.

systemd (Linux)

sudo tee /etc/systemd/system/hydra-node.service > /dev/null << 'EOF'
[Unit]
Description=Hydra Node
After=network.target

[Service]
Type=simple
User=hydra
ExecStart=/usr/local/bin/hydra-node start --config /etc/hydra/node.yaml
Restart=always
RestartSec=5
EnvironmentFile=/etc/hydra/node.env

[Install]
WantedBy=multi-user.target
EOF

Create /etc/hydra/node.env with your secrets:

HYDRA_NODE_SECRET=hnd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ADSB_API_KEY=your-key
AISSTREAM_API_KEY=your-key
OTX_API_KEY=your-key
OPENAIP_API_KEY=your-key

# Secure the env file
sudo chmod 600 /etc/hydra/node.env

# Copy your config
sudo mkdir -p /etc/hydra
sudo cp ~/.hydra/node.yaml /etc/hydra/node.yaml

# Start the service
sudo systemctl daemon-reload
sudo systemctl enable hydra-node
sudo systemctl start hydra-node

# Check status
sudo systemctl status hydra-node

# View logs
journalctl -u hydra-node -f

Docker

docker run -d \
  --name hydra-node \
  --restart unless-stopped \
  -p 4001:4001 \
  -v ~/.hydra/node.yaml:/etc/hydra/node.yaml:ro \
  -v hydra-data:/var/hydra/data \
  --env-file ~/.hydra/node.env \
  ghcr.io/hydra-network/hydra-node:latest \
  start --config /etc/hydra/node.yaml

Docker Compose

version: "3.8"

services:
  hydra-node:
    image: ghcr.io/hydra-network/hydra-node:latest
    ports:
      - "4001:4001"
      - "9090:9090"
    volumes:
      - ./node.yaml:/etc/hydra/node.yaml:ro
      - hydra-data:/var/hydra/data
    env_file:
      - .env
    command: start --config /etc/hydra/node.yaml
    restart: unless-stopped

volumes:
  hydra-data:

Step 7: Verify on the Dashboard

Once your public node is running:

  1. Go to hydra.fast/platform → your app → Nodes
  2. Your node should appear with a green Online status
  3. You can view:
    • Uptime percentage and last heartbeat time
    • Submission count — how many signal batches have been accepted
    • Active sources — which sources are currently collecting
    • Live logs — if logging.streamToBackend is enabled
  4. Use the Test Connection button to verify the platform can reach your node's endpoint

Troubleshooting

Node won't start

# Verify config syntax
hydra-node status --config ~/.hydra/node.yaml

# Run with debug logging (set in node.yaml)
# logging:
#   level: "debug"
hydra-node start

Source not collecting data

# Check API key is set
echo $OTX_API_KEY

# Check source status via control plane
curl http://127.0.0.1:4002/control/status | jq '.sources'

# Restart a specific source
curl -X POST http://127.0.0.1:4002/control/restart-source/cyber

"Authentication failed" (public mode)

  • Verify node.id and node.secret match what the platform generated
  • Check network.backendUrl is correct
  • Run hydra-node status to inspect your current config

Platform shows "Offline"

  • Ensure your endpoint URL is publicly accessible
  • Check your firewall allows inbound connections on port 4001
  • If behind a reverse proxy, ensure WebSocket upgrade headers are forwarded (see Reverse Proxy)
  • Verify heartbeats are being sent: check logs for heartbeat sent messages

Port already in use

Change the port in your config:

server:
  port: 4003  # any available port