Skip to main content

​
Overview

This guide will walk you through setting up Agora locally, configuring your DAO instance, and creating your first governance proposal. You’ll have a fully functional governance platform running in under 15 minutes.
This guide assumes you have basic familiarity with Next.js, TypeScript, and PostgreSQL. You’ll also need Node.js 18+ and npm installed.

​
Prerequisites

Before you begin, ensure you have:
1

Development tools

  • Node.js 18+ and npm installed
  • Git for cloning the repository
  • PostgreSQL database (local or remote)
  • Code editor (VS Code recommended)
2

API keys and accounts

  • Alchemy API key for blockchain RPC access (Get one free)
  • WalletConnect Project ID (Create project)
  • Database connection strings for PostgreSQL
3

Optional services

  • Pinata credentials for IPFS storage (optional)
  • Tenderly account for transaction simulation (optional)
  • Etherscan API key for contract verification (optional)

​
Step 1: Clone and Install

First, clone the Agora repository and install dependencies: 
# Clone the repository
git clone https://github.com/voteagora/agora-next.git
cd agora-next

# Install dependencies
npm install
The installation process will also generate TypeChain types and Prisma client automatically.

​
Step 2: Configure Environment Variables

Create a .env.local file in the project root. You can start by copying the sample file: 
cp env.sample .env.local
Now configure the essential environment variables:

​
Core Configuration

These variables are required for Agora to run:
.env.local
# DAO Configuration
NEXT_PUBLIC_AGORA_INSTANCE_NAME=ens
NEXT_PUBLIC_AGORA_INSTANCE_TOKEN=ENS
NEXT_PUBLIC_AGORA_ENV=dev

# Base URL
NEXT_PUBLIC_AGORA_BASE_URL=http://localhost:3000/api/v1
NEXT_PUBLIC_AGORA_INSTANCE_NAME must match one of the configured tenants: ens, optimism, uniswap, derive, cyber, xai, boost, scroll, linea, etherfi, b3, or protocol-guild.

​
Blockchain RPC Configuration

Add your Alchemy API keys for blockchain access:
.env.local
# Client-side RPC (browser)
NEXT_PUBLIC_ALCHEMY_ID=your_alchemy_api_key

# Server-side RPC (recommended for better security)
SERVERSIDE_ALCHEMY_ID_DEV=your_dev_alchemy_key
SERVERSIDE_ALCHEMY_ID_PROD=your_prod_alchemy_key
Use separate Alchemy keys for client and server to prevent leaked keys from affecting server operations. Domain-whitelist the client key in your Alchemy dashboard.

​
Database Configuration

Configure PostgreSQL connection strings:
.env.local
# Simple approach: Single database URL
DATABASE_URL=postgres://user:password@localhost:5432/agora_dev

# Advanced: Separate read/write databases
READ_WRITE_WEB2_DATABASE_URL_DEV=postgres://user:password@localhost:5432/agora_web2_dev
READ_ONLY_WEB3_DATABASE_URL_DEV=postgres://user:password@localhost:5432/agora_web3_dev
Agora uses a dual-database pattern:
  • WEB2 Database: User-generated content (profiles, settings, forum posts)
  • WEB3 Database: Blockchain-indexed data (proposals, votes, delegates)
For local development, you can use the same database for both.

​
Wallet Connection

Add your WalletConnect Project ID:
.env.local
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_walletconnect_project_id

​
Authentication

Generate a JWT secret for user sessions:
.env.local
JWT_SECRET=your-secure-random-string-at-least-32-characters
Generate a secure JWT secret with: openssl rand -base64 32

​
Step 3: Set Up the Database

Agora uses Prisma as its ORM. Pull the latest schema and generate the Prisma client: 
# Pull the latest database schema
npx prisma db pull

# Generate Prisma client
npx prisma generate
The database schema is managed in a separate repository. You’ll need access to a pre-configured Agora database or set up your own using the queries repository.

​
Database Structure

Agora uses a multi-schema PostgreSQL database:
  • agora: Shared cross-tenant data
  • config: Configuration and contracts
  • [dao-namespace]: DAO-specific data (e.g., ens, optimism, uniswap)
Each DAO tenant has its own schema with tables for proposals, votes, delegates, and more.

​
Step 4: Start the Development Server

Now you’re ready to run Agora locally: 
npm run dev
This command will:
  1. Generate TypeChain types from contract ABIs
  2. Generate the Prisma client
  3. Start the Next.js development server on http://localhost:3000
The development server supports hot reload. Changes to your code will automatically refresh the browser.
Open http://localhost:3000 in your browser. You should see the Agora governance interface for your configured DAO.

​
Step 5: Connect Your Wallet

To interact with Agora, you’ll need to connect a wallet:
1

Click Connect Wallet

Click the Connect Wallet button in the top-right corner.
2

Choose your wallet

Select from supported wallets: MetaMask, WalletConnect, Coinbase Wallet, etc.
3

Approve the connection

Approve the connection request in your wallet.
4

Sign in (optional)

