VCAL Server

VCAL Server is a production-grade semantic cache and memory layer for LLM apps — designed to cut repetitive token usage, latency, and cost by up to 60%, while keeping all data private and self-hosted (on-prem / VPC).

Powered by the open-source vcal-core, VCAL Server adds:

• REST API (/v1/* for app traffic, /admin/* for control)
• Automatic TTL/LRU eviction + snapshot autosave
• Prometheus metrics (/metrics)
• File-based authentication (key files)
• File-based licensing (signed license JSON)
• Signed binaries + Docker image
• Tiered licensing: Trial, Growth, Enterprise

---

Latest improvements

• Mandatory licensing

  • VCAL_LICENSE_FILE — signed license JSON (Trial / Growth / Enterprise)
  • VCAL_LICENSE_PUBKEY_FILE — vendor public key used for signature validation
  • (Optional) live reload via POST /admin/license/reload (if enabled)

• File-based authentication

  • VCAL_KEYS_APP_FILE — app keys for /v1/*
  • VCAL_KEYS_ADMIN_FILE — admin keys for /admin/*

• Similarity threshold control

  • VCAL_SIM_THRESHOLD — global cosine-similarity cutoff (requests can override via min_score)

• Snapshot reliability

  • Atomic paired writes (.tmp + rename)
  • Backward-compatible Envelope v1 format

---

Why VCAL Server

• No more costs for repeated LLM calls
• Millisecond cache hits
• Private, self-hosted, and recovery-friendly (data dir + license file)
• Drop-in HTTP API integration with existing LLM apps

---

Quickstart (Docker)

Trial licensing is self-serve via CLI (request a code, verify it, and VCAL writes a license file).
The server will not start without a valid license file.

# 0) Create a persistent host directory (data + license)
mkdir -p ./vcal-data

# If you see "Permission denied" on Linux (container runs as UID 10001):
sudo chown -R 10001:10001 ./vcal-data

# 1) Request a 30-day trial code (runs inside the image)
docker run --rm -it \
  -v "$(pwd)/vcal-data:/var/lib/vcal" \
  -e VCAL_LICENSE_PATH=/var/lib/vcal/license.json \
  ghcr.io/vcal-project/vcal-server:latest \
  license trial <your_email>

# 2) Verify the code and write the license file to ./vcal-data/license.json
docker run --rm -it \
  -v "$(pwd)/vcal-data:/var/lib/vcal" \
  -e VCAL_LICENSE_PATH=/var/lib/vcal/license.json \
  ghcr.io/vcal-project/vcal-server:latest \
  license verify <code>

# Confirm the license exists
ls -la ./vcal-data && jq . ./vcal-data/license.json

# 3) Start VCAL Server with the same persisted directory mounted
docker run --rm -p 8080:8080 \
  -v "$(pwd)/vcal-data:/var/lib/vcal" \
  -e VCAL_LICENSE_PATH=/var/lib/vcal/license.json \
  -e VCAL_DIMS=768 \
  -e VCAL_CAP_MAX_BYTES=8589934592 \
  -e RUST_LOG=info \
  ghcr.io/vcal-project/vcal-server:latest

# 4) Health check
curl -fsS http://localhost:8080/healthz && echo "OK"

Integrations

Component	Description
vcal-core	Rust library powering the semantic index and eviction logic
VCAL Server	REST service layer with licensing, persistence, and metrics
Grafana / Prometheus	Dashboards for latency, hit ratio, evictions, and savings
Helm chart	Kubernetes deployment
License system	Signed JSON validated via Ed25519 public key (optional live reload)

Next Steps

• See Installation for Docker, Binary, and Helm.
• Configure via Configuration
• Learn about Licensing
• Explore API Reference for /v1/* and /admin/*.