Get started

Get HyprBox running and watch it fix one problem — in about 10 minutes. This is the short happy path. The full guide has every option; ignore it for now.

You need: a Linux/macOS machine with Node 20+, pnpm, Docker, and Go (Go only to build the agent). You'll run everything locally.

#1. Start HyprBox

From the project folder:

pnpm install
pnpm db:generate                 # prepare the database client
pnpm db:up                       # start Postgres (via Docker)
cp apps/api/.env.example apps/api/.env
pnpm --filter @hyprbox/api exec prisma migrate deploy
pnpm db:seed:admin               # creates the admin login
pnpm db:seed:recommendations     # loads the fix catalogue (don't skip this)
pnpm dev:api                     # the API  → http://localhost:4000
pnpm dev:web                     # the web  → http://localhost:3000

Already started it earlier? pnpm dev:api will say EADDRINUSE :4000 — that just means it's already running. Skip these two and go straight to the URL.

Open http://localhost:3000 and log in:

• email: admin@hyprbox.local
• password: hyprbox-admin (change it right after, in Settings)

You're in. You'll see an empty dashboard — no servers yet. That's next.

#2. Connect your first server

A "server" here can just be this machine — perfect for testing. This block creates a connection token and starts the agent — copy-paste the whole thing (no manual token-pasting, so nothing to get wrong):

# get a login, then mint a token for a server we'll call "my-server"
JWT=$(curl -s -X POST http://localhost:4000/api/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"admin@hyprbox.local","password":"hyprbox-admin"}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["token"])')

TOKEN=$(curl -s -X POST http://localhost:4000/api/tokens \
  -H "authorization: Bearer $JWT" -H 'content-type: application/json' \
  -d '{"name":"my-server","nodeId":"my-server"}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["token"])')

echo "token: $TOKEN"     # sanity check — should start with hbnt_

# arm a safe demo problem, then start the agent (builds itself, runs here)
rm -f /tmp/hyprbox-demo.ok
scripts/install-agent.sh --api-url http://localhost:4000 \
  --node-id my-server --token "$TOKEN" --interval 10s --demo

Leave that terminal open — the agent runs there and scans every 10s. --demo adds a harmless fake problem so you can try the loop with zero risk.

Prefer clicking? You can instead create the token in the dashboard (Settings → tokens, name it my-server) and pass it to the same scripts/install-agent.sh … --token hbnt_… command.

#3. Watch the loop

Go to Health in the dashboard (left menu). Within ~10 seconds you'll see:

• real findings about this machine (disk, SSH, security checks), and
• a safe one: "Demo: marker file is missing".

Click the demo finding → you'll see the exact commands the fix runs and a green Apply button (it's marked SAFE). Click Apply. Watch it run live, see the verified: line, and — back on Health — the finding turns resolved on its own.

That's the whole product. You just did Discover → Preview → Apply → Verify.

#4. What now?

• Try a real fix on a real server (not your laptop — real fixes change the system). See Use it daily.
• Add more servers: repeat step 2 on each.
• Going to production? Deployment and the full guide.

Stuck?

• EADDRINUSE :4000 on pnpm dev:api → the API is already running; skip dev:api / dev:web and just open http://localhost:3000.
• The agent rejects your token → you pasted the placeholder. Use the real token from step 2a (it starts with hbnt_).
• Health page empty → the agent hasn't finished its first scan yet; wait a few seconds and refresh.