Install and start Docker
The Local Fuzzer is distributed as a Linux container. Docker supplies Node, ffmpeg, a headless Chromium browser, the face models, recipes, and the web interface, so you do not have to install those parts separately.
| Platform | Official installation guide | What “running” looks like |
|---|---|---|
| macOS | Install Docker Desktop on Mac ↗ | Docker Desktop is open and its status says the engine is running. |
| Windows | Install Docker Desktop on Windows ↗ | Docker Desktop is open and its engine has finished starting. |
| Linux | Install Docker Engine ↗ | The Docker service is active and your account can run docker. |
Open Terminal, PowerShell, or your Linux shell and run docker version. Continue when it prints both a Client and Server section. If it prints only the client or cannot connect to the daemon, start Docker first.
Pull once, then open the local page
docker pull ghcr.io/vecna/ghostmaxxing:latestdocker run -d --name ghostmaxxing -p 127.0.0.1:11111:11111 --shm-size=1g --stop-timeout 120 -v ghostmaxxing-data:/data ghcr.io/vecna/ghostmaxxing:latestWhen the command returns a container ID, open http://localhost:11111 in a browser on the same computer. You should see the Ghostmaxxing Local Fuzzer page with an upload area, a preset selector, and no jobs yet.
Keep it local. The command binds the page to 127.0.0.1. The service has no login and must not be exposed on 0.0.0.0 or a public network.
If you already created the container, use docker start ghostmaxxing. To watch its service log, use docker logs -f ghostmaxxing. To stop cleanly, use docker stop ghostmaxxing; an unfinished job resumes when the container starts again.
Record one person turning slowly
Use a 15–60 second video containing one consenting person. Keep the whole face large and sharp in the frame while the person turns slowly left and right, then looks slightly up and down. Return through the frontal pose. A phone video is suitable; MP4 is the simplest choice, and the container accepts other formats that ffmpeg can read.
- Use steady, even light and a simple background.
- Keep camera distance, zoom, and orientation fixed.
- Avoid fast motion, motion blur, cuts, filters, and other faces.
- Do not begin with makeup if the clean video is intended to become the atlas.
- Do not include more extreme poses than the clean face detector can recognise: unrecognised poses cannot be scored.
The video determines the experiment. A blurry, distant, dark, or narrow-pose clip changes the atlas and therefore changes every number in the report. It cannot be corrected by running more trials.
Upload, choose a preset, and start
Upload the video
The page checks it with ffprobe. The upload is a copy into the local Docker data volume, not an internet upload.
Choose Quick first
Quick uses coarser pose bins and fewer trials. Use it to check framing and runtime before committing hours to Standard or Deep.
Review the plan
The page shows the exact atlas, trial, and report commands. Advanced settings change the pose atlas or individual recipe cells; changing either changes what the numbers mean.
Start and leave Docker running
The job first builds a clean pose atlas, then sweeps each recipe. Jobs run one at a time. The estimate becomes more accurate after the first measured trials.
Inspect and download
Open the full HTML report, download the selected Ghostyles and their images, or download logs for later analysis. Use Run again on this video to reuse an unchanged atlas.
A trial seed reproduces a design only with the same recipe and atlas conditions. Paired seeds keep stroke geometry aligned across compatible recipe cells and videos; the face, palette, pose atlas, and measured outcome can still differ.
Report, Ghostyles, and evidence
| Output | Use | Sensitive content |
|---|---|---|
| Full HTML report | Compare recipes and trials; print every recipe with the reading guide included under the first recipe. | Embeds an anchor image and detailed measurements. |
| Ghostyles archive | Generated .js modules, previews, pose sheets, CSV profiles, and report. | Contains face images and derived results. |
| Logs archive | Reproduce or audit the atlas and trials. | Contains descriptors, frames, configuration, and command history. |
Deleting a job removes its job folder from the Docker data volume. Removing the volume deletes every job. Downloaded copies remain wherever you saved them.
Common startup and input problems
| What you see | What to check |
|---|---|
| The local page does not open | Run docker ps, then docker logs ghostmaxxing. Confirm that Docker is running and port 11111 is free. |
| “name is already in use” | The container already exists. Run docker start ghostmaxxing instead of another docker run. |
| Chromium crashes during a long run | Confirm the container was created with --shm-size=1g. |
| Atlas fails or has few imprints | Use a larger, sharper face; steadier light; slower turns; and a visible frontal pose. |
| The computer becomes slow | The fuzzer is CPU-intensive. Let Quick finish first and allocate additional CPUs to Docker Desktop if appropriate. |