Installation

This guide explains how to download, install, verify, and run VCAL Semantic Cache v0.6.0 using Docker or a standalone Linux binary.

VCAL Semantic Cache requires a valid license file to start. A 30-day Trial license can be obtained self-serve via the CLI.

Prerequisites

Linux x86_64 or aarch64
Docker or standalone binary
A valid Trial, Growth, or Enterprise license, or an email address for self-serve Trial license activation
Optional: Prometheus and Grafana for monitoring
Optional: jq, curl, and sha256sum for checks and verification

Download VCAL Semantic Cache

VCAL Semantic Cache is distributed in two main ways:

Docker image from GitHub Container Registry (GHCR) — recommended for evaluation and most deployments.
Signed Linux binaries — useful for direct host installation, systemd services, or environments where Docker is not preferred.

Use Docker if you want the fastest evaluation path. Use standalone binaries if you prefer to run the server directly on a Linux host or under your own service manager.

The same release files may also be mirrored through the public releases repository for version history and verification:

https://github.com/vcal-project/vcal-server-releases/releases/

Docker image

Pull the pinned v0.6.0 image:

docker pull ghcr.io/vcal-project/vcal-server:v0.6.0

Or pull the latest published image:

docker pull ghcr.io/vcal-project/vcal-server:latest

For production deployments, prefer a pinned version such as v0.6.0 so deployments are reproducible.

The Docker installation flow is shown below in Option A — Docker.

Standalone binary packages

Standalone Linux builds are published as .tar.gz archives. Choose the archive that matches your target system:

Platform	Artifact pattern	Use when
Linux x86_64, glibc	`vcal-server-linux-x86_64-v0.6.0.tar.gz`	Standard x86_64 Linux distributions with glibc
Linux x86_64, musl	`vcal-server-linux-x86_64-musl-v0.6.0.tar.gz`	Minimal/static-friendly x86_64 environments
Linux aarch64, musl	`vcal-server-linux-aarch64-musl-v0.6.0.tar.gz`	ARM64 Linux servers or edge systems

Each binary archive is published together with:

a .sha256 checksum file;
a .minisig signature file.

Verification is optional for quick local testing, but recommended for production and customer deployments.

Release metadata and extra assets

The download page uses release metadata to expose the latest available files. The latest metadata endpoint is:

https://downloads.vcal-project.com/vcal-server/latest.json

You can inspect it with:

curl -fsSL https://downloads.vcal-project.com/vcal-server/latest.json | jq .

The release may also include extra assets such as:

VCAL_Server_User_Manual.md
grafana-dashboard.json
openapi.yml

Use these files when you need the offline user manual, a ready-to-import Grafana dashboard, or the OpenAPI definition for integration and review.

Verify a binary download

After downloading a binary archive and its .sha256 file, verify the checksum from the same directory:

sha256sum -c vcal-server-linux-x86_64.sha256

If your checksum file includes the version in the filename, use that exact filename instead.

The .minisig files can be used for signature verification when you have the VCAL release signing public key. Do not confuse the release signing key with the license verification public key used by VCAL Semantic Cache at runtime.

Option A — Docker

Docker is the fastest way to get started and is the recommended option for evaluation and production.

0. Create a persistent host directory

mkdir -p ./vcal-data

# If you see permission errors on Linux, the container runs as UID 10001:
sudo chown -R 10001:10001 ./vcal-data

This directory stores cache snapshots and, for trial setups, the generated license file.

1. Request a 30-day Trial license

Run the licensing command 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:v0.6.0 \
  license trial <your_email>

A verification code will be sent to your email.

2. Verify the code and write the license file

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:v0.6.0 \
  license verify <code>

If verification fails because the pending email state is missing, provide the email explicitly:

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:v0.6.0 \
  license verify <code> --email <your_email>

The license is written to:

./vcal-data/license.json

Confirm that the license file exists:

ls -la ./vcal-data
jq . ./vcal-data/license.json

3. Start VCAL Semantic Cache

docker run -d \
  --name vcal-server \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  --memory=2g \
  -v "$(pwd)/vcal-data:/var/lib/vcal" \
  -e VCAL_LICENSE_PATH=/var/lib/vcal/license.json \
  -e VCAL_DIMS=768 \
  -e VCAL_CAP_MAX_VECTORS=50000 \
  -e VCAL_TTL_SECS=2592000 \
  -e VCAL_AUTOSAVE_SECS=3600 \
  -e VCAL_AUTOSAVE_ATOMIC=1 \
  -e RUST_LOG=info \
  ghcr.io/vcal-project/vcal-server:v0.6.0

VCAL_CAP_MAX_VECTORS=50000 is used here because it is safer with a --memory=2g container limit than setting a large byte cap such as 8 GiB.

4. Health and readiness checks

curl -fsS http://127.0.0.1:8080/healthz && echo "OK"

If authentication is enabled, readiness requires a key:

curl -i \
  -H "X-VCAL-Key: <app_key>" \
  http://127.0.0.1:8080/readyz

Docker with an annual Growth / Enterprise license

If you already have a signed annual license file on the host, mount it into the container and point VCAL_LICENSE_PATH to the container path.

Example host layout:

/etc/vcal/license.json
/etc/vcal/license-pubkey.b64
/opt/vcal-data/
/opt/vcal-server/.env

Example command:

