Hostveil / Docs / Environment variables

Environment variables

Hostveil has no config file, so the environment is the whole of its persistent configuration surface. This page lists every variable it reads, every variable it sets for the commands it runs, and every variable it inherits that changes what you see — with the default and the accepted values for each.

Hostveil's own settings

These are Hostveil's, and each has a flag equivalent or no equivalent at all. Set them in a shell profile, a systemd unit, or in front of a single command.

The three flag-shaped ones — HOSTVEIL_DEBUG, HOSTVEIL_NO_SUDO, HOSTVEIL_ELEVATED — are tested for being non-empty, not for a value. HOSTVEIL_DEBUG=false enables tracing and HOSTVEIL_NO_SUDO=0 opts out of sudo. Everything writes them as =1 because that is the only value that reads the way it behaves; to turn one off, unset it or set it to the empty string.

What survives the re-exec under sudo

Running a root-benefiting command as a normal user re-executes Hostveil under sudo, and sudo's env_reset — the default on every mainstream distribution — keeps only what env_keep names: TERM, LANG, LC_*, and a short list besides. Never an application's own variable. So Hostveil hands the settings you did set to sudo as assignments on its command line, which is how they arrive.

Carried: HOSTVEIL_DEBUG, HOSTVEIL_THEME, HOSTVEIL_GLYPHS, HOSTVEIL_LAYOUT, HOSTVEIL_AI_PROVIDER, HOSTVEIL_OLLAMA_HOST, HOSTVEIL_OLLAMA_MODEL, ANTHROPIC_API_KEY, HOSTVEIL_ANTHROPIC_MODEL, HOSTVEIL_OPENAI_BASE_URL, HOSTVEIL_OPENAI_API_KEY, HOSTVEIL_OPENAI_MODEL, and NO_COLOR — each only when it is actually set, so a host with none of them builds exactly the command it always did. explain elevates like every other root-benefiting command, so a credential that did not survive the re-exec would fail the same way an unreachable provider does — quietly — which is exactly what carrying it here prevents. HOSTVEIL_NO_SUDO is not carried because reaching the re-exec at all means it was unset, and HOSTVEIL_ELEVATED is not carried for the reason below.

HOSTVEIL_DEBUG=1 hostveil scan
  runs:  sudo HOSTVEIL_DEBUG=1 /usr/local/bin/hostveil scan

This had to be built, because for a long time none of them crossed. HOSTVEIL_DEBUG=1 hostveil scan is printed in hostveil help, in the README and on the troubleshooting page as the thing to attach to a bug report, and on an ordinary non-root host it produced a normal scan, no trace, and nothing to suggest the variable had been discarded; a theme or glyph set was ignored the same silent way. Continuous integration never saw it, because the end-to-end job runs as root with HOSTVEIL_NO_SUDO=1 — both of the branches that skip the re-exec. Any variable not on the list above is still dropped by env_reset: use sudo -E, or add an env_keep entry for it.

What Hostveil honours from your environment

Hostveil reads some of these itself and inherits the rest through the terminal libraries the TUI is built on. None of them changes a finding, a score, or a fix — but several change what you are shown, and two change where files land.

Color and the terminal

The proxy variables, on the advisory explainer's request

Hostveil makes exactly one kind of network request of its own: the advisory explainer talking to whichever provider HOSTVEIL_AI_PROVIDER names. It uses Go's default HTTP transport, which honours the standard proxy variables.

Nothing else in Hostveil opens a socket. The scan reads files and runs local commands; the dashboard binds to loopback and serves; the CVE scan is Trivy’s own process with its own configuration.

Where Hostveil keeps things, and what it can find

sudo's secure_path replaces PATH outright in the elevated child on Debian and Ubuntu, so a re-executed Hostveil can resolve a different set of binaries than the process that started it would have.

DOCKER_HOST

The consequence is worth stating plainly: with DOCKER_HOST pointing elsewhere, the Compose, image-CVE, Docker-daemon and Docker-firewall domains describe a remote daemon while the SSH, sysctl, file-permission and account domains describe the local host — merged into one score, with nothing in any interface distinguishing them. That is occasionally what you want and is never what you want by accident. Unset it before scanning the machine you are sitting on.

Debug hooks the TUI inherits

The TUI is built on terminal libraries that carry their own debug switches. Hostveil neither sets nor clears them, and they are live on every hostveil tui run.

What Hostveil sets for the commands it runs

Hostveil passes its own environment through to every command it runs, with exactly one addition.

This exists because of a specific failure. Hostveil inherits the operator's environment and sudo keeps LANG and LC_* by default, so on a German host Hostveil asked apt in German and then looked for English. The string [upgradable from: %s] is translated in twenty-one locales, and the counter skipped every line that did not contain that exact English text: zero pending security updates on an unpatched machine, which is the failure class the whole tool refuses. A clean report you cannot trust is worse than no report.

LC_ALL rather than LANG, and this is the part worth remembering: gettext honours LANGUAGE over LANG, so pinning LANG alone would leave a desktop's LANGUAGE=de:en in charge. LANGUAGE is ignored when the locale is C, which is why this one variable is enough.

The locale does not change the layout, on purpose

The width library Hostveil links reads these at startup and sets a global that Hostveil then does not use — it builds its own measurement with East Asian width switched off. The obvious assumption is the opposite one, so it is worth stating positively: none of these four changes how a screen is laid out.

What it reads from the tooling around it

sudo sets this in the target environment itself rather than passing it through, which is precisely why env_reset cannot strip it and why it works where Hostveil's own marker could not. It is also set when the sudo target is not root, which is the case worth catching: on a host whose sudoers sets a non-root runas_default, the child comes back unprivileged and stops here instead of looping.

A false positive — SUDO_USER left in the environment by something other than the sudo that ran Hostveil — costs an unprivileged scan whose root-only domains report Skipped with a reason. That is the safe direction to be wrong in; an unbounded chain of password prompts is not.

What is not on this page

Test and build variables. The test suite reads a couple of variables the shipped binary never does, and the release build pins a couple more that do not exist at runtime. Neither is a knob on a running Hostveil, so listing them here would only invite someone to set one. They are documented where they are used, in the repository's development notes — see Contributing.

Variables Hostveil looks at, rather than reads. Some checks inspect environment variables belonging to your services: credential-shaped keys in a Compose file's environment: block, or in a container's .env. Those are data Hostveil examines on disk. It never reads your shell's environment looking for secrets, and nothing on this page is sent anywhere — every variable here is read locally and used locally.

Anything that relaxes a finding. There is no variable that changes a severity, adjusts the score, or makes a fix do less than it says. Detection is decided by the host, not by the environment; the variables that change what a scan covers do it by changing what Hostveil can reach — PATH, HOSTVEIL_NO_SUDO, and DOCKER_HOST.

HOSTVEIL_ASSUME_HOST is the one that comes closest, and it is worth being exact about. It does not turn a check off — it turns two back on, by answering a question about what kind of machine this is. Inside a container Hostveil declines to audit the host firewall and declines to offer the kernel-hardening fix, because neither can be acted on from in there; setting the variable says that this filesystem is the host you mean. It cannot make a finding smaller, and there is still no way to ask Hostveil to overlook one.