Self-host quickstart

You can run the whole thing yourself. This is the minimal single-user path — no multi-tenant auth, no cloud. You bring a Linux box with virtualization and your own AI key.

This is a quickstart map, not a line-by-line installer. Exact commands live in each published repo’s README on github.com/zkmkarlsruhe and in Install & deploy.

What you need

Linux with KVM/libvirt — the one hard dependency of the workbench core.
Your own AI — an OpenAI-compatible endpoint + key (cloud or a local Ollama/vLLM). See Bring your own AI.
For the autopsy service: Docker + Docker Compose (the easy path — it brings up PostgreSQL, the API and a runner for you). Autopsy’s own AI endpoint is optional: without one it produces a complete deterministic report; with one it adds the AI analyst.

See Dependencies for the full tiered picture.

1. The research workbench (rvmc), single-user

rvmc runs as one process — no database, no message broker; the one hard dependency is libvirt/qemu-KVM. For solo self-hosting, use local auth mode — a single owner, no Authentik, no OIDC, no auth database:

# get the workbench with its shared lib (vmctl-core) as a sibling submodule
git clone --recurse-submodules https://github.com/zkmkarlsruhe/vmctl
cd vmctl/research-vm-controller

# deps: libvirt + qemu/KVM on the host, plus Poetry and Node 20+
poetry install                      # installs vmctl-core (../vmctl-core path dep) + the controller
( cd web && npm ci && npm run build )   # builds the SPA into rvmc/static/ (served by the API)

# run in single-user mode: every request is the local owner, no Authentik, no login
RVMC_AUTH_MODE=local poetry run rvmc serve     # http://127.0.0.1:8000

That’s the keystone that makes rvmc fork-and-run. The default mode is forward (hardened multi-tenant behind a reverse proxy) — see Auth modes. Point it at your golden-image storage and your libvirt.

2. The autopsy service

Autopsy analyzes bundles as jobs. The easy path is Docker Compose — clone the superset recursively and bring the stack up (it provisions Postgres + the API + a runner for you):

git clone --recurse-submodules https://github.com/zkmkarlsruhe/vmctl.git
cd vmctl/artwork-autopsy
cp .env.example .env          # works as-is: default runs deterministic-only (no AI key needed)
docker compose up -d --build  # db (Postgres) + api + runner on http://localhost:8099

AI is optional. The default .env uses the sentinel key sk-nokey and produces a complete deterministic report (formats, run-graph, entry point, dead-endpoint flags) — no LLM calls. To add the AI analyst, set a reachable endpoint + real key in .env (AUTOPSY_LLM__BASE_URL, AUTOPSY_LLM__API_KEY, and the analysis/* aliases — see Bring your own AI).

Prefer bare processes? Run your own PostgreSQL, set AUTOPSY_JOBSTORE__DATABASE_URL, and start the API + a autopsy runner; or analyze one bundle without the queue via autopsy analyze --no-llm <zip>. See the autopsy README and Configuration reference.

3. Analyze and run

Upload an artwork (or point the CLI at a bundle), let the autopsy run — confirming the preflight checkpoint if it asks — then clone the suggested golden(s) in the workbench and boot the work.

Running fully offline

Use a local model (Ollama/vLLM) as your AI endpoint and everything stays on your machine — no external calls, no per-token cost. Golden images and captured archives are local too. This is the air-gapped conservation setup.