Running Your Own Beacon

rng.dev is fully open source under MIT license. You can run your own beacon with no restrictions or fees.

Why Self-Host?

Independence: Don't rely on our infrastructure
Customization: Add your own sources, change configuration
Privacy: Keep your usage patterns private
Compliance: Meet specific regulatory requirements

Prerequisites

Docker and Docker Compose
2GB RAM minimum
API keys for some blockchain RPC providers (see below)

API Keys & RPC Providers

The beacon fetches data from 8 blockchains. Some have free public endpoints; others require API keys.

Required API Keys

Chain	Provider	Free Tier	Get Key
Cardano	Blockfrost	50,000 requests/day	blockfrost.io
Solana	Helius	100,000 credits/mo	helius.dev

Recommended (Higher Rate Limits)

Chain	Provider	Free Tier	Get Key
Ethereum	Alchemy	300M compute units/mo	alchemy.com
Arbitrum	Alchemy	Included with Ethereum	Same key as Ethereum
Base	Alchemy	Included with Ethereum	Same key as Ethereum

Free Public Endpoints (No Key Needed)

Chain	Default Endpoint	Notes
Aptos	`fullnode.mainnet.aptoslabs.com`	Official Aptos Labs node
Bitcoin	`mempool.space/api`	Community-run, reliable
Sui	`fullnode.mainnet.sui.io`	Official Sui Foundation node

Fallback Strategy

Each chain has multiple fallback endpoints configured. If the primary fails, the beacon automatically rotates through:

Ankr — Free public RPCs for most chains
LlamaNodes — Free public RPCs
PublicNode — Free public RPCs

The beacon will operate with degraded reliability without API keys, but we recommend getting at least Blockfrost (Cardano) and Helius (Solana) keys for production use.

Quick Start

1. Clone the Repository

git clone https://github.com/hugoelliott/beacon.git
cd beacon

2. Configure Environment

cp .env.example .env

Edit .env with your API keys:

# Required: Cardano via Blockfrost (free tier: 50k requests/day)
# Get key at: https://blockfrost.io
BLOCKFROST_API_KEY=mainnetYourKeyHere

# Required: Solana via Helius (free tier: 100k credits/month)
# Get key at: https://helius.dev
HELIUS_API_KEY=your_helius_key

# Recommended: Alchemy for Ethereum/Arbitrum/Base (free tier: 300M CU/month)
# Get key at: https://alchemy.com
# One key works for all three chains
ALCHEMY_API_KEY=your_alchemy_key

# Database (defaults work for Docker Compose)
DATABASE_URL=postgresql+asyncpg://beacon:beacon@localhost:5432/beacon  # pragma: allowlist secret

3. Start Services

docker-compose up -d

4. Verify It's Working

# Check health
curl http://localhost:8000/api/v1/health

# Get current round (after first second)
curl http://localhost:8000/api/v1/current

Configuration Options

Environment Variables

Core Settings

Variable	Default	Description
`BEACON_ROUND_DURATION_SECONDS`	`1`	Duration of each beacon round
`DEBUG`	`false`	Enable debug logging
`CORS_ORIGINS`	`localhost`	Comma-separated allowed origins

API Keys

Variable	Default	Description
`BLOCKFROST_API_KEY`	-	Cardano Blockfrost API key
`HELIUS_API_KEY`	-	Solana Helius API key
`ALCHEMY_API_KEY`	-	Alchemy key (Ethereum/Arbitrum/Base)

Custom RPC Endpoints

Override default endpoints if you have your own nodes or preferred providers:

Variable	Default	Description
`APTOS_RPC_URL`	`fullnode.mainnet.aptoslabs.com`	Aptos REST API
`BITCOIN_RPC_URL`	`mempool.space/api`	Bitcoin API
`CARDANO_RPC_URL`	`cardano-mainnet.blockfrost.io`	Cardano Blockfrost
`ETHEREUM_RPC_URL`	`ethereum-rpc.publicnode.com`	Ethereum JSON-RPC
`SOLANA_RPC_URL`	`api.mainnet-beta.solana.com`	Solana JSON-RPC
`SUI_RPC_URL`	`fullnode.mainnet.sui.io`	Sui JSON-RPC

