mqtt-explorer/ENV_VARS_EXAMPLE.md

Environment Variables for LLM Integration

This document provides examples of how to configure the AI Assistant using environment variables for server deployments.

Basic Configuration

# Set up OpenAI as the provider
export LLM_PROVIDER=openai
export OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxx

# Or use Gemini
export LLM_PROVIDER=gemini
export GEMINI_API_KEY=AIzaxxxxxxxxxxxxxxxxxxxx

# Or use the generic LLM_API_KEY (works with either provider)
export LLM_PROVIDER=openai
export LLM_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxx

Advanced Configuration

# Configure token limit for neighboring topics context
export LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT=100  # Default: 100 tokens

# Example: Increase token limit for more context
export LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT=200

# Example: Decrease token limit to reduce API costs
export LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT=50

Complete Example for Server Deployment

#!/bin/bash
# start-mqtt-explorer.sh

# MQTT Connection
export MQTT_EXPLORER_SKIP_AUTH=true  # Or configure authentication
export MQTT_AUTO_CONNECT_HOST=mqtt.example.com
export MQTT_AUTO_CONNECT_PORT=1883

# LLM Configuration
export LLM_PROVIDER=gemini
export GEMINI_API_KEY=AIzaxxxxxxxxxxxxxxxxxxxx
export LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT=100

# Start the server
node dist/src/server.js

Docker Example

# Dockerfile
FROM node:24-alpine

WORKDIR /app
COPY . .
RUN yarn install && yarn build:server

# Environment variables can be set at runtime
ENV LLM_PROVIDER=openai
ENV LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT=100

EXPOSE 3000
CMD ["node", "dist/src/server.js"]

# Run with docker
docker run -d \
  -e OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxx \
  -e LLM_PROVIDER=openai \
  -e LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT=100 \
  -e MQTT_AUTO_CONNECT_HOST=mqtt.example.com \
  -p 3000:3000 \
  mqtt-explorer

Context Generation with Token Limits

The LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT controls how many tokens are allocated for neighboring topics in the context. Here's what happens:

With Default 100 Tokens

Topic Path: sensors/living_room/temperature
Value: 22.5
Status: Retained

Related Topics (5 shown):
  humidity: 65
  pressure: 1013.25
  air_quality: {"pm25":12,"pm10":8,"co2":450,"voc":120}
  motion: false
  light_level: 450

Message Count: 1
Subtopics: 0

With 50 Tokens (Reduced)

Topic Path: sensors/living_room/temperature
Value: 22.5
Status: Retained

Related Topics (3 shown):
  humidity: 65
  pressure: 1013.25
  air_quality: {"pm25":12,"pm10":8...

Message Count: 1
Subtopics: 0

With 200 Tokens (Increased)

Topic Path: sensors/living_room/temperature
Value: 22.5
Status: Retained

Related Topics (8 shown):
  humidity: 65
  pressure: 1013.25
  air_quality: {"pm25":12,"pm10":8,"co2":450,"voc":120}
  motion: false
  light_level: 450
  battery: 85
  signal_strength: -45
  last_seen: 2026-01-26T23:45:00Z

Message Count: 1
Subtopics: 0

Priority Order

The AI Assistant checks configuration in this order:

1. Environment Variables (highest priority)

   • Provider-specific: OPENAI_API_KEY, GEMINI_API_KEY
   • Generic fallback: LLM_API_KEY
   • Provider selection: LLM_PROVIDER
   • Token limit: LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT

2. localStorage (browser/UI configuration)

   • Set via the configuration dialog in the UI
   • Only used if environment variables are not set

3. Defaults (lowest priority)

   • Provider: openai
   • Token limit: 100

Security Recommendations

• Never commit API keys to version control
• Use environment variables or secrets management
• In production, use .env files (not committed) or container secrets
• Rotate API keys regularly
• Monitor API usage and set billing alerts

Troubleshooting

API Key Not Working

Check priority order:

# Check if env vars are set
echo $OPENAI_API_KEY
echo $LLM_API_KEY
echo $LLM_PROVIDER

# Verify they're available to the Node process
node -e "console.log(process.env.OPENAI_API_KEY)"

Token Limit Too Low

If you're seeing truncated context:

# Increase the token limit
export LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT=200

Want to Use UI Configuration

Simply don't set the environment variables - the UI configuration will be used instead.