If SIWE (Sign-In with Ethereum) is enabled, sign a message to authenticate.
For testing, make sure your wallet is connected to the correct network for your DAO (Mainnet for ENS, Optimism for OP, etc.).

​
Step 6: Create Your First Proposal

Now let’s create a governance proposal:

​
Option A: Using the UI

If your tenant has the easv2-govlessvoting feature enabled:
1

Navigate to Create

Go to /create in your browser or click Create Proposal in the navigation.
2

Choose proposal type

Select between:
  • Temp Check: Off-chain temperature check via Snapshot or EAS
  • Gov Proposal: Full onchain governance proposal
3

Fill in details

Enter proposal information:
  • Title: Clear, descriptive title
  • Description: Detailed proposal body (supports markdown)
  • Proposal Type: Standard, approval voting, etc.
  • Voting Period: Start and end times
4

Add transactions (onchain only)

For onchain proposals, add executable transactions:
  • Target contract addresses
  • Function calls and parameters
  • ETH values (if sending funds)
5

Submit

Review and submit your proposal. You’ll need to sign a transaction or message.

​
Option B: Using the API

Create a proposal programmatically: 
const response = await fetch('http://localhost:3000/api/v1/proposals', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  },
  body: JSON.stringify({
    title: 'Treasury Allocation for Q2 Development',
    description: `## Summary\n\nThis proposal allocates 100,000 tokens from the treasury for Q2 development work.\n\n## Details\n\n- Team expansion: 50,000 tokens\n- Infrastructure: 30,000 tokens\n- Marketing: 20,000 tokens`,
    targets: [treasuryContractAddress],
    values: ['0'],
    calldatas: [encodedTransferCalldata],
    proposalType: 'standard'
  })
});

const proposal = await response.json();
console.log('Proposal created:', proposal.id);
API authentication requires an API key. Generate one using the CLI: npm run generate-apikey -- --email [email protected] --address 0x... --chain-id 1 --description "API access"

​
Step 7: Vote on a Proposal

Once a proposal is active, you can vote:

​
Using the UI

1

Navigate to proposal

Go to /proposals/[proposal-id] or click on a proposal from the list.
2

Review details

Read the proposal description, transactions, and current vote counts.
3

Cast your vote

Click For, Against, or Abstain and confirm the transaction.
4

Add a reason (optional)

Include a text explanation for your vote.

​
Using the API

const response = await fetch(`http://localhost:3000/api/v1/proposals/${proposalId}/vote`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  },
  body: JSON.stringify({
    support: 1, // 0 = Against, 1 = For, 2 = Abstain
    reason: 'I support this allocation for team growth'
  })
});
If gasless voting is enabled, votes are submitted as signed messages instead of onchain transactions, saving gas fees.

​
Step 8: Explore Delegation

Delegation allows token holders to delegate their voting power to trusted representatives:

​
Delegate Your Voting Power

1

Navigate to delegates

Go to /delegates to see the list of delegates.
2

Find a delegate

Browse delegate profiles, statements, and voting history.
3

Delegate

Click Delegate on a delegate’s profile and confirm the transaction.

​
Create a Delegate Profile

To become a delegate:
1

Go to delegate creation

Navigate to /delegates/create.
2

Fill in your statement

Add information about yourself:
  • Bio and governance philosophy
  • Social links (Twitter, Discord, Warpcast)
  • Email for notifications (optional)
3

Submit

Sign and submit your delegate statement.

​
Next Steps

Congratulations! You now have Agora running locally and understand the core workflows. Here’s what to explore next:

Architecture Deep Dive

Learn about Agora’s system design, multi-tenant architecture, and database schema.

Configuration Guide

Explore all environment variables and advanced configuration options.

Deployment Guide

Deploy Agora to production on Vercel or your own infrastructure.

API Reference

Comprehensive API documentation for building integrations.

​
Troubleshooting

​
Database Connection Issues

Cause: PostgreSQL is not running or connection string is incorrect.Solution:
  1. Verify PostgreSQL is running: pg_isready
  2. Check connection string format: postgres://user:password@host:port/database
  3. Ensure database exists: createdb agora_dev
Cause: Database schema hasn’t been created for your tenant.Solution: Run migrations from the queries repository to create the required schemas.

​
RPC and Blockchain Issues

Cause: Invalid or rate-limited Alchemy API key.Solution:
  1. Verify your Alchemy API key is correct
  2. Check Alchemy dashboard for rate limit status
  3. Use separate keys for client and server
Cause: Wallet connected to incorrect network.Solution: Switch your wallet to the correct network for your tenant (Mainnet for ENS, Optimism for OP, etc.).

​
Build and Runtime Errors

Solution:
  1. Regenerate types: npm run generate-typechain
  2. Regenerate Prisma client: npx prisma generate
  3. Check TypeScript: npm run typecheck
Solution: Ensure .env.local is in the project root and contains all required variables. Restart the dev server after changes.
For additional help, join the Discord community or open an issue on GitHub.

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us