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:8084 |
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.1 persists the paired snapshot set:
vcal.index
answers.json
tombstones.json
At startup, VCAL Semantic Cache validates that the configured data directory is usable and checks restored snapshot dimensions against VCAL_DIMS.
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
Startup restores the paired snapshot set only when the persisted files are valid. Corrupt or incompatible companion files should be treated as startup errors rather than silently ignored.
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.
Runtime Entitlement
VCAL Semantic Cache will not start without a valid license.
The license and, where required, its verification public key are supplied by VCAL with the approved AI Cost Firewall deployment package. There is no public self-service issuance flow.
| 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:8084
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.