> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/voteagora/agora-next/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  Create a `.env.local` file in your project root for local development. Never commit this file to version control.
</Note>

## Critical Configuration (Required)

These variables are required for the application to start.

### NEXT\_PUBLIC\_AGORA\_INSTANCE\_NAME

<ParamField path="NEXT_PUBLIC_AGORA_INSTANCE_NAME" type="string" required>
  Identifies which DAO configuration to load.

  **Supported values**: `ens`, `uniswap`, `optimism`, `derive`, `cyber`, `xai`, `boost`, `scroll`, `linea`, `etherfi`, `b3`, `protocol-guild`

  **Example**:

  ```bash theme={null}
  NEXT_PUBLIC_AGORA_INSTANCE_NAME=ens
  ```

  **Impact**: Controls the entire tenant configuration including contracts, UI theme, and features.
</ParamField>

### NEXT\_PUBLIC\_AGORA\_INSTANCE\_TOKEN

<ParamField path="NEXT_PUBLIC_AGORA_INSTANCE_TOKEN" type="string" required>
  Token symbol for the DAO instance.

  **Example**:

  ```bash theme={null}
  NEXT_PUBLIC_AGORA_INSTANCE_TOKEN=ENS
  ```

  **Usage**: Displayed throughout the UI when referring to the governance token.
</ParamField>

### NEXT\_PUBLIC\_AGORA\_ENV

<ParamField path="NEXT_PUBLIC_AGORA_ENV" type="string" required>
  Determines production vs development environment.

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

  **Example**:

  ```bash theme={null}
  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
</ParamField>

### NEXT\_PUBLIC\_ALCHEMY\_ID

<ParamField path="NEXT_PUBLIC_ALCHEMY_ID" type="string" required>
  Alchemy API key for client-side blockchain RPC access.

  **Example**:

  ```bash theme={null}
  NEXT_PUBLIC_ALCHEMY_ID=your_client_alchemy_api_key
  ```

  <Warning>
    This key is public but sensitive. **Must be domain-whitelisted** in your Alchemy dashboard to prevent abuse.
  </Warning>

  **Usage**: Used for client-side chain interactions (wagmi, Web3Provider, hooks)

  **Fallback**: Can be overridden by `NEXT_PUBLIC_FORK_NODE_URL` for local development
</ParamField>

### NEXT\_PUBLIC\_WALLETCONNECT\_PROJECT\_ID

<ParamField path="NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID" type="string" required>
  WalletConnect v2 project identifier.

  **Example**:

  ```bash theme={null}
  NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_project_id
  ```

  **Get credentials**: [WalletConnect Cloud](https://cloud.walletconnect.com/)

  **Usage**: Enables wallet connections via WalletConnect protocol
</ParamField>

## Database Configuration

Agora uses a dual-database architecture for optimal performance.

### DATABASE\_URL

<ParamField path="DATABASE_URL" type="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**:

  ```bash theme={null}
  DATABASE_URL=postgres://user:password@host:5432/database
  ```

  **Fallback**: If not set, uses environment-specific URLs below
</ParamField>

### READ\_WRITE\_WEB2\_DATABASE\_URL\_PROD / READ\_WRITE\_WEB2\_DATABASE\_URL\_DEV

<ParamField path="READ_WRITE_WEB2_DATABASE_URL_*" type="string" required>
  Database for user-generated content (profiles, settings, delegate statements).

  **Example**:

  ```bash theme={null}
  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
</ParamField>

### READ\_ONLY\_WEB3\_DATABASE\_URL\_PROD / READ\_ONLY\_WEB3\_DATABASE\_URL\_DEV

<ParamField path="READ_ONLY_WEB3_DATABASE_URL_*" type="string" required>
  Database for blockchain indexed data.

  **Example**:

  ```bash theme={null}
  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)

  <Info>
    This separation allows for optimized querying of blockchain data without affecting user-generated content operations.
  </Info>
</ParamField>

## Authentication & Security

Critical security credentials for various features.

### GAS\_SPONSOR\_PK

<ParamField path="GAS_SPONSOR_PK" type="string">
  Private key for sponsoring gas fees in relay transactions.

  **Format**: Hex string without 0x prefix

  **Example**:

  ```bash theme={null}
  GAS_SPONSOR_PK=your_private_key_without_0x
  ```

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

  **Usage**: Enables users to delegate/vote without paying gas
</ParamField>

### EAS\_SENDER\_PRIVATE\_KEY

<ParamField path="EAS_SENDER_PRIVATE_KEY" type="string">
  Private key for Ethereum Attestation Service operations.

  **Example**:

  ```bash theme={null}
  EAS_SENDER_PRIVATE_KEY=your_eas_private_key
  ```

  <Warning>
    CRITICAL - Server-side only. Used for creating on-chain attestations for verified delegates.
  </Warning>
</ParamField>

### JWT\_SECRET

<ParamField path="JWT_SECRET" type="string" required>
  Secret for signing JWT tokens.

  **Example**:

  ```bash theme={null}
  JWT_SECRET=your_long_random_secret_at_least_32_characters
  ```

  <Warning>
    Must be strong and unique per environment. Minimum 32 characters recommended.
  </Warning>

  **Usage**: User session management and authentication
</ParamField>

## Network & RPC Configuration

### SERVERSIDE\_ALCHEMY\_ID\_PROD / SERVERSIDE\_ALCHEMY\_ID\_DEV

<ParamField path="SERVERSIDE_ALCHEMY_ID_*" type="string">
  Alchemy API keys for server-side blockchain RPC access.

  **Example**:

  ```bash theme={null}
  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
