HyprBox — the complete guide (A → Z)

Everything you need to go from zero to a running, self-managed fleet: who it's for, what to install, in what order, how to drive the find→fix→verify loop, and how to operate it day to day. This is the canonical onboarding doc (the one meant to live on the docs subdomain).

Honesty note: where a capability is shipped vs. planned, this guide says so with [v1], [shipped], or [roadmap]. Don't trust a guide that promises buttons that aren't there.

#Contents

1. Is HyprBox for you? — the target PME profiles
2. How it works in 60 seconds
3. Part 1 — Stand up HyprBox (the control plane)
4. Part 2 — Add your first server
5. Part 3 — Drive the loop (daily use)
6. Part 4 — The three modules
7. Part 5 — Operate a fleet
8. Safety & risk tiers
9. Troubleshooting
10. Reference & deep docs

#1. Target PME profiles

HyprBox is for freelancers and MSPs running a handful to a few dozen Linux servers for SMB clients — no platform team, no cluster. Each company type has a bundle preset that stands up the whole stack (Docker compose + firewall + HTTPS) with a verify step, plus the baseline (server-light) and backups (hypervault-restic) you apply alongside.

Recommended per server: server-light (firewall + SSH hardening + auto-updates) → the bundle for its role → hypervault-restic (backups) → enable HyprWatch for monitoring. After that, every TLS/disk/SSH/update risk the host raises has a one-click fix.

Each bundle takes a domain (or wg_host) variable and a few passwords — preview the rendered compose before applying. They need Docker on the host and a DNS record pointing at it for HTTPS. If you're just testing, any Linux box (even this dev machine) works for the find→fix loop — but the bundles want a real VM with a public domain.

#Business apps (add-ons)

Common self-hosted apps a PME asks for, each a one-shot deploy:

Same deploy flow (Deploys → pick → domain + secrets → Apply). The heavier ones (support, booking) take several minutes on first boot; their verify waits, and fails the job honestly if the app doesn't come up.

#Starter stacks (for devs/freelancers)

Building something custom? These stand up a ready-to-run runtime with the DB

• env pre-wired and HTTPS via Caddy — you just drop your code into the stack's folder and reload. HyprBox runs the infra; you write the app.

Each ships a placeholder that serves immediately (so verify passes), then you replace it with your own code (edit the folder, or git clone into it) and docker compose restart. This is provisioning, not code generation — HyprBox stands up + verifies the stack; it doesn't write your application.

Maturity badge. New presets ship as experimental — schema-valid but not yet proven end-to-end against a real host. The UI badges them and adds a warning on the preview before Apply; preview the script and test on a throwaway box first. A preset is promoted to verified only after a real successful run (the baseline fix presets are verified). The default is experimental on purpose — unproven until shown otherwise.

#2. How it works

Three pieces, one loop:

• Dashboard (web) — what you look at.
• API (control plane) — auth, jobs, findings, presets.
• Agent (hyprnode) — one static Go binary per server; scans + runs fixes.

 Discover  →  Recommend  →  Preview  →  Apply  →  Verify
  the agent    each finding   you see     it runs   the agent asserts
  raises a     maps to a      the exact   for real  it took — or the
  Finding      vetted fix     bash + tier (streamed) job FAILS

A passing fix auto-resolves the Finding. Nothing changes on a host without you previewing it first, and nothing is reported "done" without a verify pass.

#3. Part 1 — Stand up HyprBox

