Environment variables

All Cognisafe services are configured exclusively via environment variables. No config files need to be edited.

api (FastAPI backend)

Variable	Required	Description
`POSTGRES_URL`	Yes	asyncpg connection string. Format: `postgresql+asyncpg://user:password@host:5432/dbname`
`REDIS_URL`	Yes	Redis connection string. Format: `redis://host:6379`
`COGNISAFE_ENCRYPTION_KEY`	Yes (prod)	base64-encoded 32-byte key for AES-256-GCM encryption of stored prompt/response bodies and secrets. Required in production — deployments abort without it. Generate with `openssl rand -base64 32`.
`STRIPE_SECRET_KEY`	Yes	Stripe secret API key (`sk_live_...` or `sk_test_...`)
`STRIPE_WEBHOOK_SECRET`	Yes	Stripe webhook signing secret (`whsec_...`). Required for billing webhooks to be accepted.
`STRIPE_PRICE_HOMELAB`	Yes	Stripe Price ID for the Starter tier (£20/mo). Format: `price_...`
`STRIPE_PRICE_PRO`	Yes	Stripe Price ID for the Professional tier (£49/mo). Format: `price_...`
`STRIPE_PRICE_TEAM`	Yes	Stripe Price ID for the Business tier (£199/mo). Format: `price_...`
`INTERNAL_API_SECRET`	Yes	A long random secret shared between the `api` and `web` services. Used to authenticate internal server-to-server calls. Generate with `openssl rand -hex 32`.

Data retention (api)

The api service runs a daily purge with per-tier windows. For paid tiers only the prompt/response bodies are wiped after the window (metadata and safety scores are kept); free and unknown accounts have their rows deleted entirely. Override any window with RETENTION_DAYS_<TIER>.

Variable	Default	Description
`RETENTION_DAYS_FREE`	`7`	Free / unknown accounts — entire rows deleted after this many days.
`RETENTION_DAYS_HOMELAB`	`30`	Starter — bodies wiped after this window.
`RETENTION_DAYS_PRO`	`90`	Professional — bodies wiped after this window.
`RETENTION_DAYS_TEAM`	`365`	Business — bodies wiped after this window.
`RETENTION_DAYS_ENTERPRISE`	(unlimited)	Enterprise — bodies never auto-wiped. Set a number to enforce one.
`POST_CANCEL_DAYS`	`90`	Days after cancellation before a cancelled account’s rows are deleted.

Managed-cloud accounts on Business and Enterprise can additionally enable zero content retention (Settings → Data Retention), which stops prompt/response bodies being written at all — safety scoring still runs from the in-flight request. See the security page.

proxy (Go reverse proxy)

Variable	Required	Description
`UPSTREAM_URL`	Yes	The LLM provider to forward requests to. Default: `https://api.openai.com`. Change for Mistral (`https://api.mistral.ai`), Azure, or Ollama.
`API_BACKEND_URL`	Yes	URL of the `api` service. The proxy POSTs logs here. Example: `http://api:8000` (Docker) or `https://api.cognisafe.uk` (Railway).
`PROXY_API_KEY`	Yes	The API key that clients must send to authenticate with the proxy. Must match a valid Cognisafe project API key.

web (Next.js dashboard)

Variable	Required	Description
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	Yes	Clerk publishable key for client-side auth (`pk_live_...`). Embedded in the browser bundle.
`CLERK_SECRET_KEY`	Yes	Clerk secret key for server-side auth (`sk_live_...`). Never exposed to the browser.
`INTERNAL_API_SECRET`	Yes	Same value as the `api` service. Used by Next.js server-side routes to authenticate calls to the FastAPI backend.
`API_URL`	Yes	Server-side URL of the `api` service. Used by Next.js server components and API routes. Example: `http://api:8000` (Docker) or `https://api.cognisafe.uk` (Railway).
`NEXT_PUBLIC_API_URL`	Yes	Client-side URL of the `api` service. Embedded in the browser bundle — must be publicly accessible. Example: `https://api.cognisafe.uk`.

safety_worker (safety scoring worker)

Variable	Required	Description
`POSTGRES_URL`	Yes	Same connection string as the `api` service. The worker writes scored results directly to PostgreSQL.
`REDIS_URL`	Yes	Same connection string as the `api` service. The worker reads jobs from the `safety_score_jobs` queue.
`OPENAI_API_KEY`	No	OpenAI API key used to run the LLM-as-judge scorers. If not set, all requests fall back to `score_label: "unscored"`.
`SCORER_MODEL`	No	The OpenAI model used for scoring. Default: `gpt-4o-mini`. Override to use a different model, e.g., `gpt-4o`.
`COGNISAFE_ENCRYPTION_KEY`	Yes (prod)	Same key as the `api` service. The worker decrypts stored bodies where needed. Must match `api` exactly.

Docker Compose shared variables

When using infra/docker-compose.yml, these variables are set in .env at the repo root and shared across services via env_file:

Variable	Default	Description
`POSTGRES_URL`	`postgresql+asyncpg://postgres:postgres@postgres:5432/cognisafe`	Overridden per service if needed
`REDIS_URL`	`redis://redis:6379`	—

In Docker Compose, service hostnames resolve to container names (e.g., postgres, redis, api). In Railway or Kubernetes, use the actual service URLs provided by your infrastructure.

Generating secrets

# Generate INTERNAL_API_SECRET
openssl rand -hex 32

# Generate COGNISAFE_ENCRYPTION_KEY (base64 32-byte AES-256 key)
openssl rand -base64 32

# Generate a PROXY_API_KEY (if not using the dashboard)
python -c "import secrets; print('csk_' + secrets.token_hex(24))"

Getting Started

SDKs

LLM Providers

Self-hosted Models

Self-hosting

Integrations

Reference Architectures

Deployment Blueprints

Safety & Scoring

Environment variables

api (FastAPI backend)

Data retention (api)

proxy (Go reverse proxy)

web (Next.js dashboard)

safety_worker (safety scoring worker)

Docker Compose shared variables

Generating secrets

​api (FastAPI backend)

​Data retention (api)

​proxy (Go reverse proxy)

​web (Next.js dashboard)

​safety_worker (safety scoring worker)

​Docker Compose shared variables

​Generating secrets

api (FastAPI backend)

Data retention (api)

proxy (Go reverse proxy)

web (Next.js dashboard)

safety_worker (safety scoring worker)

Docker Compose shared variables

Generating secrets