Skip to content

Configuration

Jump to bottom
Judah Paul edited this page Sep 13, 2026 · 19 revisions

⚙️ Configuration

This page documents all configuration options for GPT Home, including environment variables, settings files, and runtime options.

Configuration Hierarchy

┌────────────────────────────────────────────────────────────┐
│                  Configuration Sources                     │
├────────────────────────────────────────────────────────────┤
│                                                            │
│   Priority (highest to lowest):                            │
│                                                            │
│   1. Environment Variables (.env)                          │
│      └─ API keys, database URLs, secrets                   │
│                                                            │
│   2. settings.json                                         │
│      └─ Model settings, UI preferences                     │
│                                                            │
│   3. Default Values (code)                                 │
│      └─ Fallback configurations                            │
│                                                            │
└────────────────────────────────────────────────────────────┘

Environment Variables (.env)

The .env file in the project root contains sensitive configuration:

Core Configuration

Variable Required Default Description
LITELLM_API_KEY Yes - API key for your LLM provider
MODEL No gpt-4o-mini LLM model to use
SPOTIFY_BROKER_URL No https://gpt-home.judahpaul.com Origin of the Spotify OAuth broker
DATABASE_URL No PostgreSQL in docker compose PostgreSQL connection string

Database Configuration

Variable Required Default Description
POSTGRES_DB No gpt_home PostgreSQL database name
POSTGRES_USER No gpt_home PostgreSQL username
POSTGRES_PASSWORD No gpt_home_secret PostgreSQL password

Embedding Configuration

Variable Required Default Description
EMBEDDING_MODEL No openai:text-embedding-3-small Model for vector embeddings (format: provider:model)
EMBEDDING_DIMS No 1536 Embedding vector dimensions

Integration API Keys

Integration credentials are entered on the web UI's Integrations page and stored in the integrations table, which is what the tools read. The environment variables below are a fallback for headless setups.

Variable Required Description
OPEN_WEATHER_API_KEY Optional OpenWeatherMap API key
DEFAULT_LOCATION Optional Fallback location for weather
PHILIPS_HUE_BRIDGE_IP For Hue Philips Hue bridge IP address
PHILIPS_HUE_USERNAME For Hue Hue bridge API username
CALDAV_URL For Calendar CalDAV server URL
CALDAV_USERNAME For Calendar CalDAV username
CALDAV_PASSWORD For Calendar CalDAV password

LangSmith Tracing (Optional)

Variable Required Description
LANGCHAIN_TRACING_V2 No Set to true to enable
LANGCHAIN_API_KEY If tracing LangSmith API key
LANGCHAIN_PROJECT If tracing Project name in LangSmith
LANGCHAIN_ENDPOINT If tracing https://api.smith.langchain.com

Example .env File

# Required
LITELLM_API_KEY=sk-your-api-key-here

# Optional - Override defaults
MODEL=gpt-4o-mini

# Database (usually set by docker compose)
POSTGRES_DB=gpt_home
POSTGRES_USER=gpt_home
POSTGRES_PASSWORD=your-secure-password

# Integrations
OPEN_WEATHER_API_KEY=your-openweather-key
PHILIPS_HUE_BRIDGE_IP=192.168.1.100
PHILIPS_HUE_USERNAME=your-hue-username
CALDAV_URL=https://caldav.example.com/dav/
CALDAV_USERNAME=your-caldav-user
CALDAV_PASSWORD=your-caldav-password

# LangSmith Tracing (optional)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=lsv2_...
LANGCHAIN_PROJECT=gpt-home

Settings

Runtime configuration stored in the PostgreSQL database (app_settings table). A local settings.json file exists as fallback. Editable via the web interface:

{
  "keyword": "computer",
  "model": "gpt-4o-mini",
  "embedding_model": "openai:text-embedding-3-small",
  "max_tokens": 1024,
  "temperature": 0.7,
  "custom_instructions": "",
  "ttsEngine": "litellm",
  "ttsVoice": "alloy",
  "sttEngine": "litellm",
  "sttLanguage": "en",
  "dark_mode": true,
  "sayHeard": false,
  "display_mode": "smart",
  "gallery_interval": 10,
  "weather_update_interval": 300,
  "screensaver_enabled": true,
  "screensaver_timeout": 300,
  "screensaver_style": "starfield",
  "screensaver_bounce_text": "GPT Home",
  "vadThresholdDb": -55.0,
  "micGain": 80,
  "pauseThreshold": 1.2,
  "phraseTimeLimit": 15,
  "nonSpeakingDuration": 0.8
}