You host HyprBox yourself (it's self-hosted). Two ways:

#Option A — Local / evaluation (fastest, what to follow for a test)

Prereqs: Node 20+, pnpm 9, Docker (for Postgres), Go 1.23 (only to build the agent).

pnpm install
pnpm db:generate                 # prisma client (install doesn't run it)
pnpm db:up                       # Postgres via docker-compose.dev.yml
cp apps/api/.env.example apps/api/.env
pnpm --filter @hyprbox/api exec prisma migrate deploy
pnpm db:seed:admin               # creates admin@hyprbox.local / hyprbox-admin
pnpm db:seed:recommendations     # the curated fix catalogue (REQUIRED — this is
                                 # what links findings to one-click fixes)
pnpm dev:api                     # http://localhost:4000  (Swagger at /docs)
pnpm dev:web                     # http://localhost:3000

Open http://localhost:3000, log in with admin@hyprbox.local / hyprbox-admin. You're in.

#Option B — Production (self-host for real)

Three containers (Postgres + API + Web):

cp .env.production.example .env.production
# Set at minimum: JWT_SECRET (≥32 random chars), POSTGRES_PASSWORD,
# NEXT_PUBLIC_HYPRBOX_API_URL (the public API URL behind your reverse proxy).
docker compose -f docker-compose.prod.yml --env-file .env.production up -d --build

Put it behind HTTPS (Caddy/nginx), then seed the admin + recommendations the same way. Full prod notes — reverse proxy, upgrades, backups of the DB itself — in DEPLOYMENT.md.

#First steps inside the dashboard

1. Change the admin password (Settings) — the seed password is public.
2. Create your team (Admin → Users) [shipped]: add teammates with a role — VIEWER (read-only), OPERATOR (can apply fixes, manage tokens/backups), ADMIN (+ user management + audit log). Public self-signup is closed in production by design; admins provision accounts.
3. Note: a role change / password reset / delete instantly revokes that user's existing sessions.

#4. Part 2 — Add your first server

A "node" is one managed server. To attach one:

#Step 1 — Mint a node token (bind it to the node)

In the dashboard: Settings → tokens, create a token and pin it to a nodeId (the server's name, e.g. acme-web-1). Copy the plaintext token — it's shown once (the server only ever stores its SHA-256 hash).

Or via API:

JWT=$(curl -s -X POST http://localhost:4000/api/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"admin@hyprbox.local","password":"hyprbox-admin"}' | jq -r .token)

curl -s -X POST http://localhost:4000/api/tokens \
  -H "authorization: Bearer $JWT" -H 'content-type: application/json' \
  -d '{"name":"acme-web-1","nodeId":"acme-web-1"}' | jq -r .token

#Step 2 — Run the agent on that server

Easiest — the installer (builds from source, sets things up, prompts for anything missing):

# quick local test (runs in the foreground):
scripts/install-agent.sh --api-url http://localhost:4000 --node-id acme-web-1 \
  --token hbnt_… --interval 10s

# real server (installs + enables a systemd service, survives reboots):
sudo scripts/install-agent.sh --api-url https://hyprbox.example.com \
  --node-id acme-web-1 --token hbnt_… --systemd

Add --demo to also arm the safe demo loop (it auto-sets a fast 15s scan so findings appear quickly). --interval is the heartbeat/job-poll cadence; --scan-interval is how often the agent scans for problems (default 15m). --help lists all flags.

Manual — build (cd agent/hyprnode && go build -o /usr/local/bin/hyprnode .) or use the Docker image, then run with HYPRBOX_API_URL / HYPRBOX_NODE_ID (must match the token's pinned nodeId) / HYPRBOX_NODE_TOKEN / HYPRBOX_INTERVAL. The systemd unit + hardened setup are in AGENT.md. In production set HYPRBOX_REQUIRE_NODE_TOKEN=true so anonymous heartbeats are refused.

#Step 3 — Confirm it's online

Within one tick the node appears on the dashboard with a green status, and within a scan or two the Health page fills with real findings about that host (disk usage, SSH config, security audit, …).

Testing on this machine? The wsl-smoke node is already your WSL host with real findings — you can skip straight to Part 3.

#5. Part 3 — Drive the loop

This is the daily job. Open /dashboard/health.

1. Read the findings. Each is a plain-language risk on a specific node, with a severity (INFO / WARN / CRITICAL). Sorted worst-first.
2. Open one. You see the Recommendation + the exact rendered bash and a risk tier. Nothing is hidden.
3. Apply (when the tier allows — see §8). You land on the job's live tail: the agent runs the fix for real, streamed line by line.
4. Verify. The preset's verify step asserts the fix took (e.g. re-checks the disk, re-greps the SSH config). No verify pass → job FAILED → the finding stays OPEN.
5. Auto-resolve. On success the finding flips to RESOLVED automatically.

#Learn risk-free first (the demo loop)

Before touching a real fix, run the built-in safe demo — it only writes a file in /tmp:

rm -f /tmp/hyprbox-demo.ok        # arm it
# add HYPRBOX_DEMO=1 to the agent's environment, restart the agent

A "Demo: marker file is missing" (SAFE) finding appears → Apply it → watch the full Discover→Apply→Verify→Resolve loop close with zero risk. Full narrated walkthrough: DEMO.md (🇫🇷 DEMO.fr.md).

#6. Part 4 — The three modules

All three ride the same loop.

#HyprGuard — security baseline [shipped]

A 9-check audit scanner (pending kernel updates, root password, NOPASSWD sudo, world-writable /etc, UFW, fail2ban, unattended-upgrades, LUKS, auditd). Each gap becomes a finding; the fix is a hardening preset (e.g. server-light, apt-security-upgrade, ssh-disable-password-auth). Just attach the agent — HyprGuard runs automatically.

#HyprVault — backups [shipped]

Go to /dashboard/backups: create a Restic backup policy (repo URL, schedule, what to back up). HyprBox flags databases with no backup (postgres.no-backup) and the hypervault-restic preset provisions the policy. Runs are tracked; restores go through the same job path. Details: HYPRVAULT.md.

#HyprWatch — monitoring [v1, opt-in]

Turn it on per node (the hyprwatch flag in the node's config, or PATCH /api/nodes/<id>/config {"hyprwatch":true}). When on, a host with no monitoring raises monitoring.absent, recommending the monitoring-only preset — which stands up Prometheus + node-exporter + Grafana + Alertmanager via Docker and verifies all three are serving before reporting success. Opt-in on purpose, so fleets monitored elsewhere aren't nagged. Design + deferred scope (Loki, alert routing, drift): HYPRWATCH.md.

#7. Part 5 — Operate a fleet

• Multiple nodes: repeat Part 2 per server. The dashboard lists all; the Health page aggregates findings across the fleet.
• Per-node config [shipped]: override scan interval, TLS paths to watch, and the HyprWatch flag per node — changes apply on the next tick, no agent restart.
• Jobs: /dashboard/jobs is every fix run, with live tails and the full log (cancel a RUNNING job from here).
• Audit log [shipped]: /dashboard/admin/audit records every sensitive action (logins, role changes, fixes applied, tokens minted) with CSV export.
• Alerts / activity: /dashboard/alerts and /dashboard/logs surface the live event stream.
• Backups: /dashboard/backups for policies + runs. Scheduling the runs server-side is [roadmap]; today the schedule rides the agent's crontab.
• CLI [partial]: hyprbox (Go + Cobra) mirrors the core ops (status, preset preview/apply) — see CLI.md.

#8. Safety & risk tiers

Every preset declares a risk tier, and the UI gates the Apply button by it:

Rules that protect you:

• Preview is mandatory — you always see the exact bash before it runs.
• Presets are idempotent and many carry prechecks (e.g. ssh-disable-password-auth refuses to run unless an authorized_keys exists, so it can't lock you out; docker-prune refuses on a non-Docker host).
• When testing on your own box, only hyprbox-demo is safe to Apply. The real fixes (server-light, docker-prune, …) run real, sometimes destructive bash — apply those on servers you mean to change.

#9. Troubleshooting

• Node never appears → token not pinned to this HYPRBOX_NODE_ID, wrong HYPRBOX_API_URL, or (prod) HYPRBOX_REQUIRE_NODE_TOKEN=true with no token. Check the agent logs (journalctl -u hyprnode -f).
• Health page empty → the agent's heartbeating but hasn't completed a scan yet (wait a tick), or it's a non-Linux host (scanners are Linux-only by design).
• No one-click fix on a finding → either its recommendation isn't seeded (pnpm db:seed:recommendations), or the tier is MANUAL (no auto-apply).
• A fix fails with sudo: a password is required → the agent isn't running as root. System fixes (apt, ufw, ssh, docker) need root; presets escalate via sudo, which has no password prompt to answer. Run the agent as root (the --systemd unit does this) or give its user passwordless (NOPASSWD) sudo. The safe demo fix doesn't need root (it only writes to /tmp).
• Login 500 after an upgrade → the DB is behind on migrations; run prisma migrate deploy.
• Everything via API → the whole loop works over curl if the UI misbehaves: GET /api/findings, GET /api/findings/:id, POST /api/jobs, GET /api/jobs/:id/stream. See API.md.

#10. Reference

Testing locally right now? Follow Part 1 Option A → Part 3's demo loop. That's the fastest honest read on whether HyprBox earns a place in your stack.