These tests answer one practical question: can Aperio install, load its native modules, create SQLite, start HTTP, and serve the setup page somewhere that has none of your developer baggage?
Run these from the repository root. Keep the terminal open: a passing run prints checkmarks; a failed run prints the evidence-log path.
.git.prlctl.vms/out/. They are private, ignored by Git, and are the first place to look after a red run.node_modules is never copied into a VM.Click a card to jump to its prerequisites and exact command. You normally run one path, not all four.
Build a local Docker image and verify it boots in an isolated container. Best for a quick smoke test after a code or image change.
On Apple silicon, install into a fresh Ubuntu or Debian ARM64 guest. Best for checking native npm dependencies and the installer lifecycle.
Run the installer inside a clean macOS or Windows ARM guest. Best before calling a one-click desktop install ready.
Run the shared health checklist against an existing Aperio folder. Best for checking startup without creating a VM or rebuilding an image.
Choose the workflow that matches the question you have. Docker is the quickest check; Linux tests a fresh command-line installation; desktop guests test the one-click experience; and the shared checklist verifies an installation you already have. Every workflow ends by checking Node/npm, native modules, SQLite migration, an HTTP bootstrap response, /setup.html, and runtime hygiene.
Use this when you want a quick answer to “does the current checkout build and start?” Docker packages Aperio in a disposable container, so it does not change your normal installation.
/api/bootstrap/state, checks /setup.html, then removes the container and volume. A pass proves only that the image built, started, and served the setup page—not that local-AI setup or chat completed.To debug the disposable test with a known port or a longer readiness window:
/api/bootstrap/state once per second while the container starts. The default is 90 attempts, or about 90 seconds; 180 allows about three minutes. Use it only when Docker is slow to start or pull the image. It does not make Aperio faster.Use this path when you want to open the setup wizard, download a model, chat, and keep your data between restarts. Start Docker Desktop, open a terminal in the Aperio repository folder, and use the Copy button to copy the complete block:
Docker prints a long container ID when it starts successfully. Open http://127.0.0.1:31338/setup in your browser. Docker cannot open the page for you.
To watch what Aperio is doing, run the command below in another terminal. Press Ctrl+C to stop watching the log; this does not stop Aperio.
Stop Aperio when you are finished for now. Start the same container later; your setup, database, engine, and downloaded model remain in the named volume:
aperio-local is already in use: do not run another copy. Use docker start aperio-local. If it says port 31338 is already allocated, either stop the program using that port or change only the left side to -p 127.0.0.1:31339:31337, then open http://127.0.0.1:31339/setup.Removing the container does not remove the named volume. This is useful after rebuilding the image: remove the old container, repeat the docker run block above, and Aperio reuses its model and database.
The disposable runner never pulls a missing local tag. Published images must be passed as a complete registry reference, preferably a digest. The <digest> part below is a placeholder:
Find published versions and their digests on GitHub Packages — Aperio. Use :latest for the newest image; use @sha256:... when you need to reproduce one exact image.
Use this when you need to know whether a new Linux user can install Aperio from a clean computer. Ubuntu tests the one-line installer; Debian tests the developer-style Git and npm setup.
APERIO_BRANCH=my-branch before the command to test another branch. A passing result means the clean Linux machine completed the intended installation path.Use these commands before releasing the macOS or Windows one-click installer. They start from a clean desktop machine and run the installer as a normal user would.
vagrant global-status and VAGRANT_CWD="$PWD/vms" vagrant status. Destroy only the selected profile, for example VAGRANT_CWD="$PWD/vms" vagrant destroy -f ubuntu-lite.Use this when Aperio is already installed in a target folder and you only want to verify that it starts correctly. It does not create a virtual machine or test the installer; it runs the common health checks directly against the folder you provide.
package.json, node_modules, server.js, db/, and public/. It writes temporary database state under that target's .sqlite/; use a disposable copy if the target contains important data.vms/?Think of the folder as a test bench: a host remote control, a clean-machine procedure, one shared checklist, and private evidence.
| Path | Role | Touch it when… |
|---|---|---|
run-vagrant.sh | Host launcher. Selects ubuntu-lite or debian-dev, starts Vagrant, records output, and destroys the guest. | You need a different branch or Linux profile. |
Vagrantfile | Machine definition and provisioning: ARM64 box, 4 GB RAM, 2 CPUs, rsync exclusions, and the commands run inside each guest. | You are changing what a clean Linux install means. |
smoke.shsmoke.ps1 | Platform-neutral acceptance checklist. It does not create a VM; it proves an already-staged install works. | You add a critical install/runtime assertion. |
docker/run.sh | Build-output checker. Creates a temporary container and volume, tests HTTP/UI, captures metadata, and cleans up. | You are validating a Docker image. |
mac/, win/ | Desktop host and guest launchers. They stage files read-only, run the real installer, collect logs, and clean up. | You are testing the installer on a clean desktop OS. |
out/ | Timestamped host logs. These may contain private paths and runtime details. | A run fails. Read, redact, and never commit them. |
Docker and Vagrant are self-contained. Desktop workflows need a pristine machine because they test the real installer, not just the application after npm install.
aperio-mac-pristineCreate an Apple-silicon macOS guest, finish account setup, install Parallels Tools, confirm /Volumes/psf/ works, and do not install Node or Aperio. Shut it down and name it aperio-mac-pristine. Each run makes and deletes a linked clone named aperio-mac-run.
aperio-win-testCreate a Windows 11 ARM VM, finish setup, install Parallels Tools, create an administrator test user, and do not install Node or Aperio. Shut it down and create the snapshot used by the runner:
Vagrant downloads the selected ARM64 box the first time. The recipe maps the checkout to /vagrant-repo but excludes host dependencies, runtime data, SQLite state, and old logs. Do not hand-edit the guest to “fix” a test.
The runner changes the environment; the smoke contract asks Aperio the same questions everywhere.
| Check | What it proves | Typical output |
|---|---|---|
| Toolchain | Node 22+, npm, and dependencies are available in the target. | ✔ toolchain |
| Native modules | better-sqlite3, sqlite-vec, and sharp load for this OS/architecture. | ✔ native module |
| SQLite | A fresh install can create its schema. | ✔ SQLite migrations |
| HTTP + UI | The server answers bootstrap state and serves /setup.html. | ✔ HTTP bootstrap · ✔ UI shell |
| Hygiene | Temporary runtime state does not leak into the test user's home directory. | ✔ runtime hygiene |
Read the newest file in vms/out/. For Linux/macOS guests, the runner also collects /tmp/aperio-vmtest.log; Windows writes C:\aperio-vmtest.log. Docker includes container logs and inspect output.
Confirm the guest is ARM64, remove guest node_modules, and let that guest run npm install. Never copy host dependencies into it.
The desktop runners require Parallels Tools for prlctl exec and shared folders. Confirm the pristine/snapshot VM name and that the host share is visible before changing the scripts.
Build the exact local tag first. The Docker runner never pulls a missing local tag. Then inspect the log for image metadata, container output, and the bootstrap timeout.
vms/out/, the command you ran, your host OS/architecture, and whether the failure happened during provisioning, install, smoke, or cleanup.