HyprBox docs GitHub ↗

Demo runbook — the find → fix → verify loop, narrated

A presenter's script for a ~5-minute live demo of HyprBox on a real agent. It's zero-risk: the loop you drive on camera uses a benign demo Finding (demo.marker-missing) and a SAFE preset (hyprbox-demo) that only touches /tmp. The optional HyprWatch beat at the end is preview-only unless you're on a throwaway host.

Quick-run (no narration) is in §Run it. The rest is the script. 🇫🇷 Version parlée en français : DEMO.fr.md.

The framing (say this first, ~20s)

"Your monitoring tells you a disk is full, SSH allows passwords, a cert is expiring. Then you SSH in and fix it by hand, on every box. HyprBox is the part that fixes it — it finds the problem, shows you the exact change before it runs, applies it, and proves it worked. Preview-then-apply, on a fleet. Let me show you the whole loop on a live server."

Keep the anti-pitch ready if asked "is this Terraform / k8s?": "No — those drive cloud APIs and clusters. We run vetted fixes as bash on the hosts a PME actually has. Host apps: yes. Control planes: no." (see AUTOPILOT.md).

Pre-flight (do this BEFORE the prospect joins)

Nothing kills a demo like a cold start. Run this 5 minutes ahead:

# 1. Stack up. Postgres (docker is the no-sudo path on this box):
docker compose -f docker-compose.dev.yml up -d postgres
pnpm --filter @hyprbox/api dev   # :4000
pnpm --filter @hyprbox/web dev   # :3000
# 2. Confirm an admin + at least one node with findings already exist:
#    log in at http://localhost:3000 (admin@hyprbox.local / hyprbox-admin)
#    and open /dashboard/health — you should see real findings (disk, audit…).
# 3. Mint a node token bound to your node (Tokens page or POST /api/tokens),
#    and ARM the demo:
rm -f /tmp/hyprbox-demo.ok
# 4. Start the agent in demo mode (short intervals so beats land fast):
HYPRBOX_API_URL=http://localhost:4000 \
HYPRBOX_NODE_ID=wsl-smoke \
HYPRBOX_NODE_TOKEN=<node token> \
HYPRBOX_DEMO=1 \
HYPRBOX_INTERVAL=8s HYPRBOX_SCAN_INTERVAL=8s \
./agent/hyprnode/hyprnode

Checklist before you share your screen:

  • /dashboard/health loads and lists findings (the page isn't empty).
  • The "Demo: marker file is missing" INFO finding has appeared.
  • You're already logged in (no fumbling with the password on camera).
  • Browser zoom ~125% so the room can read the rendered bash.

Act 1 — Discover (~45s)

Open /dashboard/health.

"This is every server the agent watches. Each line is a Finding — a specific risk, in plain language, not a metric to interpret."

Point at a real one (disk usage / UFW inactive / fail2ban down). Then the demo finding:

"Here's one we'll fix live: a file the agent expects is missing. INFO, because it's harmless — but it drives the exact same machinery as the scary ones."

The beat that matters: findings are human-readable causes, and each carries a recommended fix. That's the product, vs a dashboard that just shows red.

Act 2 — Fix, with proof (~2min — the core)

Click the "Demo: marker file is missing" finding.

"Before anything runs, I see the recommendation and the exact bash that will execute. Nothing is hidden."

Point at:

  • the recommendation title + risk tier SAFE (the Apply button is gated per tier — MANUAL fixes show no button at all, DANGEROUS demand a typed confirm). "The product decides how much friction each fix earns."
  • the rendered script (the marker write + the verify block).

Click Apply fix →. You land on the job live-tail.

"The agent is running it for real, right now — streamed live. And critically: it doesn't just run, it verifies. See the verified: … line? That's the verify step asserting the fix actually took. No verify pass, no success."

Job goes SUCCEEDED. Go back to /dashboard/health.

"And the finding resolved itself — the loop closed. We asked it to fix X, it ran the vetted fix, X is gone. That's find → fix → verify → resolve, end to end, in fifteen seconds."

This is the whole pitch in one motion. If you show nothing else, show this.

Act 3 — It installs, not just repairs (~1min, optional but strong)

This is the wedge that turns "auto-remediation" into "your ops stack on autopilot." Enable HyprWatch on the node (Tokens/config or PATCH /api/nodes/<id>/config {"hyprwatch":true}); within a tick a "No monitoring stack detected" finding appears, recommending the monitoring-only preset.

"Same loop — but the fix here installs Prometheus, Grafana, node-exporter and Alertmanager, opens the firewall, and verifies all three are serving before it calls it done. Point HyprBox at a fresh PME server and it stands up your monitoring, logging, backups — and keeps them healthy."

Two ways to show it:

  • Throwaway host: actually click Apply — the stack comes up, the verify goes green, the finding resolves. Most impressive; only do it where deploying Prometheus is fine.
  • Any host (safe): open the recommendation and show the rendered compose + verify steps, then narrate the apply. Don't click Apply on a box you care about — it deploys real services.

Reset after: PATCH …/config {"hyprwatch":null} + resolve the finding.

The close (~15s)

"Three modules, one loop: HyprGuard hardens, HyprVault backs up, HyprWatch watches — all find → preview → fix → verify. Built on proven OSS engines, with the autopilot intelligence on top. Self-hosted, your servers, your data."

Run it (quick reference)

Arm + start the agent (demo mode), then at http://localhost:3000:

  1. /dashboard/health → within ~one scan tick the node shows "Demo: marker file is missing" (INFO).
  2. Click it → modal shows recommendation hyprbox-demo (SAFE) + rendered bash → Apply fix →.
  3. Job live-tail: marker written, verify prints verified: … → SUCCEEDED.
  4. Health: the finding is RESOLVED (auto-resolve on job success).
rm -f /tmp/hyprbox-demo.ok                 # arm the demo
HYPRBOX_API_URL=http://localhost:4000 HYPRBOX_NODE_ID=wsl-smoke \
HYPRBOX_NODE_TOKEN=<node token> HYPRBOX_DEMO=1 \
HYPRBOX_INTERVAL=8s HYPRBOX_SCAN_INTERVAL=8s ./agent/hyprnode/hyprnode

Re-arm / reset

rm -f /tmp/hyprbox-demo.ok                  # next scan re-emits the demo finding

For HyprWatch: PATCH /api/nodes/<id>/config {"hyprwatch":null} and resolve the monitoring.absent finding (POST /api/findings/<id>/resolve).

If it breaks live

  • No demo finding after ~15s → the marker still exists (rm -f /tmp/hyprbox-demo.ok) or HYPRBOX_DEMO wasn't set on the agent. Have a second terminal ready to restart the agent.
  • Health page empty → the agent isn't reporting; check the node token is bound to this nodeId and the API is on :4000.
  • Apply button missing → that finding's recommendation is MANUAL (no auto-apply by design) — use the demo finding, which is SAFE.
  • Fallback to terminal: the whole loop works over curl (GET /api/findings, GET /api/findings/:id, queue via POST /api/jobs, stream GET /api/jobs/:id/stream) if the UI misbehaves — see API.md.

Notes

  • HYPRBOX_DEMO_MARKER overrides the marker path (default /tmp/hyprbox-demo.ok).
  • Without HYPRBOX_DEMO, the demo scanner is a no-op — safe to ship.
  • hyprbox-demo is the only preset you can safely Apply on your own box; the real fixes (server-light, docker-prune, …) run destructive bash on the host.