</ParamField>

### NEXT\_PUBLIC\_FORK\_NODE\_URL

<ParamField path="NEXT_PUBLIC_FORK_NODE_URL" type="string">
  Override RPC endpoint for development/testing.

  **Example**:

  ```bash theme={null}
  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
</ParamField>

### NEXT\_PUBLIC\_CONDUIT\_KEY

<ParamField path="NEXT_PUBLIC_CONDUIT_KEY" type="string">
  API key for Conduit RPC (Derive chain).

  **Example**:

  ```bash theme={null}
  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}`)
</ParamField>

### DAONODE\_URL\_TEMPLATE

<ParamField path="DAONODE_URL_TEMPLATE" type="string" required>
  Template for DAO-specific data endpoints.

  **Format**:

  ```bash theme={null}
  DAONODE_URL_TEMPLATE=https://{TENANT_NAMESPACE}.example.com/
  ```

  **Variables**: `{TENANT_NAMESPACE}` is replaced with instance name

  **Usage**: Fetches proposal details, voting data
</ParamField>

## External Services

### Tenderly (Transaction Simulation)

<ParamField path="TENDERLY_USER" type="string">
  Tenderly username for transaction simulation.
</ParamField>

<ParamField path="TENDERLY_PROJECT" type="string">
  Tenderly project name.
</ParamField>

<ParamField path="TENDERLY_ACCESS_KEY" type="string">
  Tenderly access key.

  **Example**:

  ```bash theme={null}
  TENDERLY_USER=your_username
  TENDERLY_PROJECT=your_project
  TENDERLY_ACCESS_KEY=your_access_key
  ```

  **Get credentials**: [Tenderly Dashboard](https://dashboard.tenderly.co/)

  **Usage**: Simulates proposal execution before voting

  <Info>
    All three variables must be set for simulation to work. Features disabled if missing.
  </Info>
</ParamField>

### Pinata (IPFS Storage)

<ParamField path="PINATA_JWT" type="string">
  Pinata JWT token (preferred method).
</ParamField>

<ParamField path="PINATA_API_KEY" type="string">
  Pinata API key (legacy).
</ParamField>

<ParamField path="PINATA_SECRET_API_KEY" type="string">
  Pinata secret API key (legacy).

  **Example**:

  ```bash theme={null}
  # 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](https://pinata.cloud/)

  **Usage**: Stores proposal descriptions and supporting documents on IPFS

  **Priority**: `PINATA_JWT` preferred over API key/secret pair
</ParamField>

### Etherscan

<ParamField path="NEXT_PUBLIC_ETHERSCAN_API_KEY" type="string">
  Etherscan API key for contract verification and ABI fetching.

  **Example**:

  ```bash theme={null}
  NEXT_PUBLIC_ETHERSCAN_API_KEY=your_etherscan_key
  ```

  **Usage**:

  * Fetches contract ABIs dynamically
  * Decodes transaction data
  * Verifies contract source code

  <Warning>
    Free tier has rate limits. Monitor usage to avoid hitting limits.
  </Warning>
</ParamField>

### GitHub PR Bot

<ParamField path="PR_BOT_TOKEN" type="string">
  GitHub token for creating pull requests.

  **Example**:

  ```bash theme={null}
  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
</ParamField>

## Deployment Configuration

### NEXT\_PUBLIC\_AGORA\_BASE\_URL

<ParamField path="NEXT_PUBLIC_AGORA_BASE_URL" type="string" required>
  Application base URL for metadata and API calls.

  **Format**: Full URL including protocol

  **Example**:

  ```bash theme={null}
  # 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
</ParamField>

### NEXT\_PUBLIC\_AGORA\_ROOT

<ParamField path="NEXT_PUBLIC_AGORA_ROOT" type="string">
  Application root path for subpath deployments.

  **Default**: `/`

  **Example**:

  ```bash theme={null}
  NEXT_PUBLIC_AGORA_ROOT=/governance
  ```

  **Use case**: Deploying under a subpath instead of root domain
</ParamField>

### NODE\_ENV

<ParamField path="NODE_ENV" type="string">
  Node.js environment mode (automatically set by Next.js).

  **Values**: `production`, `development`, `test`

  <Info>
    Automatically set by `next dev` (development) and `next build` (production). Do not set manually.
  </Info>

  **Impact**:

  * Production mode enables optimizations
  * Development mode enables hot reload
  * Controls Prisma client behavior and caching