Note: The display_mode and gallery_interval settings only apply to full graphical displays (HDMI, PiScreen, SPI). I2C displays are text-only and do not support display modes. See Hardware Setup for details.

I2C IP address / Docker networking: The I2C display now attempts to dynamically detect an appropriate IP address (best-effort) — typically the outbound interface address used to reach the network. If you need the host machine's LAN IP to be shown reliably, run the app service with host networking (add network_mode: host to the app service in docker compose.yml). Ensure the container can access display devices (for example, privileged: true and device mappings such as devices: - /dev/dri:/dev/dri - /dev/i2c-1:/dev/i2c-1), then use Settings → Display → Refresh to re-detect and initialize the display.

Settings Reference

Setting Type Default Description
model string gpt-4o-mini LLM model identifier
embedding_model string openai:text-embedding-3-small Embedding model (format: provider:model)
temperature float 0.7 Response creativity (0-2)
max_tokens int 1024 Maximum response length
keyword string computer Wake word to trigger assistant
sayHeard bool false Speak "Heard: ..." confirmation
ttsEngine string "litellm" Text-to-speech engine: pyttsx3, gtts, or litellm
ttsVoice string "alloy" TTS voice (OpenAI: alloy, echo, fable, onyx, nova, shimmer)
sttEngine string "litellm" Speech-to-text engine: google or litellm
sttLanguage string "en" STT language code (e.g., en, es, fr, de, ja, zh)
custom_instructions string "" Additional system prompt text
dark_mode bool true Web interface dark mode
display_mode string "smart" Display mode: smart, clock, weather, gallery, waveform, or off (full displays only)
gallery_interval int 10 Gallery image rotation interval in seconds (full displays only)
weather_update_interval int 300 Weather data update interval in seconds
screensaver_enabled bool true Enable screensaver to prevent display burn-in
screensaver_timeout int 300 Seconds of inactivity before screensaver activates
screensaver_style string "starfield" Screensaver animation: starfield, matrix, bounce, or fade. Applies to all display types.
screensaver_bounce_text string "GPT Home" Text shown in the bounce screensaver
vadThresholdDb float -55.0 Voice Activity Detection threshold in dB. Higher values (e.g., -30) = less sensitive (rejects background noise). Lower values (e.g., -60) = more sensitive (catches quiet speech). Adjustable via web UI.

Audio Input Settings

Setting Type Default Description
micGain int 80 Hardware capture volume (0-100%). Controlled via ALSA mixer.
vadThresholdDb float -55.0 VAD threshold in dB. Audio below this level is ignored.
pauseThreshold float 1.2 Seconds of silence to mark end of phrase.
phraseTimeLimit int 15 Maximum seconds to listen for a single phrase.
nonSpeakingDuration float 0.8 Minimum seconds of non-speaking audio before phrase considered complete.

The web interface provides controls for microphone input under Settings → Audio:

  • Mic Gain: Increase if your speech is too quiet (showing below -50 dB in logs).
  • Voice Detection Threshold: Lower for quiet environments, raise for noisy environments.
  • Pause Threshold: Increase if the assistant cuts you off mid-sentence.

Tip: If speech isn't being detected, check the logs for [VAD] Peak: -XX.X dB. Either increase mic gain or lower the VAD threshold.

Speech Engine Configuration

GPT Home supports separate configuration for text-to-speech (TTS) and speech-to-text (STT) engines.

TTS Engines

Engine Type Requirements Notes
pyttsx3 Offline None Default, works without internet
gtts Online Internet Google TTS, better quality
litellm API-based Compatible API key Best quality, configurable voices

STT Engines

Engine Type Requirements Notes
google Online Internet Free, no API key required
litellm API-based Compatible API key Uses Whisper or provider's STT

LiteLLM Speech Provider Support

The system automatically detects your provider from the API key:

