Configuration

🔐 Configuration

All configuration is done through environment variables. Copy .env.example to .env and fill in your values.

Environment Variables

VariableRequiredDescription
DATABASE_URL✅PostgreSQL connection string
CLERK_SECRET_KEY✅Clerk backend secret key
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY✅Clerk frontend publishable key
GROQ_API_KEY⭐Groq API key — free, ultra-fast inference (recommended)
MISTRAL_API_KEY⚡Mistral AI API key (fallback if Groq not set)
OLLAMA_URL⚡Ollama endpoint (default: http://localhost:11434)
NEXT_PUBLIC_API_URL⚡Backend URL for the frontend (default: http://localhost:8000)

You only need one LLM provider key. Groq is recommended — it’s completely free with generous rate limits.

LLM Provider Setup

1️⃣ Groq (Recommended — Free)

Groq provides free, ultra-fast LLM inference with no credit card required.

  1. Sign up at console.groq.com
  2. Go to API Keys → Create API Key
  3. Add to your .env:
GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxx

Available models:

ModelTierSpeed
llama-3.1-8b-instantLight~800 tok/s
llama-3.3-70b-versatileHeavy~250 tok/s
gemma2-9b-itLight (alt)~500 tok/s

2️⃣ Mistral AI (Paid fallback)

If GROQ_API_KEY is not set, IntentScope falls back to Mistral.

  1. Sign up at console.mistral.ai
  2. Go to API Keys → Create new key
  3. Add to your .env:
MISTRAL_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxx

3️⃣ Ollama (Local — no key needed)

If neither Groq nor Mistral keys are set, IntentScope falls back to a local Ollama instance.

# Start Ollama via Docker
docker compose up -d
 
# Pull the model
docker exec intentscope-ollama ollama pull llama3.2
OLLAMA_URL=http://localhost:11434
⚠️

Ollama cannot run on cloud platforms like Render. Use it for local development only.

Clerk Auth Setup

IntentScope uses Clerk for user authentication.

  1. Create a project at dashboard.clerk.com
  2. Go to API Keys
  3. Copy both keys to your .env:
CLERK_SECRET_KEY=sk_test_...
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...

Also add to frontend/.env.local:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_API_URL=http://localhost:8000

Database

IntentScope uses PostgreSQL via SQLAlchemy async + Alembic migrations.

Local (Docker):

DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5434/intentscope

Production (Neon):

DATABASE_URL=postgresql+asyncpg://user:password@host/dbname?sslmode=require

After setting the URL, run migrations:

cd backend-python
alembic upgrade head
ArchitectureModel Routing