Pensieve Docs

Environment Variables

configurationenvironment-variablesreference

Environment Variables

This page lists all environment variables used by Pensieve. Variables are grouped by component.

Backend

These variables are used by the Pensieve FastAPI backend.

Secrets (Required)

Variable Description Example
OPENAI_API_KEY API key for the OpenAI LLM provider. Referenced in Global Configuration via ${OPENAI_API_KEY}. sk-proj-abc123...

Secrets (Optional)

Variable Description Example
SEARCH_API_KEY API key for the search provider (Tavily, SerpAPI, or Brave). Referenced in Global Configuration via ${SEARCH_API_KEY}. Only needed if web search is enabled. tvly-abc123...

Server Settings

Variable Default Description
PENSIEVE_HOST 127.0.0.1 Host address the server binds to. Set to 0.0.0.0 to accept connections from other machines. The Docker image defaults to 0.0.0.0.
PENSIEVE_PORT 8000 Port the server listens on.
PENSIEVE_CONFIG config.yaml Path to the global configuration file. Useful when running from a different directory or in Docker.

How Secrets Are Loaded

Pensieve uses ${VAR_NAME} interpolation in config.yaml. At startup, any ${VAR_NAME} pattern is replaced with the corresponding environment variable value. See Global Configuration — Environment Variable Interpolation.

A .env file in the application root is loaded automatically via python-dotenv:

# .env (application root)
OPENAI_API_KEY=sk-your-openai-api-key
SEARCH_API_KEY=tvly-your-tavily-api-key

For Docker Compose, the .env file is loaded automatically by Compose and passed to containers.

Frontend

These variables configure the Vite-based React frontend. They follow Vite’s naming convention — all must start with VITE_.

Variable Default Description
VITE_API_URL http://localhost:8000 Base URL for the Pensieve REST API.
VITE_WS_URL ws://localhost:8000/ws WebSocket endpoint URL.

The frontend resolves these values in priority order:

  1. Runtime injection — window.__env__ written by the Docker container’s entrypoint at startup (see Docker Runtime Configuration below).
  2. Build-time variables — import.meta.env.VITE_* embedded by Vite at build time.
  3. Hardcoded defaults — http://localhost:8000 and ws://localhost:8000/ws.

Setting Frontend Variables

During development (Vite dev server):

VITE_API_URL=http://localhost:9000 npm run dev

Or via frontend/.env.local (not committed to git):

# frontend/.env.local
VITE_API_URL=http://localhost:9000
VITE_WS_URL=ws://localhost:9000/ws

For production builds:

VITE_API_URL=https://api.example.com npm run build

For Docker (runtime — no rebuild needed):

docker run -d \
  -e VITE_API_URL=https://api.example.com \
  -e VITE_WS_URL=wss://api.example.com/ws \
  ghcr.io/5000k/pensieve-frontend:latest

For Docker builds (build-time alternative):

docker build \
  --build-arg VITE_API_URL=https://api.example.com \
  --build-arg VITE_WS_URL=wss://api.example.com/ws \
  -t pensieve-frontend ./frontend

Docker Runtime Configuration

When the frontend container starts, its entrypoint script reads VITE_API_URL and VITE_WS_URL and writes them into /usr/share/nginx/html/env-config.js:

window.__env__ = {
  VITE_API_URL: "https://api.example.com",
  VITE_WS_URL:  "wss://api.example.com/ws"
};

This means you can point the pre-built frontend image at any backend without rebuilding — just pass the environment variables at docker run time or in your docker-compose.yml. If neither variable is set, the frontend falls back to the build-time defaults (http://localhost:8000 / ws://localhost:8000/ws).

Docker-specific

These variables are set by the Docker images and generally don’t need to be changed:

Variable Set by Value Notes
PENSIEVE_HOST Backend Dockerfile 0.0.0.0 Binds to all interfaces inside the container.
PENSIEVE_PORT Backend Dockerfile 8000 Internal container port. Map to a different host port with -p <host>:8000.
VITE_API_URL Frontend container (runtime) (empty — falls back to http://localhost:8000) Pass -e VITE_API_URL=... to override without rebuilding.
VITE_WS_URL Frontend container (runtime) (empty — falls back to ws://localhost:8000/ws) Pass -e VITE_WS_URL=... to override without rebuilding.

Summary Table

Variable Component Required Default
OPENAI_API_KEY Backend Yes —
SEARCH_API_KEY Backend No —
PENSIEVE_HOST Backend No 127.0.0.1 (0.0.0.0 in Docker)
PENSIEVE_PORT Backend No 8000
PENSIEVE_CONFIG Backend No config.yaml
VITE_API_URL Frontend No http://localhost:8000 (runtime-configurable in Docker)
VITE_WS_URL Frontend No ws://localhost:8000/ws (runtime-configurable in Docker)

Next Steps