Provider TTS Model TTS Voices STT Model Key Pattern
OpenAI openai/tts-1 alloy, echo, fable, onyx, nova, shimmer openai/whisper-1 sk-...
Google/Gemini gemini/gemini-2.5-flash-preview-tts en-US-Standard-A/B/C/D, en-US-Wavenet-A/B gemini/gemini-1.5-flash AIza...
Groq ✗ Not available — groq/whisper-large-v3 gsk_...
Anthropic ✗ Not available — ✗ Not available sk-ant-...

Supported STT Languages

When using LiteLLM STT, you can configure the language for better recognition accuracy:

en (English), es (Spanish), fr (French), de (German), it (Italian), pt (Portuguese), nl (Dutch), ja (Japanese), ko (Korean), zh (Chinese), ru (Russian), ar (Arabic), hi (Hindi), pl (Polish), tr (Turkish), vi (Vietnamese), th (Thai), id (Indonesian), sv (Swedish), da (Danish), fi (Finnish), no (Norwegian), cs (Czech), el (Greek), he (Hebrew), uk (Ukrainian)

Fallback Behavior:

  • If LiteLLM TTS fails or isn't available → falls back to pyttsx3
  • If LiteLLM STT fails or isn't available → falls back to Google Speech Recognition

Configuration Example

{
  "ttsEngine": "litellm",
  "ttsVoice": "nova",
  "sttEngine": "litellm",
  "sttLanguage": "en"
}

Or configure via the web interface at Settings → General Settings.

LiteLLM Model Configuration

GPT Home uses LiteLLM to support 100+ AI providers. The model name format determines the provider:

Supported Providers

┌─────────────────────────────────────────────────────────────────────┐
│                     LiteLLM Model Formats                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  Provider         │ Model Format                │ API Key Env        │
│  ─────────────────┼─────────────────────────────┼────────────────── │
│  OpenAI           │ gpt-4o, gpt-4o-mini         │ LITELLM_API_KEY   │
│  Anthropic        │ claude-3-haiku-20240307     │ LITELLM_API_KEY   │
│  Google           │ gemini/gemini-1.5-flash     │ LITELLM_API_KEY   │
│  Cohere           │ command-r, command-r-plus   │ LITELLM_API_KEY   │
│  Mistral          │ mistral/mistral-large       │ LITELLM_API_KEY   │
│  Groq             │ groq/llama-3.1-70b          │ LITELLM_API_KEY   │
│  Together AI      │ together_ai/meta-llama/...  │ LITELLM_API_KEY   │
│  Ollama (local)   │ ollama/llama3.2             │ (none)            │
│  OpenRouter       │ openrouter/...              │ LITELLM_API_KEY   │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Configuration Examples

OpenAI:

MODEL=gpt-4o-mini
LITELLM_API_KEY=sk-...

Anthropic Claude:

MODEL=claude-3-5-sonnet-20241022
LITELLM_API_KEY=sk-ant-...

Google Gemini:

MODEL=gemini/gemini-1.5-flash
LITELLM_API_KEY=AIza...

Local Ollama:

MODEL=ollama/llama3.2
# No API key needed
# Requires Ollama running on localhost:11434

Groq (fast inference):

MODEL=groq/llama-3.1-70b-versatile
LITELLM_API_KEY=gsk_...

Model Selection via API

Fetch available models:

curl -X POST http://gpt-home.local/availableModels

Update model:

curl -X POST http://gpt-home.local/updateModel \
  -H "Content-Type: application/json" \
  -d '{"model_id": "claude-3-haiku-20240307"}'

Agent Configuration

The AgentConfig class in src/agent/config.py controls agent behavior:

@dataclass
class AgentConfig:
    model: str = "gpt-4o-mini"           # LiteLLM model name
    temperature: float = 0.7              # Response randomness
    max_tokens: int = 1024                # Max response length
    custom_instructions: str = ""         # Additional prompt text
    embedding_model: str = "openai:text-embedding-3-small"  # Format: provider:model
    embedding_dims: int = 1536
    database_url: Optional[str] = None

Programmatic Configuration

from agent import AgentConfig

# Using builder pattern
config = AgentConfig.builder() \
    .with_model("claude-3-haiku-20240307") \
    .with_temperature(0.5) \
    .with_max_tokens(2048) \
    .with_custom_instructions("Always be concise.") \
    .with_database_url("postgresql://...") \
    .build()

# Or from settings file
config = AgentConfig.from_settings()

