Environment Variables

MQTT Explorer supports extensive configuration through environment variables, enabling automated deployments, containerization, and server mode operation. This guide covers all available environment variables and their usage.

Overview

Environment variables are particularly useful for:

Server Deployments

Configure MQTT Explorer for browser mode with predefined settings

Container Deployments

Deploy with Docker/Kubernetes using environment-based configuration

CI/CD Pipelines

Automated testing and deployment without manual configuration

Multi-Environment Setup

Easy switching between development, staging, and production environments

MQTT Connection Variables

Auto-Connect Configuration

Automatically connect to an MQTT broker when starting in server mode:

MQTT_AUTO_CONNECT_HOST

string

The MQTT broker hostname or IP address to automatically connect to on startup.Required for auto-connect: Yes (triggers auto-connect when set)

export MQTT_AUTO_CONNECT_HOST=mqtt.example.com

When this variable is set, MQTT Explorer will automatically attempt to connect on startup without requiring user interaction.

MQTT_AUTO_CONNECT_PORT

number

default:"1883"

The MQTT broker port to connect to.Common ports:

1883 - Standard MQTT (non-encrypted)
8883 - MQTT over TLS/SSL
8080 - WebSocket
8443 - WebSocket over TLS

export MQTT_AUTO_CONNECT_PORT=8883

MQTT_AUTO_CONNECT_PROTOCOL

string

default:"mqtt"

The connection protocol to use.Options:

mqtt - Standard MQTT protocol
ws - WebSocket protocol

export MQTT_AUTO_CONNECT_PROTOCOL=mqtt

MQTT_AUTO_CONNECT_USERNAME

string

Username for MQTT broker authentication.

export MQTT_AUTO_CONNECT_USERNAME=myuser

Leave unset if your broker doesn’t require authentication.

MQTT_AUTO_CONNECT_PASSWORD

string

Password for MQTT broker authentication.

export MQTT_AUTO_CONNECT_PASSWORD=mypassword

Never commit passwords to version control. Use secrets management or environment-specific configuration files.

MQTT_AUTO_CONNECT_CLIENT_ID

string

default:"mqtt-explorer-[random]"

Custom client ID for the MQTT connection.Default: Auto-generated as mqtt-explorer- followed by random hex string

export MQTT_AUTO_CONNECT_CLIENT_ID=mqtt-explorer-prod-01

Use custom client IDs to:

Identify connections in broker logs
Enable persistent sessions
Prevent conflicts between multiple instances

Auto-Connect Example

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

# MQTT Broker Configuration
export MQTT_AUTO_CONNECT_HOST=mqtt.example.com
export MQTT_AUTO_CONNECT_PORT=1883
export MQTT_AUTO_CONNECT_PROTOCOL=mqtt
export MQTT_AUTO_CONNECT_USERNAME=readonly-user
export MQTT_AUTO_CONNECT_PASSWORD=secret123
export MQTT_AUTO_CONNECT_CLIENT_ID=mqtt-explorer-server

# Start MQTT Explorer server
node dist/src/server.js

Server Authentication Variables

Configure authentication for the MQTT Explorer web interface (browser mode):

MQTT_EXPLORER_USERNAME

string

default:"auto-generated"

Username for accessing the MQTT Explorer web interface.Default: If not set, generates random username like user-a1b2c3d4

export MQTT_EXPLORER_USERNAME=admin

MQTT_EXPLORER_PASSWORD

string

default:"auto-generated"

Password for accessing the MQTT Explorer web interface.Default: If not set, generates random UUID password displayed in console on first startup

export MQTT_EXPLORER_PASSWORD=your_strong_password_min_12_chars

Use strong passwords with at least 12 characters including uppercase, lowercase, numbers, and special characters.

Security features:

Passwords hashed with bcrypt (10 rounds)
Rate limiting: 5 attempts per IP per 15 minutes
Timing-safe comparison to prevent timing attacks

MQTT_EXPLORER_SKIP_AUTH

boolean

default:false

Completely disable authentication for the web interface.

export MQTT_EXPLORER_SKIP_AUTH=true

SECURITY RISK: Only use when MQTT Explorer is behind a secure authentication proxy (e.g., nginx with OAuth2, Authentik, Authelia). Never expose unauthenticated instances to the internet.

When enabled, displays warning:

============================================================
WARNING: Authentication is DISABLED
MQTT_EXPLORER_SKIP_AUTH=true
This should only be used behind a secure authentication proxy!
============================================================

LLM Integration Variables

