AI explanations

AI in Hostveil is optional, advisory-only, and local-first by default. It can add a second opinion in plain words. It never applies changes, and everything works with no AI at all.

Using it

Add --ai to explain for an advisory explanation of a finding:

hostveil explain ssh.rootlogin --ai

The built-in plain explanation always prints first; --ai appends an AI explanation (advisory) section. If the model is not reachable, Hostveil says so and continues. The command never fails because AI is unavailable.

The same explanation is one action away in the other interfaces: the dashboard's finding panel has an Explain with AI button, and the TUI's detail view answers e. Both degrade the same way the CLI does: no provider reachable means a one-line note, never an error.

Judging a fix for this host specifically

A fix's trade-off is generic — cve.outdated-image's re-pull is attractive on a self-hosted box that wants CVE patches fast, and risky on one that is stable today — and Hostveil has no way to know which side of that this host is on unless it's told. hostveil ai-context saves one line describing the host, remembered until changed:

hostveil ai-context "a personal media server, want fast security patches more than stability"

Once it's set, every --ai answer — explain, the dashboard button, the TUI's e — reads it automatically and closes with a sentence judging the fix for a host like the one described, instead of a generic explanation. hostveil ai-context with no argument shows what's saved; --clear removes it.

hostveil advise [--ai] asks the same question about every fixable finding at once: a deterministic list of what each fix would get you and cost you (no AI required), and with --ai, a one-line verdict per finding — Apply, Skip, or Depends — weighed against the same saved description. The TUI's v key and the dashboard's Advise button reach the same thing.

Local by default, an external API by choice

HOSTVEIL_AI_PROVIDER selects the backend. It defaults to Ollama, running on your own machine, so nothing leaves the host unless you name a different provider explicitly.

`HOSTVEIL_AI_PROVIDER`	Where it runs	Credential	Model
`ollama` (default)	On this machine, via Ollama	none	`HOSTVEIL_OLLAMA_MODEL` (default `llama3.2`)
`anthropic`	The Claude API	`ANTHROPIC_API_KEY`	`HOSTVEIL_ANTHROPIC_MODEL` (default `claude-opus-5`)
`openai`	Any vendor speaking the OpenAI chat-completions shape — OpenAI itself, OpenRouter, Groq, Together, a self-hosted server on another machine	`HOSTVEIL_OPENAI_API_KEY`	`HOSTVEIL_OPENAI_MODEL` — required, no cross-vendor default

Ollama, running locally

Install Ollama and pull the model once:

ollama pull llama3.2
hostveil explain ssh.rootlogin --ai

To use a different local model:

HOSTVEIL_OLLAMA_MODEL=llama3.1 hostveil explain ssh.rootlogin --ai

An external API, when the machine can't run a local model

A demo host or a small VPS is often not powerful enough to run even a small local model well. Point Hostveil at the Claude API instead:

HOSTVEIL_AI_PROVIDER=anthropic ANTHROPIC_API_KEY=sk-... \
  hostveil explain ssh.rootlogin --ai

Or at any OpenAI-compatible vendor — this example uses OpenRouter:

HOSTVEIL_AI_PROVIDER=openai \
  HOSTVEIL_OPENAI_BASE_URL=https://openrouter.ai/api/v1 \
  HOSTVEIL_OPENAI_API_KEY=sk-or-... \
  HOSTVEIL_OPENAI_MODEL=meta-llama/llama-3.1-8b-instruct \
  hostveil explain ssh.rootlogin --ai

Set these in a shell profile or a systemd unit to make the choice permanent for that host, rather than repeating them on every command. Whichever provider is off-host, credentials and prompts leave the machine — see the privacy note below for exactly what that prompt contains.

Advisory only, and private by design

What the model can and can't do

The AI can only explain. It has no ability to apply, change, or drive any fix. Scores, findings, and fixes are computed entirely without it.

Privacy

Only human-readable fields are sent to the model: a finding's title, service, description, how-to-fix text, and its fix's benefit/side-effect summary. Raw evidence values such as secrets, ports, and file paths are never included in the prompt, so sensitive detail does not leave the host even when you opt in — including when you opt into an off-host provider. If a host description is saved (hostveil ai-context), that text is sent too, since it's the whole reason to ask — write it accordingly. What does leave the host with anthropic or openai is that reduced prompt itself, sent to whichever API you configured; with the default ollama nothing leaves the host at all.