Local HTTP bridge - how the site sees your rig exactly

Short answer

While Abliteration is running, it exposes a tiny read-only HTTP endpoint on 127.0.0.1:47821. The site at abliteration.org can probe it to show precise “runs now / tight fit / slow / won’t fit” verdicts across the whole catalog instead of guessing from browser hints. Loopback only - no external network exposure, no tokens, no data leaves your machine except the hardware description your browser sees on the same page.

Detailed explanation

Why the bridge exists. Browsers can’t see how much RAM your machine actually has free right now - navigator.deviceMemory caps at 8 GB and doesn’t distinguish free from total. So without help, the catalog can only guess: it draws a coarse yellow “guess” plate and colors every model with the same rough numbers. With Abliteration running, the site probes the local bridge, reads real RAM/CPU/GPU numbers, and every compatibility chip across every model page reflects them.

Endpoints. The bridge is two GET routes on 127.0.0.1:47821.

• GET /health - a fast liveness check. Returns {"ok": true, "app": "abliteration", "version": "<sem>", "schema": 1} under 100 ms. Never touches disk or the model index - the site uses it as the first probe.
• GET /rig - the full hardware description: OS name and version, CPU model and core counts, total and free RAM, GPU (when a dGPU/eGPU with ≥ 2 GB VRAM is present - integrated graphics stay null because they don’t help inference), plus a UTC timestamp of when the numbers were measured.

Both endpoints answer Access-Control-Allow-Origin: https://abliteration.org so the browser lets the site read them. Preflight OPTIONS returns 204. Dev builds also accept http://localhost:* and http://127.0.0.1:* behind an internal flag.

Port fallback. The bridge tries 47821 first. If that port is taken (rare on typical machines), it falls back to 47822, then 47823. Beyond three, the app gives up rather than picking an arbitrary port the site can’t find.

Refresh cadence. ram.free_gb is the only field that meaningfully moves during a session - everything else (CPU, GPU, total RAM) is measured once at startup. The app refreshes free RAM in the background every 3-5 seconds; the site caches the last /rig response in sessionStorage for 30 seconds before probing again.

Startup and shutdown. The bridge starts with the app and stops the moment you Quit. Closing the window on either platform does not stop the bridge: on Windows the app minimises to the tray, on macOS it stays in the menu bar (see Menu bar and tray), and the bridge keeps serving in both cases. This is the whole point: opening abliteration.org after checking your email should still see accurate colors without you re-launching anything. Only Quit stops the bridge.

Same bridge on Windows and macOS. The endpoints, the port, the schema, and the response shapes are identical. The site does not care which OS the visitor is on, it fetches /health and /rig the same way in both cases. On macOS the app is a sandboxed bundle, so the bridge is only reachable once the app is running from the Applications folder; launched from anywhere else, the loopback listener stays blocked. See The site says “install the app” even though I have the app on macOS.

How the site probes. Every page on abliteration.org that shows a rig-aware component ships a small inline script. On load it looks in sessionStorage['abl_rig'] for a cached probe under 30 seconds old; a hit shortcuts the network entirely. On a miss it walks the three ports in order and fires GET /health at each with a 1500 ms timeout - long enough for Chrome’s Private Network Access preflight, short enough that a probe against a dead port doesn’t stall the page. The first port that answers gets a 500 ms follow-up GET /rig; the result is written back to sessionStorage and dispatched as a window event named abl-rig-ready. Every rig-aware component on the page subscribes to that event and recolors itself when it fires. On any failure - port closed, wrong host, timeout, non-200 - the site falls back to the browser guess and moves on. Nothing blocks first paint.

What the site shows in each state. Two visual modes, same layout, different palette.

• Guess (no bridge). The plate on /models and every model page is yellow, tagged GUESS, and reads “rough estimate - likely fits models up to ~X GB” alongside a green Get the app button. Compatibility chips on cards render from browser hints only, so the numbers are coarse - the browser hides real memory behind navigator.deviceMemory, which caps at 8 GB and never reports free vs total, so a Chromebook and a 128 GB workstation are indistinguishable from JavaScript. A small ? chip inside the plate expands into a popover that explains why the bridge helps and links to the download.
• Connected (bridge answered). The plate flips to green, tagged CONNECTED, and prints the CPU model, total RAM, and free RAM straight from /rig. Every card recolors to a precise runs now / tight fit / slow / won't fit verdict. The ? popover, the GUESS tag, and the Get the app CTA all hide themselves - they’d read as noise when the numbers on screen are already exact.

Losing the bridge mid-session. The 30 second cache is deliberately short. If you Quit Abliteration while a tab is still open, the very next probe (fired the moment the cache expires) returns nothing and the site drops back to guess mode: the plate goes yellow, chips coarsen, the CTA reappears. Restarting the app flips everything green again inside the next probe interval, no page reload required. This is why the app minimises to the tray by default: closing the window doesn’t drop the bridge, only Quit does.

The catalog Compat filter. The four Compatibility rows in the /models sidebar are a real server-side facet, not a client-side filter over the visible page. Clicking one navigates to ?fit=green (or a comma-separated set like ?fit=green,yellow), and the server translates the colors into byte ranges against each model’s smallest available quantization using the exact same thresholds the client uses to paint cards. The “N results” count reflects the whole catalog, not the current page, and popular ordering is preserved inside the filtered set. The visitor’s free_gb and total_gb ride along in the URL, attached client-side just before navigation, so the SQL sees the same rig the plate is showing. Without JS, or before the probe lands, the server falls back to a conservative default matching the yellow-plate copy.

Why it matters

The compatibility color on every model card is the difference between a catalog that helps you and a catalog you have to work around. Two identical laptops with 32 GB RAM can have wildly different “free right now” numbers depending on what else is open. The bridge closes that gap - the model page says “runs now” only when it actually will. Without the bridge, the same catalog card falls back to a guess verdict with a GUESS tag, and the top of the page carries a Install app for exact → plate.

In Abliteration specifically

The bridge is loopback-only: it binds 127.0.0.1, never 0.0.0.0. Nothing on your local network can reach it, only the browser running on the same machine. There are no tokens, no signatures, no cookies - the entire security model is “loopback plus an Access-Control-Allow-Origin on the specific site domain”. The endpoint returns hardware description and nothing else - not chat history, not installed models, not filesystem paths, not usernames.

The schema is versioned. Today’s shape is schema: 1. Breaking changes to the field layout bump the number and the site handles both for a release window; adding a new optional field doesn’t touch the schema at all.

If you want to see what the site sees, curl http://127.0.0.1:47821/health and curl http://127.0.0.1:47821/rig from any shell on the same machine while the app is running. The JSON that comes back is exactly what the catalog uses to color your chips.

Related

• Understanding your rig - what each field in /rig means for running models
• Hardware card - the same numbers, presented in-app
• Deep links - the sibling site-integration, for actions rather than data
• System tray - why the bridge stays available after you close the window