Configure AI Assistant features for intelligent topic suggestions:

LLM_PROVIDER

string

default:"openai"

The LLM provider to use for AI Assistant features.Options:

openai - OpenAI GPT models
gemini - Google Gemini models

export LLM_PROVIDER=openai
# or
export LLM_PROVIDER=gemini

OPENAI_API_KEY

string

API key for OpenAI (when using OpenAI provider).

export OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxx

Get your API key from: https://platform.openai.com/api-keys

GEMINI_API_KEY

string

API key for Google Gemini (when using Gemini provider).

export GEMINI_API_KEY=AIzaxxxxxxxxxxxxxxxxxxxx

Get your API key from: https://makersuite.google.com/app/apikey

LLM_API_KEY

string

Generic API key that works with either provider (fallback option).

export LLM_PROVIDER=openai
export LLM_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxx

Priority order:

Provider-specific key (OPENAI_API_KEY or GEMINI_API_KEY)
Generic key (LLM_API_KEY)
UI configuration (localStorage)

LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT

number

default:"500"

Maximum tokens to allocate for neighboring topics context in AI prompts.Default: 500 tokens (increased from 100 for better device detection)

# Recommended for home automation (500-1000 tokens)
export LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT=1000

# Reduce for cost optimization (may reduce quality)
export LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT=200

Impact:

Higher values (1000): More context, better multi-device proposals, higher API costs
Default (500): Good balance for most use cases
Lower values (200): Less context, may miss device relationships, lower costs

The default was increased from 100 to 500 to better support multi-device automation proposals and complex topic hierarchies.

LLM Configuration Examples

# Use OpenAI GPT models
export LLM_PROVIDER=openai
export OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxx
export LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT=500

HTTP Server Variables

PORT

number

default:"3000"

Port for the MQTT Explorer web server to listen on.

export PORT=8080

NODE_ENV

string

default:"development"

Node.js environment mode.Options:

development - Verbose logging, detailed errors
production - Minimal logging, generic error messages

export NODE_ENV=production

Production mode changes:

Credentials not logged to console
Generic error messages (no stack traces)
Enhanced security headers
Stricter CORS policies

ALLOWED_ORIGINS

string

default:"*"

Comma-separated list of allowed CORS origins.

# Single origin
export ALLOWED_ORIGINS=https://mqtt-explorer.example.com

# Multiple origins
export ALLOWED_ORIGINS=https://app1.example.com,https://app2.example.com

In production (NODE_ENV=production), wildcard * is automatically disabled for security. Always specify explicit origins.

UPGRADE_INSECURE_REQUESTS

boolean

default:false

Enable HTTP Upgrade-Insecure-Requests header.

export UPGRADE_INSECURE_REQUESTS=true

When enabled, instructs browsers to upgrade HTTP requests to HTTPS automatically.

X_FRAME_OPTIONS

boolean

default:false

Enable X-Frame-Options header to prevent clickjacking.

export X_FRAME_OPTIONS=true

When enabled, sets X-Frame-Options: DENY to prevent embedding in frames.

Testing Variables

Used for automated testing and development:

TESTS_MQTT_BROKER_HOST

string

default:"127.0.0.1"

MQTT broker host for running automated tests.

export TESTS_MQTT_BROKER_HOST=localhost

TESTS_MQTT_BROKER_PORT

string

default:"1883"

MQTT broker port for running automated tests.

export TESTS_MQTT_BROKER_PORT=1883

BROWSER_MODE_URL

string

URL for browser mode testing (used by UI tests).

export BROWSER_MODE_URL=http://localhost:3000

USE_MOBILE_VIEWPORT

boolean

default:false

Use mobile viewport dimensions for UI testing.

export USE_MOBILE_VIEWPORT=true

Complete Deployment Examples

Production Server Deployment

#!/bin/bash
# production-start.sh

# Server Configuration
export NODE_ENV=production
export PORT=3000
export ALLOWED_ORIGINS=https://mqtt-explorer.example.com

# Server Authentication
export MQTT_EXPLORER_USERNAME=admin
export MQTT_EXPLORER_PASSWORD=$(cat /run/secrets/web_password)

# MQTT Broker Auto-Connect
export MQTT_AUTO_CONNECT_HOST=mqtt.example.com
export MQTT_AUTO_CONNECT_PORT=8883
export MQTT_AUTO_CONNECT_USERNAME=readonly-user
export MQTT_AUTO_CONNECT_PASSWORD=$(cat /run/secrets/mqtt_password)
export MQTT_AUTO_CONNECT_CLIENT_ID=mqtt-explorer-prod

