Install VerifAIer

Getting started

Install VerifAIer

VerifAIer runs entirely inside your own environment. You install a small FastAPI service that exposes the twelve governance APIs on port 8000, plus two optional dashboards. There is no cloud dependency and no telemetry, nothing calls home.

Supported platforms

• Linux (x86-64, arm64), recommended for servers.
• macOS (Apple Silicon & Intel), for local development.
• Windows 10/11: natively or via WSL2.
• Docker on any of the above, the fastest, most reproducible path.

Prerequisites

• Python 3.12 (python --version), the version continuous integration runs and the dependency lock is generated for. 3.13 and 3.14 have been installed and exercised by hand; 3.11 and below are refused by the project's own requires-python. Newer interpreters are untested rather than known-broken.
• pip and a virtual environment tool (venv).
• The VerifAIer source distribution (provided with your evaluation).
• Optional: Docker 24+ with the Compose v2 plugin for the container path.

Option A, Docker (recommended)

The most reproducible install. From the VerifAIer distribution root:

# 1. Provide provider config (safe defaults; no keys required to start)
cp .env.example .env

# 2. Build and start the API (+ dashboards) in the background
docker compose up -d --build

# 3. Watch it become healthy
docker compose ps

This starts three services:

Sign in and open http://localhost:8000/app: the authenticated workspace, where every trust, evidence and governance surface is reachable from one navigation.

Option B, Local (from source)

For development, run the API directly with Python 3.12+:

# 1. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate        # macOS/Linux
.\.venv\Scripts\Activate.ps1    # Windows PowerShell

# 2. Install VerifAIer and its dependencies
pip install -e .

# 3. Provide provider config
cp .env.example .env

# 4. Start the API (the app lives under src/)
PYTHONPATH=src uvicorn vailidator.api.routes:app --host 0.0.0.0 --port 8000
# Windows PowerShell: $env:PYTHONPATH="src"; uvicorn vailidator.api.routes:app --port 8000

First startup

On a successful start you will see uvicorn bind to the port:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Verify it is healthy

Hit the health endpoint, it returns HTTP 200 and the running version:

curl http://localhost:8000/health

# Expected response
{
  "status": "ok",
  "version": "1.4.2"
}

You now have a running evidence engine. Next, wire a provider and run your first audit in the Quickstart.

Troubleshooting

Port 8000 is already in use

Choose another port: add --port 8080 to the uvicorn command, or change the ports mapping in docker-compose.yml.

ModuleNotFoundError: vailidator

The application package lives under src/. Ensure PYTHONPATH=src is set (the Docker image handles this for you).

uvicorn: command not found

Your virtual environment is not active, or dependencies were not installed. Re-activate it and run pip install -e ..

Requires Python 3.12+

Install a newer interpreter; VerifAIer targets Python 3.12 and above.

Docker build fails on the source copy

Run the build from the distribution root (where pyproject.toml and src/ live), and ensure the Compose v2 plugin is present: docker compose version.

No .env file

Copy the template with cp .env.example .env. The service starts with safe defaults (mock provider) even with no API keys.

Upgrade path

VerifAIer stores data in an on-disk SQLite database (a Docker volume, db_data, in the container path), so upgrades preserve your data.

# Docker
docker compose pull        # or: git pull
docker compose up -d --build

# Local (from source)
git pull
pip install -e .
# restart uvicorn