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 | Description |
|---|---|---|
PURPLE8_HOST | 0.0.0.0 | Interface the REST server binds to |
PURPLE8_PORT | 8010 | TCP port |
DATA_DIR | ./graph_data | Root directory for graph storage |
WORKERS | 1 | Number of Uvicorn worker processes |
LOG_LEVEL | info | debug / info / warning / error |
Authentication
| Variable | Default | Required | Description |
|---|---|---|---|
JWT_SECRET | — | Yes | HMAC-SHA256 signing secret — must be ≥32 random bytes in production |
JWT_EXPIRY_SECONDS | 3600 | No | Access token TTL (seconds) |
JWT_REFRESH_EXPIRY_SECONDS | 86400 | No | Refresh token TTL (seconds) |
ADMIN_EMAIL | — | Yes | Email for the admin user created on first start |
ADMIN_PASSWORD | — | Yes | Password for the admin user created on first start |
JWT_SECRET
Never use the default or a short secret in production. Generate one with:
bash
python -c "import secrets; print(secrets.token_hex(32))"Vector index
| Variable | Default | Description |
|---|---|---|
P8G_VECTOR_BACKEND | hnswlib | hnswlib (in-memory HNSW) or diskann (on-disk, low memory) |
P8G_VECTOR_QUANTIZATION | — | int8 (4× compression) or binary (32× compression, approximate) |
P8G_VECTOR_CACHE_TTL | 300 | Seconds to keep decoded vectors in the read cache |
P8G_INDEX_DEFERRED | false | Skip HNSW index updates during write (set true for bulk ingestion, then rebuild) |
HNSW tuning (hnswlib backend)
| Variable | Default | Description |
|---|---|---|
P8G_HNSW_M | 16 | HNSW M parameter — higher = better recall, more RAM |
P8G_HNSW_EF_CONSTRUCTION | 200 | Build-time recall quality (higher = slower build, better index) |
P8G_HNSW_EF_SEARCH | 50 | Search-time recall quality (higher = slower query, better recall) |
DiskANN tuning (diskann backend)
| Variable | Default | Description |
|---|---|---|
P8G_DISKANN_R | 64 | Graph degree bound |
P8G_DISKANN_L | 100 | Search list size |
P8G_DISKANN_ALPHA | 1.2 | Pruning slack parameter |
Graph engine
| Variable | Default | Description |
|---|---|---|
P8G_TRAVERSAL_CACHE_SIZE | 1000 | LRU cache entries for graph traversal results |
P8G_TRAVERSAL_CACHE_TTL | 60 | TTL (seconds) for cached traversal results |
P8G_MAX_TRAVERSAL_DEPTH | 10 | Hard cap on MATCH variable-length path depth |
P8G_WAL_SYNC | true | true = fsync on every write (durable), false = async (faster, less durable) |
KMS / encryption
| Variable | Required | Description |
|---|---|---|
KMS_PROVIDER | When encrypting | local / vault / aws / gcp / azure |
KMS_KEY_ID | When encrypting | Provider-specific key identifier |
KMS_LOCAL_KEYSTORE | Local only | Path to JSON keystore file |
VAULT_ADDR | Vault only | HashiCorp Vault server URL |
VAULT_TOKEN | Vault only | Vault token |
VAULT_CACERT | Vault (mTLS) | Vault CA certificate path |
AWS_REGION | AWS only | 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 (SA auth) | 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 |
AZURE_USE_MSI | Azure (MSI) | Use Managed Identity instead of client secret |
Multi-tenancy
| Variable | Default | Description |
|---|---|---|
P8G_MULTI_TENANT | false | Route requests to per-tenant engine instances |
P8G_TENANT_DATA_ROOT | ./data/tenants | Root directory for per-tenant data directories |
Cluster / sharding
| Variable | Default | Description |
|---|---|---|
P8G_CLUSTER_MODE | false | Enable distributed sharding mode |
SHARD_ID | — | This instance's shard index (e.g. 0, 1, 2) |
SHARD_PEERS | — | Comma-separated host:port list of peer shards |
Journeys / AI
| Variable | Default | Description |
|---|---|---|
P8G_JOURNEY_SLA_POLL_INTERVAL | 30 | How often (seconds) the SLA monitor checks for breaches |
P8G_AI_ADVISOR_PROVIDER | — | Default LLM provider for JourneyAIAdvisor (openai / anthropic / google / mistral / cohere / ollama) |
LLM providers
| Variable | Description |
|---|---|
OPENAI_API_KEY | OpenAI API key |
ANTHROPIC_API_KEY | Anthropic API key |
GOOGLE_API_KEY | Google Gemini API key |
MISTRAL_API_KEY | Mistral AI API key |
COHERE_API_KEY | Cohere API key |
OLLAMA_BASE_URL | Ollama server URL (default: http://localhost:11434) |
OLLAMA_MODEL | Ollama model name (e.g. llama3.1) |
P8G_EMBEDDING_MODEL | Default embedding model (e.g. all-MiniLM-L6-v2) |
Sample .env for local development
bash
# Auth
JWT_SECRET=dev-secret-change-me
ADMIN_EMAIL=admin@localhost
ADMIN_PASSWORD=changeme
# Storage
DATA_DIR=./graph_data
LOG_LEVEL=debug
# Vector
P8G_VECTOR_BACKEND=hnswlib
# LLM (optional)
OPENAI_API_KEY=sk-...Sample .env for production (AWS)
bash
# Auth — generate with: python -c "import secrets; print(secrets.token_hex(32))"
JWT_SECRET=<64-hex-chars>
ADMIN_EMAIL=ops@acme.com
ADMIN_PASSWORD=<strong-password>
# Storage
DATA_DIR=/mnt/data/graph
WORKERS=4
LOG_LEVEL=info
# Vector
P8G_VECTOR_BACKEND=diskann
P8G_VECTOR_QUANTIZATION=int8
# KMS
KMS_PROVIDER=aws
KMS_KEY_ID=arn:aws:kms:us-east-1:123456789012:key/mrk-abc123
AWS_REGION=us-east-1
# Credentials via IAM instance role — no keys needed here
# Multi-tenancy
P8G_MULTI_TENANT=true
P8G_TENANT_DATA_ROOT=/mnt/data/tenants