Skip to content

Configuration

Jump to bottom
root edited this page Dec 9, 2025 · 3 revisions

Configuration

Complete guide to configuring Luna Chat.

Environment Variables

Core Settings

Variable Description Default
NODE_ENV Environment mode production
PORT API server port 3005
LOG_LEVEL Logging level info

Database

Variable Description Example
DATABASE_URL PostgreSQL connection postgresql://user:pass@host:5432/luna
POSTGRES_HOST Database host luna-postgres
POSTGRES_PORT Database port 5432
POSTGRES_DB Database name luna
POSTGRES_USER Database user luna

Redis

Variable Description Example
REDIS_URL Redis connection redis://:password@host:6379
REDIS_HOST Redis host luna-redis
REDIS_PORT Redis port 6379

Security

Variable Description Notes
JWT_SECRET JWT signing key Min 32 chars
ENCRYPTION_KEY Token encryption 32 chars
CORS_ORIGINS Allowed origins Comma-separated

External Services

Variable Description Required
OLLAMA_HOST Ollama URL For embeddings
SEARXNG_URL Search engine For web search
MEMORYCORE_URL MemoryCore URL Optional

API Keys

Variable Provider
OPENAI_API_KEY OpenAI
ANTHROPIC_API_KEY Anthropic
GROQ_API_KEY Groq
GOOGLE_API_KEY Google AI
XAI_API_KEY xAI
OPENROUTER_API_KEY OpenRouter
ELEVENLABS_API_KEY ElevenLabs

Docker Secrets

For production, use Docker secrets instead of environment variables:

Creating Secrets

mkdir -p secrets

# Database
echo "your-postgres-password" > secrets/postgres_password.txt

# Security
echo "your-jwt-secret-min-32-chars" > secrets/jwt_secret.txt
echo "your-redis-password" > secrets/redis_password.txt
echo "your-32-character-encryption-key" > secrets/encryption_key.txt

# API Keys (optional)
echo "sk-your-openai-key" > secrets/openai_api_key.txt
echo "sk-ant-your-anthropic-key" > secrets/anthropic_api_key.txt
echo "gsk_your-groq-key" > secrets/groq_api_key.txt

Docker Compose Reference

secrets:
  postgres_password:
    file: ./secrets/postgres_password.txt
  jwt_secret:
    file: ./secrets/jwt_secret.txt

services:
  luna-api:
    secrets:
      - postgres_password
      - jwt_secret

Model Configuration

Configure which models to use for different tasks.

Settings Location

Web UI: Settings > Models

Configurable Tasks

Task Purpose Default
main Primary chat gpt-5.1
council Council deliberation llama-3.3-70b
researcher Research agent claude-sonnet-4
coder Coding agent claude-sonnet-4
writer Writing agent gpt-5.1
analyst Analysis agent llama-3.3-70b
planner Planning agent gpt-5.1
friends Friend discussions llama3.2:3b
embeddings Vector embeddings bge-m3

Configuration Format

{
  "main": {
    "provider": "openai",
    "model": "gpt-5.1"
  },
  "council": {
    "provider": "groq",
    "model": "llama-3.3-70b-versatile"
  },
  "embeddings": {
    "provider": "ollama",
    "model": "bge-m3"
  }
}

Provider Options

Provider Value
OpenAI openai
Anthropic anthropic
Groq groq
Google google
xAI xai
OpenRouter openrouter
Ollama ollama

Autonomous Configuration

Configure autonomous mode behavior.

Settings Location

Web UI: Autonomous > Settings

Options

Setting Description Default
enabled Enable autonomous mode false
autoStart Auto-start sessions false
sessionInterval Minutes between sessions 60
maxDailySessions Max sessions per day 10
idleTimeout Session timeout (minutes) 30

API Configuration

PUT /api/autonomous/config
{
  "enabled": true,
  "autoStart": false,
  "sessionInterval": 60,
  "maxDailySessions": 10,
  "idleTimeout": 30
}

User Preferences

Per-user settings stored in database.

Settings Location

Web UI: Settings > Appearance (and other tabs)

Categories

Category Settings
Appearance Theme, CRT effects
Models Per-task model config
Persona Custom prompts
Memory Fact extraction settings

API Access

GET /api/settings
PUT /api/settings
{
  "theme": "dark",
  "crtFlicker": false,
  "models": { ... }
}

Calendar Configuration

CalDAV (Self-hosted)

Luna includes Radicale CalDAV server:

Setting Value
URL http://luna-radicale:5232
Username Set in Radicale config
Password Set in Radicale config

