Skip to main content

​
Environment Variables Overview

Echoes of the Past requires several environment variables to function properly. These variables configure integrations with Supabase, Vapi AI, ElevenLabs, OpenAI, and Redis.
Never commit environment variables to version control. Create a .env.local file in the project root and add it to .gitignore.

​
Create Environment File

Create a .env.local file in the root of your project: 
touch .env.local

​
Required Environment Variables

​
Supabase Configuration

Supabase is used for database, authentication, and file storage.
.env.local
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
1

Create a Supabase Project

  1. Go to supabase.com and sign in
  2. Click “New Project” and fill in the details
  3. Wait for the project to be provisioned
2

Get API Credentials

  1. Navigate to Settings > API
  2. Copy the Project URL (this is your NEXT_PUBLIC_SUPABASE_URL)
  3. Copy the anon/public key (this is your NEXT_PUBLIC_SUPABASE_ANON_KEY)
The project is currently configured to use project ID fmknwbbacrndtinyyhiw for type generation. You can update this in package.json under the gen-types script.

​
Vapi AI Configuration

Vapi AI powers the voice conversation functionality.
.env.local
NEXT_PUBLIC_VAPI_WEB_TOKEN=your-vapi-web-token
1

Sign Up for Vapi AI

  1. Visit vapi.ai and create an account
  2. Complete the onboarding process
2

Get Web Token

  1. Navigate to Dashboard > API Keys
  2. Create a new Web Token
  3. Copy the token to your .env.local file
This variable is required and the application will throw an error if it’s not set (see lib/vapi.ts:3).

​
ElevenLabs Configuration

ElevenLabs provides text-to-speech functionality for historical figure voices.
.env.local
ELEVEN_LABS_API_KEY=your-elevenlabs-api-key
1

Create ElevenLabs Account

  1. Go to elevenlabs.io and sign up
  2. Choose a plan (free tier available)
2

Generate API Key

  1. Navigate to Profile > API Keys
  2. Click “Generate New API Key”
  3. Copy the key to your .env.local file

​
OpenAI Configuration

OpenAI is used for AI-powered conversation and content generation.
.env.local
OPENAI_API_KEY=sk-your-openai-api-key
1

Get OpenAI API Key

  1. Visit platform.openai.com
  2. Sign in or create an account
  3. Navigate to API Keys section
  4. Click “Create new secret key”
  5. Copy the key immediately (it won’t be shown again)
This variable is required and the application will throw an error if it’s not set (see lib/ai.ts:3).

​
Upstash Redis Configuration

Redis is used for rate limiting and caching.
.env.local
UPSTASH_REDIS_REST_URL=https://your-redis-url.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-redis-token
1

Create Upstash Database

  1. Go to upstash.com and sign in
  2. Click “Create Database”
  3. Choose a name and region
  4. Select the free tier
2

Get Redis Credentials

  1. Open your database dashboard
  2. Scroll to REST API section
  3. Copy UPSTASH_REDIS_REST_URL
  4. Copy UPSTASH_REDIS_REST_TOKEN
Both variables are required and the application will throw an error if either is missing (see lib/redis.ts:3).

​
Application URL Configuration

These variables configure URLs for authentication callbacks and webhooks.
.env.local
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_SERVER_URL=http://localhost:3000
  • NEXT_PUBLIC_APP_URL: Used for OAuth redirects (see features/auth/components/sign-in-google-btn.tsx:21)
  • NEXT_PUBLIC_SERVER_URL: Used for webhook URLs (see features/call/hooks/useVapi.ts:57)
In production, update these to your deployed URL (e.g., https://your-app.vercel.app).

​
Optional: Vercel Configuration

When deploying to Vercel, this variable is automatically set:
.env.local
VERCEL_URL=your-deployment-url.vercel.app
The application uses this for metadata configuration (see config/metadata.ts:5).

​
Complete Environment File Example

Here’s a complete .env.local template:
.env.local
# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# Vapi AI
NEXT_PUBLIC_VAPI_WEB_TOKEN=your-vapi-web-token

# ElevenLabs
ELEVEN_LABS_API_KEY=your-elevenlabs-api-key

# OpenAI
OPENAI_API_KEY=sk-your-openai-api-key

# Upstash Redis
UPSTASH_REDIS_REST_URL=https://your-redis-url.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-redis-token

# Application URLs
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_SERVER_URL=http://localhost:3000

# Node Environment
NODE_ENV=development

​
Validating Your Configuration

After setting up your environment variables, verify they’re loaded correctly:
  1. Start the development server: 
    npm run dev
  2. Check for any error messages in the console. The application validates required environment variables at startup:
    • lib/vapi.ts checks for NEXT_PUBLIC_VAPI_WEB_TOKEN
    • lib/ai.ts checks for OPENAI_API_KEY
    • lib/redis.ts checks for Redis credentials
    • next.config.ts checks for NEXT_PUBLIC_SUPABASE_URL
  3. If all variables are set correctly, you should see: 
    ✓ Ready in 1.2s

​
Environment-Specific Configuration

​
Development

Use NODE_ENV=development for local development. This enables:
  • Detailed error messages
  • React Query DevTools
  • Hot module replacement

​
Production

For production deployments:
  1. Set NODE_ENV=production
  2. Update URLs to production domains
  3. Enable analytics (see app/layout.tsx:43)
  4. Use production API keys (not test keys)

​
Next Steps

Once your environment is configured:
1

Set Up Database

Configure your Supabase database and run migrations. See Database Setup.
2

Test the Application

Start the development server and verify all integrations work correctly.

​
Troubleshooting

​
Environment Variables Not Loading

If your environment variables aren’t being recognized:
  1. Ensure the file is named exactly .env.local
  2. Restart your development server
  3. Check for typos in variable names
  4. Verify the file is in the project root

​
CORS Errors with Supabase

If you encounter CORS errors:
  1. Verify your NEXT_PUBLIC_APP_URL matches your development URL
  2. Check Supabase dashboard Authentication > URL Configuration
  3. Add http://localhost:3000 to allowed redirect URLs

​
API Rate Limits

During development:
  • OpenAI and ElevenLabs have rate limits on free tiers
  • Consider using test/development API keys
  • Redis caching helps reduce API calls

Build docs developers (and LLMs) love

Get started for freeTalk to us