Configuration Guide

Overview

Agora uses environment variables for all configuration. This guide provides comprehensive documentation for every environment variable with usage examples and best practices.

Create a .env.local file in your project root for local development. Never commit this file to version control.

Critical Configuration (Required)

These variables are required for the application to start.

NEXT_PUBLIC_AGORA_INSTANCE_NAME

string

required

Identifies which DAO configuration to load.Supported values: ens, uniswap, optimism, derive, cyber, xai, boost, scroll, linea, etherfi, b3, protocol-guildExample:

NEXT_PUBLIC_AGORA_INSTANCE_NAME=ens

Impact: Controls the entire tenant configuration including contracts, UI theme, and features.

NEXT_PUBLIC_AGORA_INSTANCE_TOKEN

string

required

Token symbol for the DAO instance.Example:

NEXT_PUBLIC_AGORA_INSTANCE_TOKEN=ENS

Usage: Displayed throughout the UI when referring to the governance token.

NEXT_PUBLIC_AGORA_ENV

string

required

Determines production vs development environment.Values: prod for production, dev or any other value for developmentExample:

NEXT_PUBLIC_AGORA_ENV=prod

Controls:

Which database URLs are used (READ_WRITE_WEB2_DATABASE_URL_PROD vs _DEV)
Contract addresses (mainnet vs testnet)
Feature toggles and safety checks
API endpoints (prod vs dev environments)
EAS schema selection
Snapshot space selection

NEXT_PUBLIC_ALCHEMY_ID

string

required

Alchemy API key for client-side blockchain RPC access.Example:

NEXT_PUBLIC_ALCHEMY_ID=your_client_alchemy_api_key

This key is public but sensitive. Must be domain-whitelisted in your Alchemy dashboard to prevent abuse.

Usage: Used for client-side chain interactions (wagmi, Web3Provider, hooks)Fallback: Can be overridden by NEXT_PUBLIC_FORK_NODE_URL for local development

NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID

string

required

WalletConnect v2 project identifier.Example:

NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_project_id

Get credentials: WalletConnect CloudUsage: Enables wallet connections via WalletConnect protocol

Database Configuration

Agora uses a dual-database architecture for optimal performance.

DATABASE_URL

string

PostgreSQL database connection string or environment selector.Special values:

"dev" - Uses development database URLs
"prod" - Uses production database URLs
Direct URL - Overrides environment-specific URLs

Format:

DATABASE_URL=postgres://user:password@host:5432/database

Fallback: If not set, uses environment-specific URLs below

READ_WRITE_WEB2_DATABASE_URL_PROD / READ_WRITE_WEB2_DATABASE_URL_DEV

READ_WRITE_WEB2_DATABASE_URL_*

string

required

Database for user-generated content (profiles, settings, delegate statements).Example:

READ_WRITE_WEB2_DATABASE_URL_PROD=postgres://user:pass@host:5432/agora_web2
READ_WRITE_WEB2_DATABASE_URL_DEV=postgres://user:pass@localhost:5432/agora_web2_dev

Usage: Read-write operations for web2 dataSelection: Based on NEXT_PUBLIC_AGORA_ENV value

READ_ONLY_WEB3_DATABASE_URL_PROD / READ_ONLY_WEB3_DATABASE_URL_DEV

READ_ONLY_WEB3_DATABASE_URL_*

string

required

Database for blockchain indexed data.Example:

READ_ONLY_WEB3_DATABASE_URL_PROD=postgres://user:pass@host:5432/agora_web3
READ_ONLY_WEB3_DATABASE_URL_DEV=postgres://user:pass@localhost:5432/agora_web3_dev

Usage: Read-only operations for web3 data (proposals, votes, delegates)

This separation allows for optimized querying of blockchain data without affecting user-generated content operations.

Authentication & Security

Critical security credentials for various features.

GAS_SPONSOR_PK

Private key for sponsoring gas fees in relay transactions.Format: Hex string without 0x prefixExample:

GAS_SPONSOR_PK=your_private_key_without_0x

