Environment variables

Perplexica can be configured using environment variables, which is especially useful for Docker deployments and automation.

How environment variables work

Environment variables are processed on container startup. If a required environment variable is set (with valid configuration), the corresponding provider is automatically configured.

Environment variables:

Are applied when Perplexica starts
Create provider configurations automatically
Are merged with existing configuration
Take precedence on first initialization

Provider configuration

Configure LLM providers using environment variables.

Ollama

string

Base URL for Ollama serverRequired: Yes (to auto-configure Ollama)Docker examples:

Windows/Mac: http://host.docker.internal:11434
Linux: http://<host-ip>:11434

Non-Docker: http://localhost:11434

docker run -d -p 3000:3000 \
  -e OLLAMA_BASE_URL="http://host.docker.internal:11434" \
  -v perplexica-data:/home/perplexica/data \
  --name perplexica \
  itzcrazykns1337/perplexica:latest

OpenAI

string

Your OpenAI API keyRequired: Yes (to auto-configure OpenAI)

string

default:"https://api.openai.com/v1"

Base URL for OpenAI APIRequired: Yes (to auto-configure OpenAI)Default: https://api.openai.com/v1For OpenAI-compatible APIs, use your custom URL

docker run -d -p 3000:3000 \
  -e OPENAI_API_KEY="sk-..." \
  -e OPENAI_BASE_URL="https://api.openai.com/v1" \
  -v perplexica-data:/home/perplexica/data \
  --name perplexica \
  itzcrazykns1337/perplexica:latest

Anthropic

string

Your Anthropic API keyRequired: Yes (to auto-configure Anthropic)

docker run -d -p 3000:3000 \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -v perplexica-data:/home/perplexica/data \
  --name perplexica \
  itzcrazykns1337/perplexica:latest

Gemini

string

Your Google AI API key for GeminiRequired: Yes (to auto-configure Gemini)

docker run -d -p 3000:3000 \
  -e GEMINI_API_KEY="AIza..." \
  -v perplexica-data:/home/perplexica/data \
  --name perplexica \
  itzcrazykns1337/perplexica:latest

Groq

string

Your Groq API keyRequired: Yes (to auto-configure Groq)

docker run -d -p 3000:3000 \
  -e GROQ_API_KEY="gsk_..." \
  -v perplexica-data:/home/perplexica/data \
  --name perplexica \
  itzcrazykns1337/perplexica:latest

LM Studio

string

Base URL for LM Studio serverRequired: Yes (to auto-configure LM Studio)Default: http://localhost:1234The /v1 suffix is added automatically

docker run -d -p 3000:3000 \
  -e LM_STUDIO_BASE_URL="http://host.docker.internal:1234" \
  -v perplexica-data:/home/perplexica/data \
  --name perplexica \
  itzcrazykns1337/perplexica:latest

Lemonade

string

Base URL for Lemonade serverRequired: Yes (to auto-configure Lemonade)Example: https://api.lemonade.ai/v1

string

Your Lemonade API keyRequired: No (optional)

docker run -d -p 3000:3000 \
  -e LEMONADE_BASE_URL="http://host.docker.internal:8000" \
  -e LEMONADE_API_KEY="your-key" \
  -v perplexica-data:/home/perplexica/data \
  --name perplexica \
  itzcrazykns1337/perplexica:latest

Search configuration

SearxNG

string

default:"http://localhost:8080"

URL for your SearxNG instanceDefault: http://localhost:8080 (bundled SearxNG)Override this when using an external SearxNG instance

# Using external SearxNG with slim image
docker run -d -p 3000:3000 \
  -e SEARXNG_API_URL="http://my-searxng:8080" \
  -v perplexica-data:/home/perplexica/data \
  --name perplexica \
  itzcrazykns1337/perplexica:slim-latest

The bundled Perplexica image automatically sets SEARXNG_API_URL=http://localhost:8080 for the included SearxNG instance.

System configuration

Data directory

string

default:"/home/perplexica/data"

Directory where Perplexica stores configuration and dataDefault: /home/perplexica/dataNote: This is automatically set in Docker images

Changing DATA_DIR is not recommended unless you have a specific use case. Ensure you mount a volume to the new location.

Docker detection

boolean

Indicates whether Perplexica is running in DockerSet by: Docker images automaticallyEffect: Changes default URLs (e.g., Ollama URL suggestions)

Multiple providers

You can configure multiple providers simultaneously:

docker run -d -p 3000:3000 \
  -e OLLAMA_BASE_URL="http://host.docker.internal:11434" \
  -e OPENAI_API_KEY="sk-..." \
  -e OPENAI_BASE_URL="https://api.openai.com/v1" \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -e GEMINI_API_KEY="AIza..." \
  -e GROQ_API_KEY="gsk_..." \
  -v perplexica-data:/home/perplexica/data \
  --name perplexica \
  itzcrazykns1337/perplexica:latest

Configuring multiple providers gives you flexibility to choose different models for different tasks.

Docker Compose example

Using environment variables with Docker Compose:

version: '3.8'

services:
  perplexica:
    image: itzcrazykns1337/perplexica:latest
    ports:
      - "3000:3000"
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:11434
      - OPENAI_API_KEY=sk-your-key
      - OPENAI_BASE_URL=https://api.openai.com/v1
      - ANTHROPIC_API_KEY=sk-ant-your-key
      - SEARXNG_API_URL=http://localhost:8080
    volumes:
      - perplexica-data:/home/perplexica/data

volumes:
  perplexica-data:

Using .env file

Create a .env file:

