Skip to content

Configuration

Complete reference for all environment variables across HX-Gate and HX-Engine.

HX-Gate (HX_GATE_*)

Core

Variable Type Default Description
HX_GATE_HOST str 0.0.0.0 Bind address
HX_GATE_PORT int 8080 Bind port
HX_GATE_LOG_LEVEL str info Log level: debug, info, warning, error
HX_GATE_ENGINE_SERVICE_KEY str required API key for authenticating to HX-Engine. Min 32 characters.
HX_GATE_TENANT_REGISTRY_PATH str /etc/hx-gate/tenants.json Path to tenant registry JSON file
HX_GATE_CORS_ORIGINS str "" Comma-separated allowed CORS origins. Empty = CORS disabled

Rate limiting

Variable Type Default Description
HX_GATE_DEFAULT_RATE_LIMIT_REQUESTS int 100 Max requests per window per tenant
HX_GATE_DEFAULT_RATE_LIMIT_WINDOW_S int 60 Sliding window duration in seconds

Stripe billing

Variable Type Default Description
HX_GATE_BILLING_ENABLED bool false Enable Stripe billing enforcement
HX_GATE_STRIPE_SECRET_KEY str "" Stripe secret key (sk_live_... or sk_test_...)
HX_GATE_STRIPE_PUBLISHABLE_KEY str "" Stripe publishable key (pk_live_... or pk_test_...)
HX_GATE_STRIPE_WEBHOOK_SECRET str "" Stripe webhook signing secret (whsec_...)
HX_GATE_STRIPE_PRICE_BUILDER str "" Stripe Price ID for Builder tier ($49/mo)
HX_GATE_STRIPE_PRICE_PRO str "" Stripe Price ID for Pro tier ($299/mo)

Audit & observability

Variable Type Default Description
HX_GATE_AUDIT_ENABLED bool true Write JSONL audit log for all operations
HX_GATE_AUDIT_LOG_PATH str /var/log/hx-gate/audit.jsonl Audit log file path
HX_GATE_METRICS_ENABLED bool true Expose Prometheus metrics at /metrics

Redis

Variable Type Default Description
HX_GATE_REDIS_URL str "" Redis URL for multi-instance shared state (e.g., redis://redis:6379/0). Empty = in-memory mode (single instance only)

HX-Engine (HOLONOMIX_*)

Server

Variable Type Default Description
HOLONOMIX_API_HOST str 127.0.0.1 Bind address
HOLONOMIX_API_PORT int 8400 Bind port
HOLONOMIX_WORKERS int 1 Gunicorn worker count (1–64)
HOLONOMIX_LOG_LEVEL str info Log level: debug, info, warning, error

Storage

Variable Type Default Description
HOLONOMIX_STORE_ROOT str ./holonomix_data Root directory for QTT-native data storage
HOLONOMIX_DEFAULT_NAMESPACE str default Default namespace
HOLONOMIX_COMPACTION_RETENTION_S float 2592000 Tombstone retention before compaction (30 days)
HOLONOMIX_MAX_UPLOAD_BYTES int 104857600 Max upload payload (100 MB)

Compression

Variable Type Default Description
HOLONOMIX_MAX_RANK int 16 Maximum TT bond dimension (1–4096)
HOLONOMIX_COMPRESSION_TOL float 1e-8 TT-SVD truncation tolerance
HOLONOMIX_MIN_VALUE_BYTES int 64 Minimum value size to attempt compression. 0 = compress all
HOLONOMIX_MIN_COMPRESSION_RATIO float 1.2 Minimum compression ratio threshold. Below this → passthrough
HOLONOMIX_PASSTHROUGH_ON_ERROR bool true Store uncompressed on compression error (true) or propagate (false)
HOLONOMIX_DEFAULT_DOMAIN str structured_data Default domain key for Oracle

Authentication

Variable Type Default Description
HOLONOMIX_REQUIRE_AUTH bool false Enforce API-key auth on all endpoints
HOLONOMIX_API_KEYS str "" Comma-separated valid API keys (≥32 chars each)
HOLONOMIX_ADMIN_API_KEYS str "" Admin keys with stats/intelligence/compaction access

CORS

Variable Type Default Description
HOLONOMIX_CORS_ORIGINS str "" Comma-separated allowed origins. Empty = disabled
HOLONOMIX_CORS_ALLOW_CREDENTIALS bool true Allow credentials in CORS
HOLONOMIX_CORS_ALLOW_METHODS str GET,POST,PUT,DELETE Allowed HTTP methods
HOLONOMIX_CORS_ALLOW_HEADERS str * Allowed request headers

Rate limiting

Variable Type Default Description
HOLONOMIX_RATE_LIMIT_ENABLED bool false Enable per-key rate limiting
HOLONOMIX_RATE_LIMIT_REQUESTS int 100 Max requests per window per key
HOLONOMIX_RATE_LIMIT_WINDOW_S int 60 Rate limit window in seconds

TLS

Variable Type Default Description
HOLONOMIX_TLS_CERT_PATH str None TLS certificate (PEM). None = plain HTTP
HOLONOMIX_TLS_KEY_PATH str None TLS private key (PEM)

Observability

Variable Type Default Description
HOLONOMIX_METRICS_ENABLED bool true Expose Prometheus metrics at /metrics

Example: minimal production .env

# Gate
HX_GATE_ENGINE_SERVICE_KEY=change-me-to-a-random-32-char-string-or-longer
HX_GATE_CORS_ORIGINS=https://app.example.com
HX_GATE_REDIS_URL=redis://redis:6379/0

# Engine
HOLONOMIX_STORE_ROOT=/var/lib/holonomix/data
HOLONOMIX_REQUIRE_AUTH=true
HOLONOMIX_API_KEYS=${HX_GATE_ENGINE_SERVICE_KEY}
HOLONOMIX_ADMIN_API_KEYS=${HX_GATE_ENGINE_SERVICE_KEY}
HOLONOMIX_MAX_RANK=32

Example: SaaS with billing

# Gate
HX_GATE_ENGINE_SERVICE_KEY=long-random-service-key-here
HX_GATE_BILLING_ENABLED=true
HX_GATE_STRIPE_SECRET_KEY=sk_live_...
HX_GATE_STRIPE_PUBLISHABLE_KEY=pk_live_...
HX_GATE_STRIPE_WEBHOOK_SECRET=whsec_...
HX_GATE_STRIPE_PRICE_BUILDER=price_...
HX_GATE_STRIPE_PRICE_PRO=price_...
HX_GATE_CORS_ORIGINS=https://holonomx.com,https://app.holonomx.com
HX_GATE_REDIS_URL=redis://redis:6379/0

# Engine
HOLONOMIX_STORE_ROOT=/var/lib/holonomix/data
HOLONOMIX_REQUIRE_AUTH=true
HOLONOMIX_API_KEYS=${HX_GATE_ENGINE_SERVICE_KEY}
HOLONOMIX_ADMIN_API_KEYS=${HX_GATE_ENGINE_SERVICE_KEY}
HOLONOMIX_MAX_RANK=32
HOLONOMIX_METRICS_ENABLED=true