CRITICAL - Never expose in client code or logs. Server-side only at /api/v1/relay/*

Usage: Enables users to delegate/vote without paying gas

EAS_SENDER_PRIVATE_KEY

string

Private key for Ethereum Attestation Service operations.Example:

EAS_SENDER_PRIVATE_KEY=your_eas_private_key

CRITICAL - Server-side only. Used for creating on-chain attestations for verified delegates.

JWT_SECRET

string

required

Secret for signing JWT tokens.Example:

JWT_SECRET=your_long_random_secret_at_least_32_characters

Must be strong and unique per environment. Minimum 32 characters recommended.

Usage: User session management and authentication

Network & RPC Configuration

SERVERSIDE_ALCHEMY_ID_PROD / SERVERSIDE_ALCHEMY_ID_DEV

SERVERSIDE_ALCHEMY_ID_*

string

Alchemy API keys for server-side blockchain RPC access.Example:

SERVERSIDE_ALCHEMY_ID_PROD=your_prod_server_alchemy_key
SERVERSIDE_ALCHEMY_ID_DEV=your_dev_server_alchemy_key

Benefits:

Private - never exposed to browser
No domain restrictions needed
Prevents leaked client keys from server-side abuse

Auto-detection: Code automatically uses the right key based on execution context and environmentFallback: Falls back to NEXT_PUBLIC_ALCHEMY_ID if not set

NEXT_PUBLIC_FORK_NODE_URL

string

Override RPC endpoint for development/testing.Example:

NEXT_PUBLIC_FORK_NODE_URL=http://localhost:8545

Use cases:

Local Anvil/Hardhat forks
Testing contract interactions
Debugging transactions

Priority: Takes precedence over Alchemy when set

NEXT_PUBLIC_CONDUIT_KEY

string

API key for Conduit RPC (Derive chain).Example:

NEXT_PUBLIC_CONDUIT_KEY=your_conduit_key

Required for: Derive tenant onlyUsage: Constructs RPC URLs for Derive mainnet/testnet (https://rpc.derive.xyz/{key})

DAONODE_URL_TEMPLATE

string

required

Template for DAO-specific data endpoints.Format:

DAONODE_URL_TEMPLATE=https://{TENANT_NAMESPACE}.example.com/

Variables: {TENANT_NAMESPACE} is replaced with instance nameUsage: Fetches proposal details, voting data

External Services

Tenderly (Transaction Simulation)

TENDERLY_USER

string

Tenderly username for transaction simulation.

TENDERLY_PROJECT

string

Tenderly project name.

TENDERLY_ACCESS_KEY

string

Tenderly access key.Example:

TENDERLY_USER=your_username
TENDERLY_PROJECT=your_project
TENDERLY_ACCESS_KEY=your_access_key

Get credentials: Tenderly DashboardUsage: Simulates proposal execution before voting

All three variables must be set for simulation to work. Features disabled if missing.

Pinata (IPFS Storage)

PINATA_JWT

string

Pinata JWT token (preferred method).

PINATA_API_KEY

string

Pinata API key (legacy).

PINATA_SECRET_API_KEY

string

Pinata secret API key (legacy).Example:

# Preferred method
PINATA_JWT=your_jwt_token

# Or legacy method
PINATA_API_KEY=your_api_key
PINATA_SECRET_API_KEY=your_secret_key

Get credentials: Pinata CloudUsage: Stores proposal descriptions and supporting documents on IPFSPriority: PINATA_JWT preferred over API key/secret pair

Etherscan

NEXT_PUBLIC_ETHERSCAN_API_KEY

string

Etherscan API key for contract verification and ABI fetching.Example:

NEXT_PUBLIC_ETHERSCAN_API_KEY=your_etherscan_key

Usage:

Fetches contract ABIs dynamically
Decodes transaction data
Verifies contract source code

Free tier has rate limits. Monitor usage to avoid hitting limits.

GitHub PR Bot

PR_BOT_TOKEN

string

GitHub token for creating pull requests.Example:

PR_BOT_TOKEN=ghp_your_token

Permissions: Requires repo write accessUsage: Creates PRs for ENS executable proposalsRelated: Works with ENVIRONMENT variable to target correct repository

Deployment Configuration

NEXT_PUBLIC_AGORA_BASE_URL

string

required

Application base URL for metadata and API calls.Format: Full URL including protocolExample:

# Production
NEXT_PUBLIC_AGORA_BASE_URL=https://vote.ens.domains

# Development
NEXT_PUBLIC_AGORA_BASE_URL=http://localhost:3000

Usage: Used in wallet connection metadata and API calls

NEXT_PUBLIC_AGORA_ROOT

string

Application root path for subpath deployments.Default: /Example:

NEXT_PUBLIC_AGORA_ROOT=/governance

Use case: Deploying under a subpath instead of root domain

NODE_ENV

string

Node.js environment mode (automatically set by Next.js).Values: production, development, test

Automatically set by next dev (development) and next build (production). Do not set manually.

Impact:

Production mode enables optimizations
Development mode enables hot reload
Controls Prisma client behavior and caching

Vercel Environment Variables

These variables are automatically set by Vercel. Do not set manually.

VERCEL_ENV

string

Deployment environment: production, preview, or development

VERCEL_REGION

string

Deployment region

VERCEL_GIT_COMMIT_SHA

string

Git commit SHA for the deployment

VERCEL_URL

string

Deployment URL

Usage: OpenTelemetry tracing attributes for monitoring

Feature Flags

Toggle optional features on or off.

NEXT_PUBLIC_SIWE_ENABLED

boolean

Enable Sign-In with Ethereum.Values: "true" to enable, any other value disablesExample:

NEXT_PUBLIC_SIWE_ENABLED=true

Default: DisabledImpact: Allows wallet-based authentication

NEXT_PUBLIC_ENABLE_BI_METRICS_CAPTURE

boolean

Enable analytics event tracking.Values: "true" to enableExample:

NEXT_PUBLIC_ENABLE_BI_METRICS_CAPTURE=true

Default: DisabledRelated: Requires NEXT_PUBLIC_AGORA_API_KEYImpact: Sends usage metrics to analytics endpoint

NEXT_PUBLIC_MUTE_QUERY_LOGGING

boolean

Disable database query logging.Values: "true" to disable loggingExample:

NEXT_PUBLIC_MUTE_QUERY_LOGGING=true

Default: Logging enabledUse case: Reduce noise in development logs

Monitoring & Analytics

DataDog

DD_API_KEY

string

DataDog API key.

DD_APP_KEY

string

DataDog application key.

ENABLE_DD_METRICS

boolean

Toggle DataDog metrics collection.Example:

DD_API_KEY=your_dd_api_key
DD_APP_KEY=your_dd_app_key
ENABLE_DD_METRICS=true

Default: Disabled

Both DD keys must be set for this to work.

Usage: Sends application metrics and alerts to DataDog

Advanced Features

AWS Services

AWS_ACCESS_KEY_ID

string

AWS access key ID.

AWS_SECRET_ACCESS_KEY

string

AWS secret access key.Example:

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Use IAM roles in production when possible for better security.

Usage:

DynamoDB access
S3 bucket operations

STORAGE_BUCKET_URL

string

Base URL for storage bucket.Format: Full URL with trailing slashExample:

STORAGE_BUCKET_URL=https://my-bucket.s3.amazonaws.com/

Usage: Fetches contract ABIs from backup storage

Smart Accounts

NEXT_PUBLIC_ALCHEMY_SMART_ACCOUNT

string

Alchemy API key for smart account features.Example:

NEXT_PUBLIC_ALCHEMY_SMART_ACCOUNT=your_smart_account_key

Note: Separate from regular API keyGet it from: Alchemy dashboardUsage: Enables account abstraction features

PAYMASTER_SECRET

string

Secret for paymaster service integration.Usage: Enables sponsored transactions

Environment Setup Examples

Minimum Required for Development

# Core Configuration
NEXT_PUBLIC_AGORA_INSTANCE_NAME=ens
NEXT_PUBLIC_AGORA_INSTANCE_TOKEN=ENS
NEXT_PUBLIC_AGORA_ENV=dev

# API Keys
NEXT_PUBLIC_ALCHEMY_ID=your_alchemy_key
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_walletconnect_project_id
NEXT_PUBLIC_AGORA_API_KEY=your_agora_api_key

# URLs
NEXT_PUBLIC_AGORA_BASE_URL=http://localhost:3000
DAONODE_URL_TEMPLATE=https://{TENANT_NAMESPACE}.example.com/

# Database
DATABASE_URL=postgres://user:password@localhost:5432/agora
# OR use environment-specific URLs
READ_WRITE_WEB2_DATABASE_URL_DEV=postgres://user:pass@localhost:5432/agora_web2
READ_ONLY_WEB3_DATABASE_URL_DEV=postgres://user:pass@localhost:5432/agora_web3

# Security
JWT_SECRET=your_long_random_secret_at_least_32_characters

Production Configuration

# Core Configuration
NEXT_PUBLIC_AGORA_INSTANCE_NAME=ens
NEXT_PUBLIC_AGORA_INSTANCE_TOKEN=ENS
NEXT_PUBLIC_AGORA_ENV=prod

# API Keys
NEXT_PUBLIC_ALCHEMY_ID=your_client_alchemy_key
SERVERSIDE_ALCHEMY_ID_PROD=your_server_alchemy_key
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_walletconnect_id
NEXT_PUBLIC_ETHERSCAN_API_KEY=your_etherscan_key

# URLs
NEXT_PUBLIC_AGORA_BASE_URL=https://vote.ens.domains
DAONODE_URL_TEMPLATE=https://{TENANT_NAMESPACE}.example.com/

# Database
READ_WRITE_WEB2_DATABASE_URL_PROD=postgres://user:pass@host/agora_web2_prod
READ_ONLY_WEB3_DATABASE_URL_PROD=postgres://user:pass@host/agora_web3_prod

# Security
JWT_SECRET=production_secret_key_very_strong_and_unique
GAS_SPONSOR_PK=private_key_for_gas_sponsoring
EAS_SENDER_PRIVATE_KEY=private_key_for_eas

# External Services
TENDERLY_USER=your_username
TENDERLY_PROJECT=your_project
TENDERLY_ACCESS_KEY=your_access_key
PINATA_JWT=your_pinata_jwt

# Monitoring
ENABLE_DD_METRICS=true
DD_API_KEY=your_datadog_api_key
DD_APP_KEY=your_datadog_app_key

Security Best Practices

Follow these security guidelines to protect your deployment:

Never commit .env files with real credentials to version control
Use different keys for development and production
Rotate private keys regularly, especially gas sponsor and EAS keys
Monitor API key usage in provider dashboards (Alchemy, Pinata, etc.)
Use environment-specific databases to prevent accidental data corruption
Keep server-side keys out of NEXT_PUBLIC_* variables
Whitelist domains in Alchemy dashboard for NEXT_PUBLIC_ALCHEMY_ID
Use IAM roles in production instead of AWS access keys when possible

Next Steps

Setup Guide

Complete initial setup with these environment variables

Deployment

Deploy to production with proper configuration

Customization

Customize your tenant configuration

Architecture

Understand the system architecture

Get Started

Core Features

Advanced Features

Guides

​Overview

​Critical Configuration (Required)

​NEXT_PUBLIC_AGORA_INSTANCE_NAME

​NEXT_PUBLIC_AGORA_INSTANCE_TOKEN

​NEXT_PUBLIC_AGORA_ENV

​NEXT_PUBLIC_ALCHEMY_ID

​NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID

​Database Configuration

​DATABASE_URL

​READ_WRITE_WEB2_DATABASE_URL_PROD / READ_WRITE_WEB2_DATABASE_URL_DEV

​READ_ONLY_WEB3_DATABASE_URL_PROD / READ_ONLY_WEB3_DATABASE_URL_DEV

​Authentication & Security

​GAS_SPONSOR_PK

​EAS_SENDER_PRIVATE_KEY

​JWT_SECRET

​Network & RPC Configuration

​SERVERSIDE_ALCHEMY_ID_PROD / SERVERSIDE_ALCHEMY_ID_DEV

​NEXT_PUBLIC_FORK_NODE_URL

​NEXT_PUBLIC_CONDUIT_KEY

​DAONODE_URL_TEMPLATE

​External Services

​Tenderly (Transaction Simulation)

​Pinata (IPFS Storage)

​Etherscan

​GitHub PR Bot

​Deployment Configuration

​NEXT_PUBLIC_AGORA_BASE_URL

​NEXT_PUBLIC_AGORA_ROOT

​NODE_ENV

​Vercel Environment Variables

​Feature Flags

​NEXT_PUBLIC_SIWE_ENABLED

​NEXT_PUBLIC_ENABLE_BI_METRICS_CAPTURE

​NEXT_PUBLIC_MUTE_QUERY_LOGGING

​Monitoring & Analytics

​DataDog

​Advanced Features

​AWS Services

​STORAGE_BUCKET_URL

​Smart Accounts

​Environment Setup Examples

​Minimum Required for Development

​Production Configuration

​Security Best Practices

​Next Steps

Setup Guide

Deployment

Customization

Architecture

Build docs developers (and LLMs) love

Overview

Critical Configuration (Required)

NEXT_PUBLIC_AGORA_INSTANCE_NAME

NEXT_PUBLIC_AGORA_INSTANCE_TOKEN

NEXT_PUBLIC_AGORA_ENV

NEXT_PUBLIC_ALCHEMY_ID

NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID

Database Configuration

DATABASE_URL

READ_WRITE_WEB2_DATABASE_URL_PROD / READ_WRITE_WEB2_DATABASE_URL_DEV

READ_ONLY_WEB3_DATABASE_URL_PROD / READ_ONLY_WEB3_DATABASE_URL_DEV

Authentication & Security

GAS_SPONSOR_PK

EAS_SENDER_PRIVATE_KEY

JWT_SECRET

Network & RPC Configuration

SERVERSIDE_ALCHEMY_ID_PROD / SERVERSIDE_ALCHEMY_ID_DEV

NEXT_PUBLIC_FORK_NODE_URL

NEXT_PUBLIC_CONDUIT_KEY

DAONODE_URL_TEMPLATE

External Services

Tenderly (Transaction Simulation)

Pinata (IPFS Storage)

Etherscan

GitHub PR Bot

Deployment Configuration

NEXT_PUBLIC_AGORA_BASE_URL

NEXT_PUBLIC_AGORA_ROOT

NODE_ENV

Vercel Environment Variables

Feature Flags

NEXT_PUBLIC_SIWE_ENABLED

NEXT_PUBLIC_ENABLE_BI_METRICS_CAPTURE

NEXT_PUBLIC_MUTE_QUERY_LOGGING

Monitoring & Analytics

DataDog

Advanced Features

AWS Services

STORAGE_BUCKET_URL

Smart Accounts

Environment Setup Examples

Minimum Required for Development

Production Configuration

Security Best Practices

Next Steps