Configuration
VCAL Server is configured entirely via environment variables or an optional .env file.
If a variable is not set, the documented default is used.
Tip: For production deployments, prefer a
.envfile or systemd environment overrides over inline variables.
Core / Index
| Variable | Description | Default |
|---|---|---|
VCAL_BIND | Address and port to bind the HTTP server | 0.0.0.0:8080 |
VCAL_DIMS | Vector dimensionality (required if no snapshot exists) | — |
VCAL_M | HNSW graph out-degree (recall vs memory trade-off) | 32 |
VCAL_EF_SEARCH | HNSW search parameter (ef) | 128 |
VCAL_SIM_THRESHOLD | Global cosine similarity cutoff used by /v1/search and /v1/qa. Can be overridden per request via min_score. | 0.80 |
VCAL_DATA_DIR | Persistent data directory (index, answers, snapshots) | ./data |
Capacity & Eviction
| Variable | Description | Default |
|---|---|---|
VCAL_CAP_MAX_BYTES | Max in-memory size before LRU eviction (e.g. 512M, 8G) | — |
VCAL_CAP_MAX_VECTORS | Max vector count before LRU eviction | — |
VCAL_TTL_SECS | Default TTL for cache entries (seconds) | — |
VCAL_EVICT_EVERY_SECS | Interval between eviction sweeps | 30 |
If both byte and vector limits are set, eviction triggers on whichever limit is reached first.
Persistence / Snapshots
| Variable | Description | Default |
|---|---|---|
VCAL_AUTOSAVE_SECS | Autosave interval for index + payloads (0 = disabled) | 300 |
VCAL_AUTOSAVE_ATOMIC | Write snapshots atomically (temp + rename) | 1 |
VCAL_SNAPSHOT_COMPRESSION | Snapshot compression mode (auto, on, off) | auto |
Snapshots are forward-compatible within the same major version.
Authentication & Authorization
| Variable | Description | Default |
|---|---|---|
VCAL_AUTH_HEADER | HTTP header used for API keys | x-vcal-key |
VCAL_KEYS_APP_FILE | File containing app keys (data-plane /v1/* routes) | — |
VCAL_KEYS_ADMIN_FILE | File containing admin keys (/admin/* routes) | — |
VCAL_ALLOW_METRICS_WITHOUT_AUTH | Allow /metrics without authentication | 0 |
VCAL_API_BASE | Base path for data-plane endpoints | /v1 |
Recommended: Use key files rather than embedding secrets directly in environment variables.
Licensing (Required)
VCAL Server will not start without a valid license.
| Variable | Description | Default |
|---|---|---|
VCAL_LICENSE_FILE | Path to active license JSON file (Trial / Growth / Enterprise) | — |
The license file is:
- Cryptographically signed by the vendor
- Validated at startup
- Periodically revalidated at runtime
Startup fails if the license is missing, invalid, or expired.
Limits / Middleware
| Variable | Description | Default |
|---|---|---|
VCAL_RATE_QPS | Global request rate limit (0 = disabled) | 0 |
VCAL_RATE_WINDOW_SECS | Rate-limit window size | 1 |
VCAL_TIMEOUT_SECS | Per-request timeout (seconds) | 30 |
VCAL_CONCURRENCY | Max concurrent requests (0 = unlimited) | 0 |
Metrics / Observability
| Variable | Description | Default |
|---|---|---|
VCAL_PROM_ENABLED | Enable Prometheus /metrics endpoint | 1 |
VCAL_LOG_LEVEL | Log verbosity (error, warn, info, debug, trace) | info |
VCAL_TOKENS_PER_HIT | Estimated tokens saved per cache hit (ROI metrics) | 0 |
Example .env
VCAL_BIND=0.0.0.0:8080
VCAL_DIMS=1536
VCAL_M=32
VCAL_EF_SEARCH=128
VCAL_SIM_THRESHOLD=0.80
VCAL_DATA_DIR=/var/lib/vcal/data
VCAL_CAP_MAX_BYTES=2G
VCAL_TTL_SECS=2592000
VCAL_EVICT_EVERY_SECS=60
VCAL_AUTOSAVE_SECS=300
VCAL_AUTOSAVE_ATOMIC=1
VCAL_AUTH_HEADER=x-vcal-key
VCAL_KEYS_APP_FILE=/opt/vcal-server/app.keys
VCAL_KEYS_ADMIN_FILE=/opt/vcal-server/admin.keys
VCAL_LICENSE_FILE=/etc/vcal/license.json
VCAL_PROM_ENABLED=1
VCAL_LOG_LEVEL=info
VCAL_TIMEOUT_SECS=30
VCAL_ALLOW_METRICS_WITHOUT_AUTH=1
Notes
VCAL_SIM_THRESHOLDis global but can be overridden per request.- All key and license files must be readable by the VCAL Server process.
- For production deployments, avoid committing secrets or keys into source control.