Skip to main content
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

​
OLLAMA_BASE_URL
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

​
OPENAI_API_KEY
string
Your OpenAI API keyRequired: Yes (to auto-configure OpenAI)
​
OPENAI_BASE_URL
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

​
ANTHROPIC_API_KEY
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

​
GEMINI_API_KEY
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

​
GROQ_API_KEY
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

​
LM_STUDIO_BASE_URL
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

​
LEMONADE_BASE_URL
string
Base URL for Lemonade serverRequired: Yes (to auto-configure Lemonade)Example: https://api.lemonade.ai/v1
​
LEMONADE_API_KEY
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

​
SEARXNG_API_URL
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

​
DATA_DIR
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

​
DOCKER
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

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):
  1. Existing configuration: Settings already saved in config.json
  2. Environment variables: Applied on startup for new providers
  3. 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

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.
Check that Docker receives the variables:
docker exec perplexica env | grep -E 'OLLAMA|OPENAI|ANTHROPIC|GEMINI|GROQ|SEARXNG'
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:
  1. Remove the existing provider in the settings UI
  2. Restart Perplexica
  3. 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

​
Next steps

Build docs developers (and LLMs) love

Get started for freeTalk to us