docker run -d \
  --name vcal-server \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  --memory=2g \
  -v /opt/vcal-data:/var/lib/vcal \
  -v /etc/vcal/license.json:/etc/vcal/license.json:ro \
  -v /etc/vcal/ed25519.pk.b64:/etc/vcal/license-pubkey.b64:ro \
  --env-file /opt/vcal-server/.env \
  -e VCAL_DIMS=768 \
  -e VCAL_CAP_MAX_VECTORS=50000 \
  -e VCAL_TTL_SECS=2592000 \
  -e VCAL_AUTOSAVE_SECS=3600 \
  -e VCAL_AUTOSAVE_ATOMIC=1 \
  -e VCAL_AUTH_REQUIRED=1 \
  -e VCAL_AUTH_HEADER=X-VCAL-Key \
  -e VCAL_LICENSE_PATH=/etc/vcal/license.json \
  -e VCAL_LICENSE_PUBKEY_FILE=/etc/vcal/license-pubkey.b64 \
  -e RUST_BACKTRACE=full \
  -e RUST_LOG=info \
  ghcr.io/vcal-project/vcal-server:v0.6.0

Avoid setting conflicting license variables such as:

VCAL_LICENSE_PATH=/var/lib/vcal/license.json
VCAL_LICENSE_FILE=/etc/vcal/annual-license.json

If both are set, make sure they point to the same actual file inside the container.

If your VCAL Semantic Cache build embeds the license verification public key, you do not need to mount license-pubkey.b64 or set VCAL_LICENSE_PUBKEY_FILE.

Option B — Standalone Binary

Use this option when you want to run VCAL Semantic Cache directly on a Linux host without Docker.

1. Download and unpack

Download the correct archive for your platform from the VCAL download page or release mirror.

For a standard x86_64 Linux host:

tar -xzf vcal-server-linux-x86_64-v0.6.0.tar.gz
chmod +x vcal-server

For x86_64 musl:

tar -xzf vcal-server-linux-x86_64-musl-v0.6.0.tar.gz
chmod +x vcal-server

For aarch64 musl:

tar -xzf vcal-server-linux-aarch64-musl-v0.6.0.tar.gz
chmod +x vcal-server

Optional system install:

sudo install -m 0755 vcal-server /usr/local/bin/vcal-server

2. Request a 30-day Trial license

User-writable location

export VCAL_LICENSE_PATH="$PWD/license.json"
./vcal-server license trial <your_email>

Stable user-level location

mkdir -p "$HOME/.vcal"
export VCAL_LICENSE_PATH="$HOME/.vcal/license.json"
./vcal-server license trial <your_email>

Use this approach if you want a stable license path that does not depend on the current working directory. If you open a new terminal later, set VCAL_LICENSE_PATH again before starting the server, or add it to your shell profile or service environment.

System-wide location

sudo mkdir -p /etc/vcal
sudo VCAL_LICENSE_PATH=/etc/vcal/license.json \
  VCAL_PENDING_EMAIL_PATH=/etc/vcal/pending_email.txt \
  ./vcal-server license trial <your_email>

3. Verify the code

User-writable license path:

./vcal-server license verify <code>

If verification fails because the pending email state is missing:

./vcal-server license verify <code> --email <your_email>

System-wide license path:

sudo VCAL_LICENSE_PATH=/etc/vcal/license.json \
  VCAL_PENDING_EMAIL_PATH=/etc/vcal/pending_email.txt \
  ./vcal-server license verify <code>

If verification fails because the pending email state is missing:

sudo VCAL_LICENSE_PATH=/etc/vcal/license.json \
  VCAL_PENDING_EMAIL_PATH=/etc/vcal/pending_email.txt \
  ./vcal-server license verify <code> --email <your_email>

4. Start VCAL Semantic Cache

For local testing without sudo, keep both the license and data directory under your home directory:

mkdir -p "$HOME/.vcal/data"

export VCAL_LICENSE_PATH="$HOME/.vcal/license.json"
export VCAL_DATA_DIR="$HOME/.vcal/data"
export VCAL_DIMS=768
export VCAL_AUTOSAVE_SECS=3600

./vcal-server

For a system-wide installation, create a system data directory and make sure it is writable by the user or service account running VCAL Semantic Cache:

sudo mkdir -p /var/lib/vcal/data
sudo chown -R "$USER:$USER" /var/lib/vcal

export VCAL_DATA_DIR=/var/lib/vcal/data
export VCAL_DIMS=768
export VCAL_AUTOSAVE_SECS=3600

./vcal-server

If you use a non-default license path, keep VCAL_LICENSE_PATH set in the same shell or service environment.

5. Health check

curl -fsS http://localhost:8080/healthz && echo "OK"

Production notes

VCAL Semantic Cache will not start without a valid license.
Trial licenses are time-limited.
Growth and Enterprise licenses are issued as signed JSON files.
License files, key files, and data directories must be readable by the VCAL Semantic Cache process.
Use pinned Docker tags such as v0.6.0 for reproducible production deployments.
Keep downloaded .sha256 and .minisig files with the matching archive for auditability.
v0.6.0 runtime snapshots are background-safe, while graceful shutdown still performs a final quiescent save.

Prerequisites​

Download VCAL Semantic Cache​

Docker image​

Standalone binary packages​

Release metadata and extra assets​

Verify a binary download​

Option A — Docker​

0. Create a persistent host directory​

1. Request a 30-day Trial license​

2. Verify the code and write the license file​

3. Start VCAL Semantic Cache​

4. Health and readiness checks​

Docker with an annual Growth / Enterprise license​

Option B — Standalone Binary​

1. Download and unpack​

2. Request a 30-day Trial license​

User-writable location​

Stable user-level location​

System-wide location​

3. Verify the code​

4. Start VCAL Semantic Cache​

5. Health check​

Production notes​