# LLM Integration
export LLM_PROVIDER=gemini
export GEMINI_API_KEY=$(cat /run/secrets/gemini_key)
export LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT=500

# Security Headers
export UPGRADE_INSECURE_REQUESTS=true
export X_FRAME_OPTIONS=true

# Start server
node dist/src/server.js

Docker Compose

# docker-compose.yml
version: '3.8'

services:
  mqtt-explorer:
    image: mqtt-explorer:latest
    ports:
      - "3000:3000"
    environment:
      # Server
      - NODE_ENV=production
      - PORT=3000
      - ALLOWED_ORIGINS=https://mqtt-explorer.example.com
      
      # Authentication
      - MQTT_EXPLORER_USERNAME=admin
      - MQTT_EXPLORER_PASSWORD=${WEB_PASSWORD}
      
      # MQTT Connection
      - MQTT_AUTO_CONNECT_HOST=mqtt
      - MQTT_AUTO_CONNECT_PORT=1883
      - MQTT_AUTO_CONNECT_USERNAME=${MQTT_USER}
      - MQTT_AUTO_CONNECT_PASSWORD=${MQTT_PASSWORD}
      
      # LLM
      - LLM_PROVIDER=openai
      - OPENAI_API_KEY=${OPENAI_KEY}
      - LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT=500
    
    restart: unless-stopped
    
  mosquitto:
    image: eclipse-mosquitto:latest
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf
    restart: unless-stopped

# .env (not committed to git)
WEB_PASSWORD=strong_random_password_here
MQTT_USER=mqtt_username
MQTT_PASSWORD=mqtt_password
OPENAI_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxx

Kubernetes Deployment

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mqtt-explorer
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mqtt-explorer
  template:
    metadata:
      labels:
        app: mqtt-explorer
    spec:
      containers:
      - name: mqtt-explorer
        image: mqtt-explorer:latest
        ports:
        - containerPort: 3000
        env:
        - name: NODE_ENV
          value: "production"
        - name: PORT
          value: "3000"
        - name: ALLOWED_ORIGINS
          value: "https://mqtt-explorer.example.com"
        
        # Secrets from Kubernetes secrets
        - name: MQTT_EXPLORER_USERNAME
          valueFrom:
            secretKeyRef:
              name: mqtt-explorer-secrets
              key: web-username
        - name: MQTT_EXPLORER_PASSWORD
          valueFrom:
            secretKeyRef:
              name: mqtt-explorer-secrets
              key: web-password
        
        - name: MQTT_AUTO_CONNECT_HOST
          value: "mosquitto-service"
        - name: MQTT_AUTO_CONNECT_PORT
          value: "1883"
        - name: MQTT_AUTO_CONNECT_USERNAME
          valueFrom:
            secretKeyRef:
              name: mqtt-explorer-secrets
              key: mqtt-username
        - name: MQTT_AUTO_CONNECT_PASSWORD
          valueFrom:
            secretKeyRef:
              name: mqtt-explorer-secrets
              key: mqtt-password
        
        - name: LLM_PROVIDER
          value: "openai"
        - name: OPENAI_API_KEY
          valueFrom:
            secretKeyRef:
              name: mqtt-explorer-secrets
              key: openai-key
        - name: LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT
          value: "500"
---
apiVersion: v1
kind: Service
metadata:
  name: mqtt-explorer-service
spec:
  selector:
    app: mqtt-explorer
  ports:
  - protocol: TCP
    port: 80
    targetPort: 3000
  type: LoadBalancer

Development Setup

# .env.development (not committed)
# MQTT Broker (local Mosquitto)
export MQTT_AUTO_CONNECT_HOST=localhost
export MQTT_AUTO_CONNECT_PORT=1883

# No authentication for local development
export MQTT_EXPLORER_SKIP_AUTH=true

# Optional: LLM testing
export LLM_PROVIDER=openai
export OPENAI_API_KEY=sk-...
export LLM_NEIGHBORING_TOPICS_TOKEN_LIMIT=200

# Development server
export NODE_ENV=development
export PORT=3000

# Start development server
source .env.development
yarn dev:server

Configuration Priority

When multiple configuration sources exist, priority is:

Environment variables (highest priority)
Credentials file (~/.mqtt-explorer-credentials.json)
UI configuration (localStorage in browser mode)
Defaults (lowest priority)

Environment variables always override other configuration sources, making them ideal for deployment automation.

Security Best Practices

Never Commit Secrets

