📚

Documentation

Everything you need to set up your own voice-enabled AI companion

Your Own AI Companion

This repo contains everything you need to run your own voice-enabled, personalized AI companion. It includes a Next.js frontend and a FastAPI backend, with optional support for memory and login features.

What‘s Inside

📱frontend/

The Next.js interface where you talk to your AI companion.

⚙️backend/

The FastAPI service that handles AI logic, voice, and orchestration.

🔧user_config

A user_config.json file to customize your AI.

1Prerequisites

  • OpenAI API key

    Get one here

  • GitHub account

    Required to clone the repository

2Customize Your Companion

Edit user_config.json to define your AI:

{ "name": "Mira", "persona_prompt": "You are a compassionate journal companion...", "voice": "nova", "memory_enabled": false📚 }

3Deploy the Backend (Render)

  1. Go to render.com and click "New +" → Web Service
  2. Connect your GitHub repo and select the ai-companion repository
  3. In the settings:
    • Root Directory: backend
    • Environment: Python
    • Build Command: pip install -r requirements.txt
    • Start Command: uvicorn main:app --host 0.0.0.0 --port 10000
  4. Add environment variable:
    OPENAI_API_KEY=your_openai_key_here
  5. Click "Deploy"
  6. Copy your backend URL (e.g. https://ai-backend.onrender.com)

4Deploy the Frontend (Vercel)

  1. Go to vercel.com and add a new project
  2. Connect the same GitHub repo (ai-companion)
  3. In the project settings:
    • Root Directory: frontend
    • Framework: Next.js
  4. Add environment variable:
    NEXT_PUBLIC_BACKEND_URL=https://ai-backend.onrender.com
  5. Click "Deploy"

Your frontend will now be live at something like https://your-companion.vercel.app

5Talk to Your AI

  1. Visit your frontend Vercel URL
  2. Press and hold the mic button
  3. Start talking to your AI companion

Troubleshooting

My frontend can't connect to the backend.

  • Double check that NEXT_PUBLIC_BACKEND_URL in .env.local points to the correct Render URL
  • Make sure your backend is live and accessible (check Render logs)

I'm getting a 401 or OpenAI error.

  • Make sure you added your OPENAI_API_KEY correctly in Render
  • Ensure the key has access to GPT models (like gpt-4o)

Voice isn't working.

  • Check your browser permissions for microphone access
  • Make sure you're pressing and holding the mic button

My deployment fails on Render.

  • Confirm you set the root directory to backend

  • Use uvicorn main:app --host 0.0.0.0 --port 10000 as your start command

Still stuck?

Try Knolia, a voice-enabled AI companion built from this toolkit