Skip to content
vmctl

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. rvmc (§1) is roadmap — not yet published; its command names below are illustrative and tracked on vmctl.org.

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

Roadmap — not yet published. rvmc’s first end-to-end revival against a real work has not been proven yet, so its code is not in the public release. This section describes the intended single-user setup; follow its progress on vmctl.org. Want something you can run today? Skip to §2 — the autopsy service.

rvmc runs as one process. For solo self-hosting, use local auth mode — a single owner, no Authentik, no OIDC, no auth database:

Terminal window
RVMC_AUTH_MODE=local rvmc serve

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. rvmc’s code and its specifics are tracked on vmctl.org until its first end-to-end revival is proven.

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):

Terminal window
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.

Where to go deeper