Skip to main content

Installation

Hindsight can be deployed in three ways depending on your infrastructure and requirements.

Prerequisites​

PostgreSQL with pgvector​

Hindsight requires PostgreSQL with the pgvector extension for vector similarity search.

By default, Hindsight uses pg0 — an embedded PostgreSQL that runs locally on your machine. This is convenient for development but not recommended for production.

For production, use an external PostgreSQL with pgvector:

  • Supabase — Managed PostgreSQL with pgvector built-in
  • Neon — Serverless PostgreSQL with pgvector
  • AWS RDS / Cloud SQL / Azure — With pgvector extension enabled
  • Self-hosted — PostgreSQL 14+ with pgvector installed

LLM Provider​

You need an LLM API key for fact extraction, entity resolution, and answer generation:

  • Groq (recommended): Fast inference with gpt-oss-20b
  • OpenAI: GPT-4o, GPT-4o-mini
  • Ollama: Run models locally

See Models for detailed comparison and configuration.

Docker​

Best for: Quick start, development, small deployments

Single Container (Quickest)​

Run everything in one container with embedded PostgreSQL:

docker run -p 8888:8888 -p 9999:9999 \
  -e HINDSIGHT_API_LLM_PROVIDER=openai \
  -e HINDSIGHT_API_LLM_API_KEY=sk-xxxxxxxxxxxx \
  -e HINDSIGHT_API_LLM_MODEL=gpt-4o-mini \
  ghcr.io/vectorize-io/hindsight

Helm / Kubernetes​

Best for: Production deployments, auto-scaling, cloud environments

# Add Hindsight Helm repository
helm repo add hindsight https://vectorize-io.github.io/hindsight
helm repo update

# Install with built-in PostgreSQL
helm install hindsight hindsight/hindsight \
  --set api.llm.provider=groq \
  --set api.llm.apiKey=gsk_xxxxxxxxxxxx \
  --set postgresql.enabled=true

# Or use external PostgreSQL
helm install hindsight hindsight/hindsight \
  --set api.llm.provider=groq \
  --set api.llm.apiKey=gsk_xxxxxxxxxxxx \
  --set postgresql.enabled=false \
  --set api.database.url=postgresql://user:pass@postgres.example.com:5432/hindsight

Requirements:

  • Kubernetes cluster (GKE, EKS, AKS, or self-hosted)
  • Helm 3+

See the Helm chart documentation for advanced configuration.

Bare Metal (pip)​

Best for: Custom deployments, integration into existing Python applications

Install​

pip install hindsight-all

Run with Embedded Database​

For development and testing, Hindsight can run with an embedded PostgreSQL (pg0):

export HINDSIGHT_API_LLM_PROVIDER=groq
export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx

hindsight-api

This creates a database in ~/.hindsight/data/ and starts the API on http://localhost:8888.

Run with External PostgreSQL​

For production, connect to your own PostgreSQL instance:

export HINDSIGHT_API_DATABASE_URL=postgresql://user:pass@localhost:5432/hindsight
export HINDSIGHT_API_LLM_PROVIDER=groq
export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx

hindsight-api

Note: The database must exist and have pgvector enabled (CREATE EXTENSION vector;).

CLI Options​

hindsight-api --port 9000          # Custom port (default: 8888)
hindsight-api --host 127.0.0.1     # Bind to localhost only
hindsight-api --workers 4          # Multiple worker processes
hindsight-api --mcp                # Enable MCP server
hindsight-api --log-level debug    # Verbose logging

Next Steps​

  • Configuration — Environment variables and settings
  • Models — ML models and providers
  • Metrics — Monitoring and observability