</ParamField>

### Vercel Environment Variables

<Info>
  These variables are automatically set by Vercel. Do not set manually.
</Info>

<ParamField path="VERCEL_ENV" type="string">
  Deployment environment: `production`, `preview`, or `development`
</ParamField>

<ParamField path="VERCEL_REGION" type="string">
  Deployment region
</ParamField>

<ParamField path="VERCEL_GIT_COMMIT_SHA" type="string">
  Git commit SHA for the deployment
</ParamField>

<ParamField path="VERCEL_URL" type="string">
  Deployment URL
</ParamField>

**Usage**: OpenTelemetry tracing attributes for monitoring

## Feature Flags

Toggle optional features on or off.

### NEXT\_PUBLIC\_SIWE\_ENABLED

<ParamField path="NEXT_PUBLIC_SIWE_ENABLED" type="boolean">
  Enable Sign-In with Ethereum.

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

  **Example**:

  ```bash theme={null}
  NEXT_PUBLIC_SIWE_ENABLED=true
  ```

  **Default**: Disabled

  **Impact**: Allows wallet-based authentication
</ParamField>

### NEXT\_PUBLIC\_ENABLE\_BI\_METRICS\_CAPTURE

<ParamField path="NEXT_PUBLIC_ENABLE_BI_METRICS_CAPTURE" type="boolean">
  Enable analytics event tracking.

  **Values**: `"true"` to enable

  **Example**:

  ```bash theme={null}
  NEXT_PUBLIC_ENABLE_BI_METRICS_CAPTURE=true
  ```

  **Default**: Disabled

  **Related**: Requires `NEXT_PUBLIC_AGORA_API_KEY`

  **Impact**: Sends usage metrics to analytics endpoint
</ParamField>

### NEXT\_PUBLIC\_MUTE\_QUERY\_LOGGING

<ParamField path="NEXT_PUBLIC_MUTE_QUERY_LOGGING" type="boolean">
  Disable database query logging.

  **Values**: `"true"` to disable logging

  **Example**:

  ```bash theme={null}
  NEXT_PUBLIC_MUTE_QUERY_LOGGING=true
  ```

  **Default**: Logging enabled

  **Use case**: Reduce noise in development logs
</ParamField>

## Monitoring & Analytics

### DataDog

<ParamField path="DD_API_KEY" type="string">
  DataDog API key.
</ParamField>

<ParamField path="DD_APP_KEY" type="string">
  DataDog application key.
</ParamField>

<ParamField path="ENABLE_DD_METRICS" type="boolean">
  Toggle DataDog metrics collection.

  **Example**:

  ```bash theme={null}
  DD_API_KEY=your_dd_api_key
  DD_APP_KEY=your_dd_app_key
  ENABLE_DD_METRICS=true
  ```

  **Default**: Disabled

  <Info>
    Both DD keys must be set for this to work.
  </Info>

  **Usage**: Sends application metrics and alerts to DataDog
</ParamField>

## Advanced Features

### AWS Services

<ParamField path="AWS_ACCESS_KEY_ID" type="string">
  AWS access key ID.
</ParamField>

<ParamField path="AWS_SECRET_ACCESS_KEY" type="string">
  AWS secret access key.

  **Example**:

  ```bash theme={null}
  AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
  AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
  ```

  <Info>
    Use IAM roles in production when possible for better security.
  </Info>

  **Usage**:

  * DynamoDB access
  * S3 bucket operations
</ParamField>

### STORAGE\_BUCKET\_URL

<ParamField path="STORAGE_BUCKET_URL" type="string">
  Base URL for storage bucket.

  **Format**: Full URL with trailing slash

  **Example**:

  ```bash theme={null}
  STORAGE_BUCKET_URL=https://my-bucket.s3.amazonaws.com/
  ```

  **Usage**: Fetches contract ABIs from backup storage
</ParamField>

### Smart Accounts

<ParamField path="NEXT_PUBLIC_ALCHEMY_SMART_ACCOUNT" type="string">
  Alchemy API key for smart account features.

  **Example**:

  ```bash theme={null}
  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
</ParamField>

<ParamField path="PAYMASTER_SECRET" type="string">
  Secret for paymaster service integration.

  **Usage**: Enables sponsored transactions
</ParamField>

## Environment Setup Examples

### Minimum Required for Development

```bash theme={null}
# 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

```bash theme={null}
# 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

<Warning>
  Follow these security guidelines to protect your deployment:
</Warning>

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

<CardGroup cols={2}>
  <Card title="Setup Guide" icon="rocket" href="/guides/setup">
    Complete initial setup with these environment variables
  </Card>

  <Card title="Deployment" icon="cloud" href="/guides/deployment">
    Deploy to production with proper configuration
  </Card>

  <Card title="Customization" icon="palette" href="/guides/customization">
    Customize your tenant configuration
  </Card>

  <Card title="Architecture" icon="sitemap" href="/architecture">
    Understand the system architecture
  </Card>
</CardGroup>