Environment Variables

All environment variables can be set in your shell, a .env file (loaded by python-dotenv if installed), or as Docker -e / Compose environment: entries.

Core server

Variable	Default	Required	Description
SECRET_KEY	—	Yes	JWT signing secret — generate with python -c "import secrets; print(secrets.token_hex(32))"
P8G_ADMIN_EMAIL	—	Yes	Bootstrap admin email (used on first start to create the initial admin user)
P8G_ADMIN_PASSWORD	—	Yes	Bootstrap admin password
HOST	0.0.0.0	No	Interface the REST server binds to
PORT	8100	No	TCP port
DB_PATH	./purple8_data	No	Root directory for graph storage
WORKERS	2	No	Number of Uvicorn worker processes
LOG_LEVEL	info	No	debug / info / warning / error
CORS_ORIGINS	*	No	Comma-separated list of allowed CORS origins

SECRET_KEY

Never use a short or guessable secret in production. Generate one with:

python -c "import secrets; print(secrets.token_hex(32))"

LLM provider

Variable	Default	Required	Description
LLM_PROVIDER	openai	No	openai | anthropic | google | ollama
LLM_MODEL	gpt-4o-mini	No	Model name override
OPENAI_API_KEY	—	When LLM_PROVIDER=openai	OpenAI API key
ANTHROPIC_API_KEY	—	When LLM_PROVIDER=anthropic	Anthropic API key
GOOGLE_API_KEY	—	When LLM_PROVIDER=google	Google AI API key
OLLAMA_BASE_URL	http://localhost:11434	No	Ollama server endpoint
LLM_TEMPERATURE	0.0	No	Generation temperature
LLM_MAX_TOKENS	4096	No	Max output tokens
LLM_TIMEOUT_S	60	No	LLM request timeout in seconds

Vector index

Variable	Default	Description
HNSW_DIM	384	Embedding dimension — must match your embedding model
HNSW_M	16	HNSW M parameter — higher = better recall, more RAM
HNSW_EF_CONSTRUCTION	200	Build-time recall quality (higher = slower build, better index)
HNSW_EF_SEARCH	50	Query-time recall quality (higher = slower query, better recall)
AUTO_CONFIG	false	true = derive all HNSW + batch parameters from available RAM automatically (recommended for production)

AUTO_CONFIG

Setting AUTO_CONFIG=true enables CortexAutoConfig, which probes available RAM at startup and derives (M, ef_construction, batch_size) such that peak process RSS never exceeds 75% of available RAM. This is the recommended setting for production deployments.

KMS / Encryption at rest

Variable	Required	Description
KMS_PROVIDER	When encrypting	local | vault | aws | gcp | azure
KMS_KEY_ID	When provider is external	Provider-specific key identifier
VAULT_ADDR	Vault	HashiCorp Vault server URL
VAULT_TOKEN	Vault	Vault token
VAULT_CACERT	Vault (mTLS)	Vault CA certificate path
AWS_REGION	AWS	AWS region (e.g. us-east-1)
AWS_ACCESS_KEY_ID	AWS (key auth)	AWS access key ID
AWS_SECRET_ACCESS_KEY	AWS (key auth)	AWS secret access key
GOOGLE_APPLICATION_CREDENTIALS	GCP	Path to service account JSON
AZURE_TENANT_ID	Azure	Azure AD tenant ID
AZURE_CLIENT_ID	Azure	Azure app registration client ID
AZURE_CLIENT_SECRET	Azure	Azure app registration client secret

Multi-tenancy

Variable	Default	Description
TENANCY_MODE	shared	shared (key prefix per tenant) | dedicated (separate DB path per tenant)
TENANCY_DEDICATED_BASE	./data/tenants	Root directory for per-tenant DB paths (dedicated mode only)

DocIntel integration

Variable	Default	Description
DOCINTEL_BASE_URL	—	URL of the Purple8 DocIntel service (e.g. http://localhost:8200)
DOCINTEL_API_KEY	—	API key for the DocIntel service

WAL / durability

Variable	Default	Description
P8G_WAL_SYNC	true	true = fdatasync on every write (durable), false = async (faster, less durable)

JWT token TTL

Variable	Default	Description
JWT_ACCESS_TOKEN_EXPIRE_MINUTES	60	Access token TTL in minutes
JWT_REFRESH_TOKEN_EXPIRE_DAYS	30	Refresh token TTL in days

OpenTelemetry (optional)

Variable	Default	Description
OTEL_EXPORTER_OTLP_ENDPOINT	—	OTLP endpoint (e.g. http://jaeger:4317) — enables tracing when set
OTEL_SERVICE_NAME	purple8-graph	Service name reported to the OTEL collector