Configuration
VCAL Semantic Cache is configured through environment variables or an optional .env file.
If a variable is not set, the documented default is used.
For production deployments, prefer a
.envfile, systemd environment overrides, Docker secrets, or mounted key files over inline secrets.
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 when no snapshot exists. | — |
VCAL_M | HNSW graph out-degree | 32 |
VCAL_EF_SEARCH | HNSW search parameter | 128 |
VCAL_SIM_THRESHOLD | Global similarity cutoff used by search/QA when a request does not override it | 0.80 |
VCAL_DATA_DIR | Persistent data directory for index, answers, and tombstones | ./data |
Capacity & Eviction
| Variable | Description | Default |
|---|---|---|
VCAL_CAP_MAX_BYTES | Max cache size before LRU eviction. Use values appropriate for the container memory limit. | — |
VCAL_CAP_MAX_VECTORS | Max vector count before LRU eviction | — |
VCAL_TTL_SECS | Default TTL for cache entries, in seconds | — |
VCAL_EVICT_EVERY_SECS | Interval between eviction sweeps | 30 |
If both byte and vector limits are set, eviction can trigger when either limit is reached. For Docker deployments with small memory limits, VCAL_CAP_MAX_VECTORS is often safer and easier to reason about than a large byte cap.
Persistence / Snapshots
| Variable | Description | Default |
|---|---|---|
VCAL_AUTOSAVE_SECS | Autosave interval for paired snapshots. 0 disables autosave. | 300 |
VCAL_AUTOSAVE_ATOMIC | Write snapshots atomically using temporary files and rename | 1 |
VCAL Semantic Cache v0.6.0 persists the paired snapshot set:
vcal.index
answers.json
tombstones.json
Runtime autosave and manual /v1/snapshot/save are background-safe:
capture consistent in-memory bundle under read lock
release read lock
write files without entering drain mode
Graceful shutdown still uses the quiescent save path:
enter drain mode
wait for in-flight requests
save final paired snapshot
exit
Snapshots are compatible within the supported release family, but old pre-envelope snapshots may need to be archived or migrated before startup.
Authentication & Authorization
| Variable | Description | Default |
|---|---|---|
VCAL_AUTH_REQUIRED | Require API keys for protected endpoints | 0 |
VCAL_AUTH_HEADER | HTTP header used for API keys | x-vcal-key |
VCAL_KEYS_APP | Comma-separated app keys for data-plane endpoints | — |
VCAL_KEY_APP | Legacy single app key variable | — |
VCAL_KEYS_ADMIN | Comma-separated admin keys for management endpoints | — |
VCAL_KEYS_APP_FILE | File containing app keys, one per line | — |
VCAL_KEYS_ADMIN_FILE | File containing admin keys, one per line | — |
VCAL_ALLOW_METRICS_WITHOUT_AUTH | Allow /metrics without authentication | 0 |
Protected endpoint behavior when authentication is enabled:
/healthzremains public./readyzrequires a valid app or admin key.- Data-plane routes such as
/v1/search,/v1/qa,/v1/insert,/v1/upsert, and/v1/deleterequire an app or admin key. - Management routes such as
/v1/snapshot/saveand/v1/license/statusrequire an admin key.
Licensing Required
VCAL Semantic Cache will not start without a valid license.
| Variable | Description | Default |
|---|---|---|
VCAL_LICENSE_JSON | Inline signed license JSON | — |
VCAL_LICENSE_PATH | Path to signed license JSON file | /etc/vcal/license.json |
VCAL_LICENSE_FILE | Alternate path to signed license JSON file | — |
VCAL_DOCKER_LICENSE_PATH | Docker-specific license path override | — |
VCAL_LICENSE_PUBKEY_FILE | Optional Ed25519 public key override | bundled/default |
Avoid setting multiple license path variables to different files. If both VCAL_LICENSE_PATH and VCAL_LICENSE_FILE are set, make sure they point to the same license or remove the unused variable.
Limits / Middleware
| Variable | Description | Default |
|---|---|---|
VCAL_RATE_QPS | Global request rate limit. 0 disables it. | 0 |
VCAL_RATE_WINDOW_SECS | Rate-limit window size | 1 |
VCAL_TIMEOUT_SECS | Per-request timeout in seconds | 30 |
VCAL_CONCURRENCY | Max concurrent requests. 0 means unlimited. | 0 |
Metrics / Observability
| Variable | Description | Default |
|---|---|---|
VCAL_PROM_ENABLED | Enable Prometheus /metrics endpoint | 1 |
VCAL_TOKENS_PER_HIT | Estimated tokens saved per cache hit | 0 |
RUST_LOG | Runtime log level used by tracing/logging | info |
RUST_BACKTRACE | Backtrace mode for diagnostics | — |
Example .env
VCAL_BIND=0.0.0.0:8080
VCAL_DIMS=768
VCAL_M=32
VCAL_EF_SEARCH=128
VCAL_SIM_THRESHOLD=0.80
VCAL_DATA_DIR=/var/lib/vcal/data
VCAL_CAP_MAX_VECTORS=50000
VCAL_TTL_SECS=2592000
VCAL_EVICT_EVERY_SECS=60
VCAL_AUTOSAVE_SECS=3600
VCAL_AUTOSAVE_ATOMIC=1
VCAL_AUTH_REQUIRED=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_ALLOW_METRICS_WITHOUT_AUTH=1
VCAL_LICENSE_PATH=/etc/vcal/license.json
VCAL_LICENSE_PUBKEY_FILE=/etc/vcal/ed25519.pk.b64
RUST_LOG=info
RUST_BACKTRACE=full
Notes
- All key and license files must be readable by the VCAL Semantic Cache process.
- For Docker, remember that paths in environment variables are container paths, not host paths.
- For production deployments, avoid committing secrets, API keys, license files, or private signing keys into source control.