Frequently asked questions
The questions self-hosters ask most before trusting a tool with their server.
Does it upload my data?
No. Hostveil runs entirely locally — no SaaS, no database, no account. Even the optional AI explanations default to a model on your own machine, and only human-readable fields (never raw secrets or paths) are ever sent to it. See AI explanations.
Will a fix break my server?
You see the exact change before it applies, the original file is backed up to a checkpoint first, and hostveil rollback restores it byte-for-byte. Fixes that can't be automated safely are classified Manual and only explained, never applied. See Fixing & rollback.
How is Hostveil itself tested?
It runs as root and edits configuration files on servers people depend on, so the question is fair. There is more test code in this repository than product code — not a ratio anyone targets, just what auditing an operating system honestly costs. 5 fuzz targets run nightly, five minutes each, over the YAML and JSON5 editors that rewrite your config files. Every pull request drives the real binary end to end — scan, fix, history, rollback, rescan — inside a seeded Debian container, which is the only place the apply and rollback machinery meets a real filesystem.
This site is held to the program the same way. A package whose only job is to fail the build when a published page drifts from the code checks every domain table, every finding ID in a screenshot, every figure on Measured results, and the counts on What it checks. A stale number on this site is a failing build rather than something you have to catch.
And if you would rather see it than read about it, the repository carries a Vagrant VM seeded to be vulnerable. You can watch a hardening tool edit a server, roll the changes back, and rescan — before you let it near one of yours. See Contributing.
What if a fix has tradeoffs?
Then it's a Review fix, not Auto-fix. Hostveil presents independent alternatives and makes you choose one with --action. fix --all touches only the clearly-safe Auto-fix findings and leaves everything else to you, unless you add --review — which applies each Review fix through its first alternative, the one its how-to-fix describes.
Do I need Docker or Trivy?
No. The SSH, firewall, and auto-update checks run natively with no extra tooling. The Docker/Compose audit needs Docker, and image CVE scanning needs Trivy — each is used when present and skipped cleanly when not, with the score renormalized so a skipped domain doesn't inflate your result.
Why does it ask for sudo?
Some checks read root-owned files such as sshd_config, and applying a fix writes to protected paths. So hostveil elevates itself with sudo automatically — the prompt you see is sudo's own, identical to running sudo hostveil, and it continues in the same terminal once you authenticate. version and help never prompt. To run unprivileged (scripts/CI), set HOSTVEIL_NO_SUDO=1; the root-owned domains are then skipped with a clear message.
Is the web dashboard exposed to my network?
No — hostveil serve binds to 127.0.0.1:8787 (loopback only), and every route requires the one-off access token printed in the startup URL. The dashboard rejects any request not addressed to localhost, so --addr cannot publish it to the network either. Use SSH port forwarding for remote access. See Interfaces.
What does the 0–100 score mean?
Each domain is scored on its own axis, and the axes are combined by weight. Every unfixed finding takes a share of what its axis still has: a High finding — one reachable right now — takes half of the remainder, and the two lesser levels proportionally less. A vulnerability with no upstream patch costs exactly the same as one you could act on; not being able to fix it yet does not make the risk smaller. Because the shares compound rather than add, an axis never bottoms out after two findings. A host with nothing to flag shows Clean rather than a hollow 100, and scan exits non-zero when any unfixed finding is High. See Scoring for the whole model.
How is this different from Lynis or a CIS benchmark?
They audit. Hostveil audits and then offers to fix, with a preview, a backup, and one-command rollback — which is the whole difference if you just want the server running well. A report that tells someone running Jellyfin, or a self-hosted AI agent like OpenClaw, that their SSH configuration is weak has moved the problem, not solved it.
Lynis is broader and deeper than Hostveil and will stay that way: it runs hundreds of tests across territory Hostveil does not cover, and it is the better tool if what you want is a thorough audit you will read yourself. A CIS benchmark is a standard rather than a program — a document to be complied with, usually in an organisation that has someone to do it.
The interesting answer is that this is not a claim we ask you to take on faith. Hostveil’s own score going up after Hostveil’s own fixes proves nothing, so the repository carries a harness that measures a deliberately weakened host with Lynis, Docker’s CIS benchmark, a TCP scan from off the host, and the kernel’s own socket table — before the fixes, after them, after the services restart, after the Review fixes are accepted, and after everything is rolled back. Every figure is committed as JSON and every number on the page is pinned to it. The results, including what did not improve, are published in full.
Which platforms are supported?
Hostveil audits Linux hosts. Prebuilt binaries target Linux and macOS on amd64 and arm64, and the macOS build runs — but every detection rule in it is about Linux. On a Mac ten of the twelve domains report N/A, two run (SSH and file permissions), and the score is an average over a fifth of the weight. Running it on macOS is the detail.
Can I add my own checks?
Not without recompiling. There is no plugin system, no rule file, and no config file — Hostveil is one static binary and its checks are Go. That is a deliberate choice rather than a gap: the scoring weights have to sum to 100 for the score to mean anything, every finding has to carry a remediation someone argued about, and a signed single binary is the whole distribution story. A rule format would put all three behind a file nobody signs.
What you can do without touching Go is tune appearance and behaviour through environment variables and flags — none of which changes a threshold, a severity, or an axis weight, with one exception worth knowing: HOSTVEIL_NO_SUDO=1 changes which domains can run at all.
If you do want to add something, the sizes are very different. A new rule in an existing domain is small — a function and a test. A new fix for an existing finding is small too. A new domain is a real change: a package, a row in the domain table, a registration, a weight taken from some other domain to keep the total at 100, rows in the checks table in both languages, and about eleven tests that fail until each step is done. Contributing walks it.