Headroom

Simulate a local AI box under your own crowd: pick the hardware, a model and the users, then find the redline before you buy

---

Overview

Headroom tells you whether a local AI box will serve your people before you pay for it. Pick a box (DGX Spark, Ryzen AI Halo, Mac Studio, Jetson Thor, an RTX workstation or your own specs), a model, a server and a crowd, such as 50 Kindle readers on Wi-Fi, six coding agents on a LAN or hikers on a LoRa mesh. It simulates every request from the first byte on the wire to the last e-ink refresh. The answer is a verdict (overloaded, tight, right-sized or overkill), the thing that runs out first, and the redline: how many users the setup holds.

Live: headroom.neorgon.com

---

Features

• Sandbox -- an interactive 3D view of the hardware and connected devices, with live request activity, a full-crowd Activity view, and throughput, queue, answers-on-target and power charts
• Device artwork -- local product and client thumbnails rendered from the same original 3D models; camera controls support mouse, touch and keyboard, with an automatic fallback when WebGL is unavailable
• Local setups -- eight editable macOS and Linux examples pairing hardware, an AI model, server settings and a workload; custom laptop, compact PC, tower and rack illustrations with editable specifications
• Quick start -- a first-visit welcome that can be reopened from the header
• Find the redline -- doubles the crowd until answers fail, then bisects; when the network gives out first, it also reports what the box alone would hold
• Compare boxes -- the same crowd on every box in the catalog, with redlines, cost per user and wall power
• Missions -- seventeen scenarios with a budget and a par price; three stars for serving every group on the cheapest hardware that works, with pars proven on four seeds
• Real protocols and links -- SSE per-token events vs WebSocket batches, Wi-Fi airtime, Bluetooth hub limits, LoRa duty cycles, VPN distance, and the TCP stall a lost packet costs on satellite links
• Two server designs -- llama.cpp slots sharing one context pool, Ollama's single slot that truncates, vLLM, SGLang and TensorRT-LLM paged KV with prefix caching
• Two ways to pair boxes -- tensor parallel (vLLM, SGLang, TensorRT-LLM, MLX) speeds up generation; llama.cpp's layer split over RPC adds memory, not speed
• Honest verdicts -- headroom is judged on how close the slowest answers run to their limits, so a background batch or a busy batching server does not read as tight
• Current models -- the September 2026 generation (Qwen3.6, Gemma 4, GLM-4.7, Nemotron 3, MiniMax-M2.7) beside gpt-oss, Qwen3 and Llama, with capability tiers anchored to one public benchmark
• Calibrated, and shows its work -- 82 published measurements next to the model's predictions, typical error about 11%, including the per-expert cost that makes many-expert models slower than their size suggests
• Tested -- make test pins every lesson the simulator teaches as a use case, in Node with no dependencies
• Costs -- electricity, amortization and payback against the same tokens from a cloud API
• Shareable -- one link reproduces the exact scenario; everything runs in the browser

---

Running locally

ES modules require an HTTP server (not file://):

make serve

Or manually:

python3 -m http.server 8894

The engine is plain ES modules with no DOM, so it also runs headless in Node:

node --input-type=module -e "import('./js/engine/sim.js').then(m => console.log(m.runScenario({box:{id:'dgx-spark',count:1},model:{id:'gpt-oss-120b',quant:'mxfp4',kv:'f16'},runtime:{id:'vllm'},groups:[{persona:'reader',count:50,client:'kindle',link:'wifi',distanceKm:0.015}]}).verdict))"

The optional 3D view uses vendored Three.js and illustrative procedural models, not exact manufacturer geometry. It shows up to 72 representative devices for large crowds while the engine and live totals still include every user. The Activity view shows every user individually.

Run make test for engine regressions. With the dev server running and Playwright available in your developer environment, node tests/ui.mjs checks the setup workflow, 3D controls and fallback, large crowds, and responsive layout. node scripts/render-device-art.mjs regenerates the committed device thumbnails. The deployed site still needs no build step or package install.

For headless setup calculations, run node scripts/calculate-setups.mjs --help. It can export every example, sweep user counts and find redlines as JSON using the existing simulator. No actual AI models or external APIs are called.

The research handoff scopes a separate pass for verified product specifications, real benchmarks, installation guides and a possible main-model/local-worker tutorial. Custom enclosure starter figures are explicitly named baselines, not measured profiles for the pictured machine. Changing enclosure appearance does not change simulated performance.

---

Architecture

headroom-site/
├── index.html              # App shell: sandbox, local setups, missions, compare, method
├── css/
│   ├── style.css           # Fleet template plus the app layout and chart tokens
│   ├── workspace.css       # Simulation workspace, device previews, responsive layout
│   ├── setups.css          # Local setup examples and custom enclosure gallery
│   └── viz.css             # Viz Kit (vendored)
├── js/
│   ├── app.js              # Entry point
│   ├── state.js            # Scenario, persistence, shareable links
│   ├── runner.js           # Live animation loop and Web Worker jobs
│   ├── render.js           # Top-level rendering per tab
│   ├── events.js           # Every listener, delegated
│   ├── utils.js            # Formatting helpers
│   ├── viz.js              # Viz Kit (vendored)
│   ├── engine/             # Pure simulation, no DOM
│   │   ├── perf.js         # Roofline model: memory fit, step time, MoE routing
│   │   ├── server.js       # Continuous batching, slots vs paged KV, prefix cache
│   │   ├── network.js      # Links as airtime queues, protocols, distance
│   │   ├── sim.js          # Discrete-event simulation of the crowd
│   │   ├── report.js       # Verdict, bottleneck, advice, economics
│   │   ├── batch.js        # Redline search and box comparison
│   │   ├── worker.js       # Runs batch jobs off the main thread
│   │   ├── heap.js         # Event queue
│   │   └── rng.js          # Seeded randomness
│   ├── data/               # Hardware, models, runtimes, crowd, missions, calibration
│   ├── vendor/three/       # Optional Three.js renderer and MIT license
│   └── ui/                 # Loadout, 3D models/scene, activity canvas, results, charts
├── assets/devices/         # Committed thumbnails of the procedural device models
├── scripts/                # Developer utility for regenerating device artwork
├── DESIGN.md               # Workspace design conventions
├── docs/
│   ├── architecture.mmd    # Diagram source
│   └── research.md         # Sourced specs and benchmarks behind the catalog
├── robots.txt
├── sitemap.xml
├── CNAME
└── Makefile

---