OAuth (Google/Microsoft)

  1. Create OAuth app in provider console
  2. Set redirect URI: https://your-domain/api/integrations/oauth/callback
  3. Add credentials to secrets

Email Configuration

Local SMTP/IMAP

SMTP_HOST=mail.example.com
SMTP_PORT=587
SMTP_USER=luna@example.com
SMTP_PASS=password
IMAP_HOST=mail.example.com
IMAP_PORT=993

OAuth (Gmail/Outlook)

  1. Create OAuth app
  2. Enable Gmail/Outlook API
  3. Add credentials to secrets

Search Configuration

SearXNG

SEARXNG_URL=http://searxng:8080

Self-hosted SearXNG

# docker-compose.yml addition
searxng:
  image: searxng/searxng
  ports:
    - "8080:8080"

TTS Configuration

Luna supports two TTS providers for Voice mode.

ElevenLabs (Recommended)

Best for emotion expression with full tag support ([laughs], [sighs], etc.)

echo "your-elevenlabs-key" > secrets/elevenlabs_api_key.txt

Environment variables:

Variable Description Default
ELEVENLABS_ENABLED Enable ElevenLabs true
ELEVENLABS_VOICE_ID Voice ID (Luna's voice)
ELEVENLABS_MODEL Model version eleven_v3

OpenAI TTS

Cost-effective alternative with good quality.

Uses your existing OpenAI API key.

Voice Settings

Configure in Settings > Models:

{
  "tts": {
    "provider": "elevenlabs",
    "voice": "voice-id",
    "model": "eleven_v3"
  }
}

Or for OpenAI:

{
  "tts": {
    "provider": "openai",
    "voice": "nova",
    "model": "tts-1-hd"
  }
}

OpenAI Voice Options

Voice Style
alloy Neutral
echo Male
fable Expressive
onyx Deep male
nova Female (recommended)
shimmer Soft female

Rate Limiting

Configure per-endpoint rate limits:

Environment Variables

RATE_LIMIT_CHAT=60
RATE_LIMIT_TTS=10
RATE_LIMIT_AUTH=10

Defaults

Endpoint Limit/min
Chat 60
TTS 10
Auth 10
Abilities 100

Logging

Log Levels

Level Description
error Errors only
warn Warnings and above
info General info (default)
debug Debug information

Configuration

LOG_LEVEL=info

File Storage

Workspace Location

WORKSPACE_DIR=/data/workspace

Document Storage

DOCUMENTS_DIR=/data/documents

Default Paths (Docker)

Type Path
Workspace /app/data/workspace
Documents /app/data/documents
Uploads /app/data/uploads

Database Configuration

Connection Pool

DB_POOL_MIN=2
DB_POOL_MAX=10

Migrations

# Run migrations
npm run migrate

# Create migration
npm run migrate:create migration_name

Complete Example

.env file

# Environment
NODE_ENV=production
PORT=3005
LOG_LEVEL=info

# Database
DATABASE_URL=postgresql://luna:password@luna-postgres:5432/luna

# Redis
REDIS_URL=redis://:password@luna-redis:6379

# Ollama
OLLAMA_HOST=http://luna-ollama:11434

# Search (optional)
SEARXNG_URL=http://searxng:8080

# Rate limits
RATE_LIMIT_CHAT=60
RATE_LIMIT_TTS=10

secrets/ directory

secrets/
├── postgres_password.txt
├── jwt_secret.txt
├── redis_password.txt
├── encryption_key.txt
├── openai_api_key.txt
├── anthropic_api_key.txt
├── elevenlabs_api_key.txt
├── spotify_client_id.txt
└── spotify_client_secret.txt

Spotify Configuration

OAuth Setup

Luna uses direct Spotify OAuth for music control.

  1. Create a Spotify Developer App at https://developer.spotify.com/dashboard
  2. Add redirect URI: https://your-domain/api/abilities/spotify/callback
  3. Copy Client ID and Client Secret to secrets files

Secrets

echo "your-spotify-client-id" > secrets/spotify_client_id.txt
echo "your-spotify-client-secret" > secrets/spotify_client_secret.txt

Environment Variables

Variable Description Default
SPOTIFY_ENABLED Enable Spotify integration true

User Authentication

Users connect their Spotify accounts via:

  1. Go to Settings > Integrations
  2. Click Connect Spotify
  3. Authorize in Spotify popup
  4. Luna stores encrypted OAuth tokens per user

Requirements

  • Spotify Premium account (for playback control)
  • Active Spotify device

Clone this wiki locally