Add .env, .env.*, and credentials files to .gitignore. Never commit API keys or passwords.

Use Secrets Management

In production, use proper secrets management (Kubernetes secrets, AWS Secrets Manager, HashiCorp Vault).

Rotate Credentials

Rotate passwords and API keys regularly (every 90 days minimum).

Least Privilege

Use read-only MQTT credentials when possible. Grant minimum required permissions.

Enable Production Mode

Always set NODE_ENV=production in production for security hardening.

Restrict CORS

Set explicit ALLOWED_ORIGINS in production. Never use wildcard in production.

Troubleshooting

Environment variables not taking effect

Causes:

Variables not exported in shell
Process started before variables were set
Typo in variable name

Solutions:

# Verify variable is set
echo $MQTT_AUTO_CONNECT_HOST

# Check Node.js can see it
node -e "console.log(process.env.MQTT_AUTO_CONNECT_HOST)"

# Export in same shell session
export MQTT_AUTO_CONNECT_HOST=mqtt.example.com
node dist/src/server.js

# Or use env command
env MQTT_AUTO_CONNECT_HOST=mqtt.example.com node dist/src/server.js

Auto-connect not working

Causes:

MQTT_AUTO_CONNECT_HOST not set
Connection parameters incorrect
Broker not accessible

Solutions:

Verify MQTT_AUTO_CONNECT_HOST is set: echo $MQTT_AUTO_CONNECT_HOST
Check broker connectivity: telnet $MQTT_AUTO_CONNECT_HOST $MQTT_AUTO_CONNECT_PORT
Review server logs for connection errors
Test credentials manually first

LLM features not available

Causes:

API key not set
Invalid API key
Wrong provider selected

Solutions:

Check API key is set: echo $OPENAI_API_KEY
Verify API key is valid (test with curl)
Ensure LLM_PROVIDER matches your API key provider
Check server logs for API errors

CORS errors in browser mode

Causes:

ALLOWED_ORIGINS doesn’t include your domain
Wildcard disabled in production

Solutions:

# Set allowed origins
export ALLOWED_ORIGINS=https://your-domain.com

# Multiple origins
export ALLOWED_ORIGINS=https://app1.com,https://app2.com

# Development only (not production)
export NODE_ENV=development
export ALLOWED_ORIGINS=*

Next Steps

Connection Setup

Learn about manual connection configuration in the UI.

Authentication

Understand authentication for both MQTT brokers and server access.

Docker Deployment

Deploy MQTT Explorer with Docker using environment variables.

Security Best Practices

Review complete security guidelines for production deployments.

Get Started

Deployment

Features

Guides

Advanced

Overview

Server Deployments

Container Deployments

CI/CD Pipelines

Multi-Environment Setup

MQTT Connection Variables

Auto-Connect Configuration

Auto-Connect Example

Server Authentication Variables

LLM Integration Variables

LLM Configuration Examples

HTTP Server Variables

Testing Variables

Complete Deployment Examples

Production Server Deployment

Docker Compose

Kubernetes Deployment

Development Setup

Configuration Priority

Security Best Practices

Never Commit Secrets

Use Secrets Management

Rotate Credentials

Least Privilege

Enable Production Mode

Restrict CORS

Troubleshooting

Next Steps

Connection Setup

Authentication

Docker Deployment

Security Best Practices

Get Started

Deployment

Features

Guides

Advanced

​Overview

Server Deployments

Container Deployments

CI/CD Pipelines

Multi-Environment Setup

​MQTT Connection Variables

​Auto-Connect Configuration

​Auto-Connect Example

​Server Authentication Variables

​LLM Integration Variables

​LLM Configuration Examples

​HTTP Server Variables

​Testing Variables

​Complete Deployment Examples

​Production Server Deployment

​Docker Compose

​Kubernetes Deployment

​Development Setup

​Configuration Priority

​Security Best Practices

Never Commit Secrets

Use Secrets Management

Rotate Credentials

Least Privilege

Enable Production Mode

Restrict CORS

​Troubleshooting

​Next Steps

Connection Setup

Authentication

Docker Deployment

Security Best Practices

Overview

MQTT Connection Variables

Auto-Connect Configuration

Auto-Connect Example

Server Authentication Variables

LLM Integration Variables

LLM Configuration Examples

HTTP Server Variables

Testing Variables

Complete Deployment Examples

Production Server Deployment

Docker Compose

Kubernetes Deployment

Development Setup

Configuration Priority

Security Best Practices

Troubleshooting

Next Steps