Docker Compose Configuration

GPT Home uses Docker Compose profiles to separate development and production environments. The default profile is prod (set via COMPOSE_PROFILES=prod in .env).

Profiles

Profile Command Services
prod (default) docker compose up -d db, nginx, backend, frontend, spotify
dev COMPOSE_PROFILES=dev docker compose up db, nginx, backend, frontend-dev, spotify

Note: The backend service runs a single uvicorn process where FastAPI (backend.py) imports and runs the voice assistant (app.py) as a background task. This enables direct method calls for display/waveform updates instead of HTTP. The frontend/frontend-dev services only handle frontend serving.

Production Configuration

services:
  db:
    image: pgvector/pgvector:0.8.1-pg18-trixie
    # Always runs (no profile)
    
  nginx:
    image: nginx:alpine
    # Always runs - routes /api to backend, static to frontend
    ports:
      - "80:80"
    volumes:
      - ./contrib/nginx.conf:/etc/nginx/nginx.conf:ro

  frontend:
    build:
      dockerfile: compose/web/Dockerfile
    profiles: [prod]
    expose:
      - "80"

  backend:
    build:
      dockerfile: compose/app/Dockerfile
    profiles: [prod]
    environment:
      SDL_VIDEODRIVER: kmsdrm
      SDL_KMSDRM_REQUIRE_DRM_MASTER: "0"
      XDG_RUNTIME_DIR: /tmp
    devices:
      - /dev/snd:/dev/snd
      - /dev/i2c-1:/dev/i2c-1
      - /dev/dri:/dev/dri
    privileged: true

  spotifyd:
    build:
      dockerfile: compose/spotifyd/Dockerfile
    profiles: [prod]
    network_mode: host  # Required for Avahi mDNS

Development Configuration

  frontend-dev:
    build:
      dockerfile: compose/web/Dockerfile.dev
    profiles: [dev]
    ports:
      - "80:80"  # React dev server with hot reload
    volumes:
      - ./src/frontend:/app  # Hot reload
    environment:
      CHOKIDAR_USEPOLLING: "true"

Nginx Configuration

The nginx reverse proxy (contrib/nginx.conf) includes SSE-optimized settings:

  • proxy_buffering off - Disables response buffering for real-time streaming
  • chunked_transfer_encoding off - Required for SSE
  • proxy_read_timeout 86400s - 24-hour timeout for long-lived SSE connections

Volume Mounts (Production)

Host Path Container Path Service Purpose
./src/settings.json /app/src/settings.json web, app Runtime settings
./.env /app/.env all Environment variables
./contrib/nginx.conf /etc/nginx/nginx.conf nginx Nginx configuration
/etc/asound.conf /etc/asound.conf app, spotifyd ALSA config
/dev/snd /dev/snd app, spotifyd Audio devices
/dev/dri /dev/dri app DRM/KMS display devices
/dev/i2c-1 /dev/i2c-1 app I2C display bus
/etc/localtime /etc/localtime app Timezone (read-only)

Integration Setup

Spotify Setup

  1. Create app at Spotify Developer Dashboard

  2. Add Redirect URI in your Spotify app settings:

    https://gpt-home.judahpaul.com/spotify/callback

  3. Add the client ID and client secret on the web interface's Integrations page. They are stored in the integrations table.

  4. Authorization:

    • Click the "Authorize" button in the web interface
    • Log in to Spotify and grant permissions
    • The device receives tokens automatically via the OAuth broker

  5. Speaker pairing:

    • Click the "Pair Speaker" button in the web interface
    • Approve the request at spotify.com/pair, the button shows the code if the page asks for one
    • The device stores its own refresh token, so pairing happens once

How it works: GPT Home uses an OAuth broker at gpt-home.judahpaul.com to handle the OAuth callback (required because Spotify needs HTTPS redirect URIs). The broker only holds credentials temporarily during authorization, then the device refreshes tokens directly with Spotify. The broker is open source at gpt-home-oauth-broker. To use your own, set SPOTIFY_BROKER_URL in .env to its origin and add <origin>/spotify/callback as a Redirect URI in your Spotify app.