# .env
OLLAMA_BASE_URL=http://host.docker.internal:11434
OPENAI_API_KEY=sk-your-key
OPENAI_BASE_URL=https://api.openai.com/v1
ANTHROPIC_API_KEY=sk-ant-your-key
GEMINI_API_KEY=AIza-your-key
GROQ_API_KEY=gsk-your-key
SEARXNG_API_URL=http://localhost:8080

Then use with Docker Compose:

version: '3.8'

services:
  perplexica:
    image: itzcrazykns1337/perplexica:latest
    ports:
      - "3000:3000"
    env_file:
      - .env
    volumes:
      - perplexica-data:/home/perplexica/data

volumes:
  perplexica-data:

Never commit .env files containing API keys to version control. Add .env to your .gitignore.

Non-Docker usage

For non-Docker installations, set environment variables before starting:

Linux/Mac

export OLLAMA_BASE_URL="http://localhost:11434"
export OPENAI_API_KEY="sk-your-key"
export OPENAI_BASE_URL="https://api.openai.com/v1"
export SEARXNG_API_URL="http://localhost:8080"

npm run start

Windows (PowerShell)

$env:OLLAMA_BASE_URL="http://localhost:11434"
$env:OPENAI_API_KEY="sk-your-key"
$env:OPENAI_BASE_URL="https://api.openai.com/v1"
$env:SEARXNG_API_URL="http://localhost:8080"

npm run start

Windows (Command Prompt)

set OLLAMA_BASE_URL=http://localhost:11434
set OPENAI_API_KEY=sk-your-key
set OPENAI_BASE_URL=https://api.openai.com/v1
set SEARXNG_API_URL=http://localhost:8080

npm run start

Validation

Perplexica validates environment variables on startup:

Missing required fields: Provider is not auto-configured
Invalid values: Error logged, provider skipped
Connection test: Providers are tested when configured

Check logs for validation messages:

docker logs perplexica

Example validation messages

Failed to initialize provider. Type: openai, ID: abc-123, Config: {...}, Error: Invalid config provided. API key and base URL must be provided

Failed to get model list. Type: ollama, ID: def-456, Error: Error connecting to Ollama API. Please ensure the base URL is correct and the Ollama server is running.

Environment variable precedence

Configuration priority (highest to lowest):

Existing configuration: Settings already saved in config.json
Environment variables: Applied on startup for new providers
Defaults: Built-in defaults (e.g., OpenAI base URL)

If a provider with the same configuration already exists (matched by hash), environment variables won’t create a duplicate.

Security considerations

Never expose API keys in:

Public repositories
Container images
Logs or error messages
Unencrypted storage

Best practices:

Use Docker secrets or orchestration tools (Kubernetes secrets, etc.)
Rotate API keys regularly
Use read-only API keys when possible
Restrict network access to Perplexica
Use HTTPS for external API endpoints

For production deployments, consider using secret management tools like:

Docker Swarm secrets
Kubernetes secrets
HashiCorp Vault
AWS Secrets Manager
Azure Key Vault

Troubleshooting

Provider not auto-configured

Check required variables are set

Each provider requires specific environment variables:

Ollama: OLLAMA_BASE_URL
OpenAI: OPENAI_API_KEY AND OPENAI_BASE_URL
Anthropic: ANTHROPIC_API_KEY
Gemini: GEMINI_API_KEY
Groq: GROQ_API_KEY
LM Studio: LM_STUDIO_BASE_URL
Lemonade: LEMONADE_BASE_URL

Missing any required variable prevents auto-configuration.

Verify environment variables are passed

Check that Docker receives the variables:

docker exec perplexica env | grep -E 'OLLAMA|OPENAI|ANTHROPIC|GEMINI|GROQ|SEARXNG'

Check logs for errors

View startup logs:

docker logs perplexica 2>&1 | grep -i error

Values not updating

Environment variables are only processed on first initialization. If configuration already exists, environment variables won’t override it.

To force reconfiguration:

Remove the existing provider in the settings UI
Restart Perplexica
Environment variables will create a new provider entry

Or delete the configuration file (⚠️ removes all settings):

docker exec perplexica rm /home/perplexica/data/config.json
docker restart perplexica

Get Started

Core Features

Configuration

Deployment

Advanced

Environment variables

How environment variables work

Provider configuration

Ollama

OpenAI

Anthropic

Gemini

Groq

LM Studio

Lemonade

Search configuration

SearxNG

System configuration

Data directory

Docker detection

Multiple providers

Docker Compose example

Using .env file

Non-Docker usage

Linux/Mac

Windows (PowerShell)

Windows (Command Prompt)

Validation

Environment variable precedence

Security considerations

Troubleshooting

Provider not auto-configured

Values not updating

Next steps

​How environment variables work

​Provider configuration

​Ollama

​OpenAI

​Anthropic

​Gemini

​Groq

​LM Studio

​Lemonade

​Search configuration

​SearxNG

​System configuration

​Data directory

​Docker detection

​Multiple providers

​Docker Compose example

​Using .env file

​Non-Docker usage

​Linux/Mac

​Windows (PowerShell)

​Windows (Command Prompt)

​Validation

​Environment variable precedence

​Security considerations

​Troubleshooting

​Provider not auto-configured

​Values not updating

​Next steps

How environment variables work

Provider configuration

Ollama

OpenAI

Anthropic

Gemini

Groq

LM Studio

Lemonade

Search configuration

SearxNG

System configuration

Data directory

Docker detection

Multiple providers

Docker Compose example

Using .env file

Non-Docker usage

Linux/Mac

Windows (PowerShell)

Windows (Command Prompt)

Validation

Environment variable precedence

Security considerations

Troubleshooting

Provider not auto-configured

Values not updating

Next steps