Database

Variable	Default	Description
`DATABASE_URL`	-	Full PostgreSQL connection string
`DATABASE_HOST`	`localhost`	PostgreSQL host
`DATABASE_PORT`	`5432`	PostgreSQL port
`DATABASE_USER`	`beacon`	PostgreSQL user
`DATABASE_PASSWORD`	`beacon`	PostgreSQL password
`DATABASE_NAME`	`beacon`	PostgreSQL database name
`POSTGRES_ROUNDS_RETENTION`	`100000`	Rounds to keep (~27 hours)

Alerting

Variable	Default	Description
`ALERT_WEBHOOK_URL`	-	Slack/Discord webhook for alerts
`ALERT_COOLDOWN_SECONDS`	`300`	Minimum time between duplicate alerts
`ALERT_FAILURE_THRESHOLD`	`3`	Consecutive failures before alerting

Optional Entropy Sources

Self-hosted operators can optionally add additional entropy sources beyond the standard blockchain inputs.

drand Integration

Add drand's threshold BLS signatures for applications requiring that specific proof type.

# config/entropy.yaml
optional_sources:
  drand:
    enabled: true
    network: "quicknet"
    wait_for_next: true  # Wait for future round (front-running prevention)

Properties:

Adds ~1.5 second average latency (waiting for next drand round)
Provides BLS threshold signatures from 20+ operators
Useful for regulatory requirements specifying "threshold cryptography"

NIST Beacon Integration

Add NIST Randomness Beacon for applications requiring US government attestation.

optional_sources:
  nist:
    enabled: true
    wait_for_next: true  # Wait for future pulse (front-running prevention)

Properties:

Adds ~60 second average latency (NIST publishes every 60 seconds)
Provides hash chain precommitment from NIST
Useful for US government or regulated environments requiring NIST attestation

Hardware Entropy

Add local hardware RNG for air-gapped or high-security deployments.

optional_sources:
  hardware:
    enabled: true
    device: "/dev/hwrng"  # Or specific hardware RNG device
    bytes: 32

Properties:

Truly random (quantum/thermal noise)
Not publicly verifiable (must trust operator)
Useful for adding defense-in-depth entropy

Becoming a Validator

Self-hosted beacons can participate in the validator network. Validators independently verify each round and submit signed attestations, creating decentralized trust.

Enable validator mode:

# In .env
VALIDATOR_MODE=true

What happens:

On startup, your instance registers as a validator
After each round, you submit a signed attestation
Public can see your validator uptime on rng.dev/validators

Benefits:

Contribute to decentralized verification
Public recognition on validator leaderboard
Help ensure beacon integrity

Requirements:

Outbound HTTPS access to api.rng.dev
Stable uptime (attestations within 30s of round generation)

Your validator keypair is stored at ~/.beacon/validator.key. Back this up if you want to maintain your validator identity.

Adding Custom Sources

You can add your own entropy sources by implementing the EntropySource interface:

from app.services.fetchers.base import EntropySource

class MyCustomSource(EntropySource):
    name = "mycustom"

    async def fetch(self) -> str | None:
        """
        Fetch entropy and return canonicalized string.
        Return None if unavailable.
        """
        # Your implementation here
        data = await self.fetch_from_api()
        return f"{data['id']}:{data['hash']}"

SOURCES = [
    AptosSource(),
    BitcoinSource(),
    CardanoSource(),
    EthereumSource(),
    SolanaSource(),
    SuiSource(),
    MyCustomSource(),  # Add your source
]

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Your Self-Hosted Beacon                                     │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   Backend    │  │  PostgreSQL  │  │    Redis     │       │
│  │   (FastAPI)  │◄─┤              │  │              │       │
│  │   Port 8000  │  │   Port 5432  │  │   Port 6379  │       │
│  └──────┬───────┘  └──────────────┘  └──────────────┘       │
│         │                                                    │
│  ┌──────▼───────┐                                           │
│  │   Frontend   │  (Optional)                               │
│  │   (Next.js)  │                                           │
│  │   Port 3000  │                                           │
│  └──────────────┘                                           │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Production Deployment

Using Kamal

We provide Kamal configuration for bare-metal deployment:

