Environment Variables

Lasso is configured via environment variables for runtime settings and YAML files for routing configuration. This page documents all available environment variables.

Core Configuration

Required and recommended settings for running Lasso.

string

required

Phoenix signing and encryption secret. Must be at least 64 bytes. Generate with mix phx.gen.secret.

SECRET_KEY_BASE=$(mix phx.gen.secret)

Required in production. Omit in development (auto-generated).

string

default:"localhost"

Public hostname for URL generation. Set to your domain in production.

PHX_HOST=rpc.example.com

Required in production for correct URL generation in responses and redirects.

string

default:"false"

Set to true to start the HTTP server. Required for releases and production deployments.

PHX_SERVER=true

integer

default:"4000"

HTTP listener port.

PORT=4000

Useful for running multiple instances locally:

PORT=4001 iex -S mix phx.server

string

default:"https"

URL scheme for external access. Automatically set to https in production.

PHX_SCHEME=https

string

required

Unique, stable identifier for this node instance. Used for state partitioning (circuit breakers, metrics) via {provider_id, node_id} keys.

LASSO_NODE_ID=us-east-1

Convention: Use geographic region names when deploying one node per region (e.g., us-east-1, eu-west-1, ap-southeast-1).Required in production. Defaults to "local" in development.

Clustering

Optional configuration for multi-node clustering.

string

DNS name that resolves to all node IPs for automatic cluster discovery.

CLUSTER_DNS_QUERY=lasso.internal

Both CLUSTER_DNS_QUERY and CLUSTER_NODE_BASENAME must be set for clustering to activate.

string

Erlang distribution node basename.

CLUSTER_NODE_BASENAME=lasso

Nodes will be named <basename>@<ip> (e.g., lasso@10.0.1.5).

Clustering Example

# Node 1 (us-east)
LASSO_NODE_ID=us-east-1
CLUSTER_DNS_QUERY=lasso.internal
CLUSTER_NODE_BASENAME=lasso

# Node 2 (eu-west)
LASSO_NODE_ID=eu-west-1
CLUSTER_DNS_QUERY=lasso.internal
CLUSTER_NODE_BASENAME=lasso

Nodes poll DNS every 5 seconds and automatically join the cluster. See Deployment Guide for details.

Provider API Keys

API keys for RPC providers. Used in profile YAML via ${VAR_NAME} substitution.

string

dRPC API key. Get yours at https://drpc.org/

DRPC_API_KEY=your_drpc_api_key_here

Use in profile:

url: "https://eth.drpc.org/${DRPC_API_KEY}"

string

Alchemy API key. Get yours at https://dashboard.alchemy.com/

ALCHEMY_API_KEY=your_alchemy_api_key_here

Use in profile:

url: "https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}"

string

Lava Network API key. Get yours at https://gateway.lavanet.xyz/

LAVA_API_KEY=your_lava_api_key_here

string

1RPC API key. Get yours at https://www.1rpc.io/

ONE_RPC_API_KEY=your_1rpc_api_key_here

string

Chainstack API key. Get yours at https://console.chainstack.com/

CHAINSTACK_API_KEY=your_chainstack_api_key_here

string

NodeReal API key. Get yours at https://nodereal.io/

NODEREAL_API_KEY=your_nodereal_api_key_here

Custom API Keys

You can use any environment variable in your profile configurations:

providers:
  - id: "custom_provider"
    url: "https://rpc.example.com/v1/${MY_CUSTOM_API_KEY}"

export MY_CUSTOM_API_KEY=secret-key-here

Important: Unresolved variables crash at startup to prevent silent misconfiguration.

Optional Settings

boolean

default:"true"

Enable VM metrics collection (memory, CPU, process counts).

LASSO_VM_METRICS_ENABLED=false

Set to false in production SaaS environments where VM metrics aren’t relevant.

string

PostgreSQL connection URL. Only used in cloud/SaaS deployments for persistent storage.

DATABASE_URL=postgresql://user:pass@host:5432/database

Not required for standalone deployments. Lasso uses in-memory ETS tables by default.

.env File Support

Lasso loads environment variables from a .env file in the project root if present:

# .env
LASSO_NODE_ID=local-dev
ALCHEMY_API_KEY=your-key-here
DRPC_API_KEY=another-key

Precedence: System environment variables override .env file values.

Example .env File

# Core configuration
SECRET_KEY_BASE=your-secret-key-base-here
PHX_HOST=localhost
PORT=4000
LASSO_NODE_ID=local-dev

# Provider API keys
ALCHEMY_API_KEY=your_alchemy_api_key_here
DRPC_API_KEY=your_drpc_api_key_here
LAVA_API_KEY=your_lava_api_key_here
ONE_RPC_API_KEY=your_1rpc_api_key_here
CHAINSTACK_API_KEY=your_chainstack_api_key_here
NODEREAL_API_KEY=your_nodereal_api_key_here

Production Checklist

Before deploying to production:

Core Settings

SECRET_KEY_BASE set (64+ bytes)
PHX_HOST set to public hostname
PHX_SERVER=true set
LASSO_NODE_ID set to unique, stable value
PORT configured for your infrastructure

Provider Keys

API keys set for all BYOK providers in profiles
Environment variable substitution tested (startup should crash on unresolved vars)
Keys stored securely (secrets manager, not version control)

Clustering (if used)

CLUSTER_DNS_QUERY set and resolving correctly
CLUSTER_NODE_BASENAME set
Erlang distribution ports open between nodes (4369 + epmd range)
Each node has unique LASSO_NODE_ID

Infrastructure

Health check monitoring GET /api/health
TLS terminated at reverse proxy/load balancer
Structured JSON log drain configured
Rate limits configured in profile frontmatter

Development vs Production

Development

# Minimal development setup
LASSO_NODE_ID=local-dev
PORT=4000

# Optional: Add API keys for BYOK providers
ALCHEMY_API_KEY=your-key-here

Run with:

mix phx.server

Production

# Required
SECRET_KEY_BASE=<64+ byte secret>
PHX_HOST=rpc.example.com
PHX_SERVER=true
LASSO_NODE_ID=us-east-1

# Recommended
PORT=4000
PHX_SCHEME=https

# Provider keys (as needed)
ALCHEMY_API_KEY=<key>
DRPC_API_KEY=<key>

# Clustering (optional)
CLUSTER_DNS_QUERY=lasso.internal
CLUSTER_NODE_BASENAME=lasso

Run with:

MIX_ENV=prod mix release
_build/prod/rel/lasso/bin/lasso start

Environment Variable Precedence

System environment variables (highest priority)
.env file (loaded at startup)
Application defaults (config/runtime.exs)

Example:

# .env file
PORT=4000

# System override
PORT=5000 mix phx.server  # Uses 5000, not 4000

Get Started

Core Concepts

Configuration

Deployment

Observability

Advanced

Environment Variables

Core Configuration

Clustering

Clustering Example

Provider API Keys

Custom API Keys

Optional Settings

.env File Support

Example .env File

Production Checklist

Development vs Production

Development

Production

Environment Variable Precedence

Next Steps

Deployment Guide

Profile Configuration

​Core Configuration

​Clustering

​Clustering Example

​Provider API Keys

​Custom API Keys

​Optional Settings

​.env File Support

​Example .env File

​Production Checklist

​Development vs Production

​Development

​Production

​Environment Variable Precedence

​Next Steps

Deployment Guide

Profile Configuration

Core Configuration

Clustering

Clustering Example

Provider API Keys

Custom API Keys

Optional Settings

.env File Support

Example .env File

Production Checklist

Development vs Production

Development

Production

Environment Variable Precedence

Next Steps