🔐 Environment Variables & Secrets Reference¶

Complete guide to configuring Spector via environment variables, container secrets, Java system properties, and low-level JVM runtime flags. Learn the canonical mapping rules, convenience aliases, and production security patterns.

🧭 Systematic Canonical Mapping Rule¶

Spector's configuration loader (SpectorConfigSource) automatically translates any configuration property from spector.yml into a canonical environment variable using three simple rules:

1. Prefix: Every property begins with SPECTOR_.
2. Path Replacement: Nested YAML dots (.) and kebab-case hyphens (-) become underscores (_).
3. Casing: All characters are converted to uppercase.

Canonical Mapping Examples¶

⚡ Convenience Aliases vs. Canonical Mappings¶

To simplify Docker commands, Kubernetes manifests, and CLI scripts, Spector's container entrypoint (entrypoint.sh) and Spring auto-configuration support short, memorable convenience aliases.

If an alias is defined and its canonical equivalent is empty, the alias value is automatically promoted to the canonical configuration key during startup:

🛡️ Docker Secrets Integration (/run/secrets/)¶

In production environments, storing sensitive credentials (such as OpenAI, Anthropic, or Azure API keys) in plain-text environment variables poses security risks (visible in docker inspect and /proc/$PID/environ).

Spector natively supports Docker Secrets and Kubernetes Secret volume mounts at /run/secrets/. During container startup, entrypoint.sh automatically detects and exports secrets mounted in this directory:

/run/secrets/
├── spector_embedding_api_key     → Exports to SPECTOR_EMBEDDING_API_KEY
├── spector_generation_api_key    → Exports to SPECTOR_GENERATION_API_KEY
├── spector_api_key               → Exports to SPECTOR_API_KEY
└── spector_auth_jwt_secret       → Exports to SPECTOR_AUTH_JWT_SECRET

Docker Compose Example with Secrets¶

version: '3.8'

services:
  spector:
    image: ghcr.io/spectrayan/spector:latest
    ports:
      - "8080:8080" # Cortex UI & API Proxy
      - "7070:7070" # Synapse REST API
    environment:
      - SPECTOR_EMBEDDING_PROVIDER=openai
      - SPECTOR_EMBEDDING_MODEL=text-embedding-3-small
      - SPECTOR_EMBEDDING_DIMS=1536
    secrets:
      - spector_embedding_api_key
      - spector_api_key
    volumes:
      - spector-data:/data

secrets:
  spector_embedding_api_key:
    file: ./secrets/openai_key.txt
  spector_api_key:
    file: ./secrets/spector_token.txt

volumes:
  spector-data:

☕ Java System Properties (-Dspector.*)¶

Any configuration key can be passed to the JVM runtime as a standard system property. System properties take precedence over environment variables:

java \
  --enable-preview --add-modules=jdk.incubator.vector --enable-native-access=ALL-UNNAMED \
  -Dspector.provider.embedding.dimensions=768 \
  -Dspector.memory.capacity=500000 \
  -Dspector.provider.embedding.type=ollama \
  -jar spector-synapse.jar

🚀 Mandatory JVM Panama & Vector API Flags¶

Spector leverages Java 23+ Project Panama (Foreign Function & Memory API - JEP 454) and the Vector API (JEP 448) to achieve zero-GC off-heap vector search with native SIMD instructions (AVX-512, AVX2, ARM Neon).

Because these features utilize incubator modules and off-heap memory access, the JVM must be launched with the following arguments:

--enable-preview --add-modules=jdk.incubator.vector --enable-native-access=ALL-UNNAMED

What Each Flag Does¶

🐧 Linux Kernel & OS-Level Tuning¶

When managing millions of vector records via memory-mapped off-heap segments (vectors.mmap), the host operating system's default memory-map and file-descriptor limits will cause OutOfMemoryError: Map failed or IOException: Too many open files if not adjusted.

Required Kernel Parameters¶

# /etc/sysctl.d/99-spector.conf
vm.max_map_count=262144
fs.file-max=1048576

Apply immediately on Linux host nodes:

sudo sysctl -w vm.max_map_count=262144
sudo sysctl -w fs.file-max=1048576

User Limit Configurations (/etc/security/limits.conf)¶

For bare-metal and systemd services, raise the process descriptor limits for the spector user:

spector soft nofile 65536
spector hard nofile 1048576
spector soft memlock unlimited
spector hard memlock unlimited

In Kubernetes environments, the official Spector Helm chart automatically applies vm.max_map_count and fs.file-max using a privileged initContainer. See the Deployment & Cloud Config Guide for full Helm values.