# Configure your server in deploy/config/deploy.yml
kamal setup
kamal deploy

Manual Docker Deployment

# Build production images
docker-compose -f docker-compose.prod.yml build

# Deploy with your orchestrator of choice
docker-compose -f docker-compose.prod.yml up -d

SSL/TLS

For production, place behind a reverse proxy (nginx, Caddy, Traefik) with SSL:

server {
    listen 443 ssl;
    server_name beacon.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Backup & Recovery

Database Backup

# Backup
docker exec beacon-postgres pg_dump -U beacon beacon_db > backup.sql

# Restore
docker exec -i beacon-postgres psql -U beacon beacon_db < backup.sql

Important Data

The critical data to back up:

Data	Location	Importance
Round history	PostgreSQL `rounds` table	High — enables verification
Source inputs	PostgreSQL `rounds.input_*` columns	High — needed for re-verification
Statistics	PostgreSQL `stats` tables	Medium — can be recomputed
Redis cache	Redis	Low — rebuilds automatically

Monitoring

Health Endpoints

# Basic health
curl http://localhost:8000/api/v1/health

# Gap detection (missing rounds)
curl http://localhost:8000/api/v1/health/gaps

Recommended Monitoring

Uptime: Monitor /api/v1/health endpoint
Round generation: Alert if no new round in 5+ seconds
Source availability: Track sources_available in responses
Database size: Monitor PostgreSQL disk usage

Troubleshooting

No rounds being generated

Check logs: docker-compose logs backend
Verify API keys are set correctly
Check network connectivity to blockchain APIs
Ensure at least 2 sources are reachable

High latency on round generation

Check blockchain API rate limits
Consider using paid RPC tiers
Add fallback providers

Database growing too large

Implement partitioning (see migrations/)
Archive old rounds to cold storage
Keep only recent data in hot storage

Differences from rng.dev

When self-hosting, note these differences:

Feature	rng.dev	Self-Hosted
Availability	99.9% SLA	Your responsibility
Validator network	Planned	Can participate
Historical data	Since genesis	Since your start date
Support	Email support	Community only

Contributing

Found a bug or want to add a feature?

Fork the repository
Create a feature branch
Submit a pull request

See CONTRIBUTING.md for guidelines.

Next Steps

How It Works — Understand the algorithm
Verification Guide — Test your instance
API Reference — API documentation

Why Self-Host?​

Prerequisites​

API Keys & RPC Providers​

Required API Keys​

Recommended (Higher Rate Limits)​

Free Public Endpoints (No Key Needed)​

Fallback Strategy​

Quick Start​

1. Clone the Repository​

2. Configure Environment​

3. Start Services​

4. Verify It's Working​

Configuration Options​

Environment Variables​

Core Settings​

API Keys​

Custom RPC Endpoints​

Database​

Alerting​

Optional Entropy Sources​

drand Integration​

NIST Beacon Integration​

Hardware Entropy​

Becoming a Validator​

Adding Custom Sources​

Architecture​

Production Deployment​

Using Kamal​

Manual Docker Deployment​

SSL/TLS​

Backup & Recovery​

Database Backup​

Important Data​

Monitoring​

Health Endpoints​

Recommended Monitoring​

Troubleshooting​

No rounds being generated​

High latency on round generation​

Database growing too large​

Differences from rng.dev​

Contributing​

Next Steps​

Why Self-Host?

Prerequisites

API Keys & RPC Providers

Required API Keys

Recommended (Higher Rate Limits)

Free Public Endpoints (No Key Needed)

Fallback Strategy

Quick Start

1. Clone the Repository

2. Configure Environment

3. Start Services

4. Verify It's Working

Configuration Options

Environment Variables

Core Settings

API Keys

Custom RPC Endpoints

Database

Alerting

Optional Entropy Sources

drand Integration

NIST Beacon Integration

Hardware Entropy

Becoming a Validator

Adding Custom Sources

Architecture

Production Deployment

Using Kamal

Manual Docker Deployment

SSL/TLS

Backup & Recovery

Database Backup

Important Data

Monitoring

Health Endpoints

Recommended Monitoring

Troubleshooting

No rounds being generated

High latency on round generation

Database growing too large

Differences from rng.dev

Contributing

Next Steps