Speaker login: spotifyd plays audio via Spotify Connect and signs in separately from the Web API tokens. Spotify only accepts streaming logins from tokens issued through the device pairing flow (RFC 8628 against accounts.spotify.com), so the backend runs that flow, stores the resulting refresh token in the app_settings table, and seeds spotifyd's credential cache with a fresh access token whenever the GPT Home device is missing from the device list.

Philips Hue Setup

  1. Find bridge IP (from Hue app or router)
  2. Add to .env:
PHILIPS_HUE_BRIDGE_IP=192.168.1.100
  1. Connect via web interface (press bridge button when prompted)
  2. Username is saved automatically

CalDAV Setup

CALDAV_URL=https://caldav.example.com/remote.php/dav/calendars/user/
CALDAV_USERNAME=your-username
CALDAV_PASSWORD=your-password

Provider-specific URLs:

Provider URL Format
Nextcloud https://your-server/remote.php/dav/calendars/username/
Google https://apidata.googleusercontent.com/caldav/v2/calid/events
iCloud https://caldav.icloud.com/
Fastmail https://caldav.fastmail.com/dav/calendars/user/

OpenWeatherMap Setup (Optional)

Weather display works automatically without any API key using the free Open-Meteo API. Location is determined via IP geolocation if lat/lon are not set in settings.

For more detailed weather data, you can optionally configure OpenWeatherMap:

  1. Get API key from OpenWeatherMap
  2. Add to .env:
OPEN_WEATHER_API_KEY=your-api-key

Fallback behavior:

  • If OpenWeatherMap API key is set → Uses OpenWeatherMap (more detailed data)
  • If no API key or API fails → Automatically falls back to Open-Meteo (free, no key required)
  • If no location configured → Uses IP geolocation to determine location

Runtime Configuration

Modify Settings at Runtime

Via Web Interface: Navigate to http://gpt-home.local/settings

Via API:

# Read settings
curl -X POST http://gpt-home.local/api/settings \
  -H "Content-Type: application/json" \
  -d '{"action": "read"}'

# Update settings
curl -X POST http://gpt-home.local/api/settings \
  -H "Content-Type: application/json" \
  -d '{
    "action": "update",
    "data": {
      "model": "gpt-4o",
      "temperature": 0.5
    }
  }'

Restart Services

After configuration changes:

# Restart backend only
docker restart gpt-home-backend-1

# Restart all services
docker compose restart

# Full rebuild
docker compose down && docker compose up -d

Environment File Templates

Minimal Configuration

# .env.minimal
LITELLM_API_KEY=sk-your-api-key

Full Configuration

# .env.full
# Core
LITELLM_API_KEY=sk-your-api-key
MODEL=gpt-4o-mini

# Database
POSTGRES_DB=gpt_home
POSTGRES_USER=gpt_home
POSTGRES_PASSWORD=secure-password-here

# Embeddings
EMBEDDING_MODEL=openai:text-embedding-3-small
EMBEDDING_DIMS=1536

# Spotify OAuth broker
SPOTIFY_BROKER_URL=https://gpt-home.judahpaul.com

# Weather
OPEN_WEATHER_API_KEY=your-key
DEFAULT_LOCATION=New York

# Philips Hue
PHILIPS_HUE_BRIDGE_IP=192.168.1.100
PHILIPS_HUE_USERNAME=hue-username

# Calendar
CALDAV_URL=https://caldav.example.com/dav/
CALDAV_USERNAME=user
CALDAV_PASSWORD=password

# LangSmith (optional)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=lsv2_...
LANGCHAIN_PROJECT=gpt-home

Troubleshooting Configuration

Check Current Configuration

# View environment variables in container
docker compose exec backend env | grep -E 'LITELLM|MODEL|DATABASE|SPOTIFY'

# View settings.json
docker compose exec backend cat /app/src/settings.json

# Check service status
docker compose ps

Common Issues

API Key Not Working:

# Verify key is loaded
docker compose exec backend python3 -c "import os; print(os.getenv('LITELLM_API_KEY'))"

Database Connection Failed:

# Test PostgreSQL connection
docker compose exec db psql -U gpt_home -d gpt_home -c "SELECT 1"

Settings Not Persisting:

# Ensure volume mount is correct
docker compose exec backend ls -la /app/src/settings.json

Next Steps

📚 GPT Home Wiki

🏠 Home

Core Documentation

Integration & API

Setup Guides

Quick Links

External Docs

Clone this wiki locally