Configuration Guide

Complete guide to environment variables and configuration options for Agora

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

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-guild

Example:

NEXT_PUBLIC_AGORA_INSTANCE_NAME=ens

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

NEXT_PUBLIC_AGORA_INSTANCE_TOKEN

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

NEXT_PUBLIC_AGORA_ENV · string · required

Determines production vs development environment.

Values: prod for production, dev or any other value for development

Example:

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

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

NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID · string · required

WalletConnect v2 project identifier.

Example:

NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_project_id

Get credentials: WalletConnect Cloud

Usage: Enables wallet connections via WalletConnect protocol

Database Configuration

Agora uses a dual-database architecture for optimal performance.

DATABASE_URL

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 data

Selection: 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

GAS_SPONSOR_PK · string

Private key for sponsoring gas fees in relay transactions.

Format: Hex string without 0x prefix

Example:

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

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

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 environment

Fallback: Falls back to NEXT_PUBLIC_ALCHEMY_ID if not set

NEXT_PUBLIC_FORK_NODE_URL

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

NEXT_PUBLIC_CONDUIT_KEY · string

API key for Conduit RPC (Derive chain).

Example:

NEXT_PUBLIC_CONDUIT_KEY=your_conduit_key

Required for: Derive tenant only

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

DAONODE_URL_TEMPLATE

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 name

Usage: 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 Dashboard

Usage: 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 Cloud

Usage: Stores proposal descriptions and supporting documents on IPFS

Priority: 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 access

Usage: Creates PRs for ENS executable proposals

Related: Works with ENVIRONMENT variable to target correct repository

Deployment Configuration

NEXT_PUBLIC_AGORA_BASE_URL

NEXT_PUBLIC_AGORA_BASE_URL · string · required

Application base URL for metadata and API calls.

Format: Full URL including protocol

Example:

# 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

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

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

NEXT_PUBLIC_SIWE_ENABLED · boolean

Enable Sign-In with Ethereum.

Values: "true" to enable, any other value disables

Example:

NEXT_PUBLIC_SIWE_ENABLED=true

Default: Disabled

Impact: Allows wallet-based authentication

NEXT_PUBLIC_ENABLE_BI_METRICS_CAPTURE

NEXT_PUBLIC_ENABLE_BI_METRICS_CAPTURE · boolean

Enable analytics event tracking.

Values: "true" to enable

Example:

NEXT_PUBLIC_ENABLE_BI_METRICS_CAPTURE=true

Default: Disabled

Related: Requires NEXT_PUBLIC_AGORA_API_KEY

Impact: Sends usage metrics to analytics endpoint

NEXT_PUBLIC_MUTE_QUERY_LOGGING

NEXT_PUBLIC_MUTE_QUERY_LOGGING · boolean

Disable database query logging.

Values: "true" to disable logging

Example:

NEXT_PUBLIC_MUTE_QUERY_LOGGING=true

Default: Logging enabled

Use 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

STORAGE_BUCKET_URL · string

Base URL for storage bucket.

Format: Full URL with trailing slash

Example:

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 key

Get it from: Alchemy dashboard

Usage: 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:

1. Never commit .env files with real credentials to version control
2. Use different keys for development and production
3. Rotate private keys regularly, especially gas sponsor and EAS keys
4. Monitor API key usage in provider dashboards (Alchemy, Pinata, etc.)
5. Use environment-specific databases to prevent accidental data corruption
6. Keep server-side keys out of NEXT_PUBLIC_* variables
7. Whitelist domains in Alchemy dashboard for NEXT_PUBLIC_ALCHEMY_ID
8. 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