Skip to main content

Quick Start

Get SmarterAvatar running in minutes with our interactive setup wizard.

Prerequisites​

Before you begin, ensure you have:

  • Node.js 18+ (we recommend Node.js 20)
  • pnpm package manager (npm install -g pnpm)
  • PostgreSQL database (local or cloud)

The setup wizard guides you through configuration step-by-step:

# Clone the repository
git clone https://github.com/fictiontribe/smarteravatar.git
cd smarteravatar

# Install dependencies
pnpm install

# Run the setup wizard
pnpm setup-wizard

The wizard will help you:

  1. Configure your database connection
  2. Select and configure LLM provider (Gemini, OpenAI, or Anthropic)
  3. Select and configure STT provider (Whisper or Deepgram)
  4. Configure HeyGen avatar settings
  5. Set up branding (optional)

After setup:

# Initialize the database
pnpm db:setup

# Start development server
pnpm dev

Visit http://localhost:3000 to see your avatar!

Option 2: Manual Configuration​

1. Clone and Install​

git clone https://github.com/fictiontribe/smarteravatar.git
cd smarteravatar
pnpm install

2. Configure Environment Variables​

Copy the example environment file:

cp .env.example .env

Edit .env with your configuration:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/smarteravatar"

# LLM Provider (choose one)
LLM_PROVIDER=gemini
GEMINI_API_KEY=your-gemini-api-key

# STT Provider (choose one)
STT_PROVIDER=whisper
OPENAI_API_KEY=your-openai-api-key

# Avatar Provider
LIVEAVATAR_API_KEY=your-heygen-api-key
NEXT_PUBLIC_AVATAR_ID=your-avatar-id
NEXT_PUBLIC_VOICE_ID=your-voice-id

3. Set Up Database​

# Generate Prisma client
pnpm db:generate

# Run migrations
pnpm db:migrate

# (Optional) Seed with sample data
pnpm db:seed

4. Start Development Server​

pnpm dev

Verify Your Setup​

After starting the server, you should see:

  1. Home page at http://localhost:3000 - The avatar interface
  2. Admin panel at http://localhost:3000/admin-analytics - Configuration and analytics

Test the Avatar​

  1. Click "Start Session" on the home page
  2. Type a question in the text input
  3. The avatar should respond with synthesized speech

Troubleshooting​

If the avatar doesn't respond:

  1. Check API keys - Ensure all provider API keys are valid
  2. Check console - Look for errors in browser developer tools
  3. Check server logs - Look for errors in the terminal running pnpm dev
  4. Verify database - Run pnpm db:studio to inspect your database

Next Steps​