Status & checks

vulnetix ai-firewall status

The single most useful command in the product. Run it after any change, and run it when something is not working.

What it shows

Gateway — which gateway, which organisation, where your credential came from, and whether inference logging is on.

Providers — every provider in the catalog, your organisation’s policy for it, whether a key is stored, and how it is wired.

Guardrails — your rules, in evaluation order.

Local clients — every AI client the CLI can find on this machine, and its state.

Checks — what is wrong.

Client states

StateMeaning
wiredConfigured, and pointing at your gateway.
points elsewhereConfigured — at something that is not your gateway.
not wiredInstalled, no gateway configuration.
manualThe CLI cannot write this client’s config (Cursor, Windsurf, Claude Desktop). You configured it, or you did not — the CLI cannot tell.
not installedNot on this machine.
Warning

manual is not wired. For clients the CLI cannot inspect, it cannot confirm anything — so the absence of a warning is not evidence that traffic is firewalled.

For those, verify end to end with a canary rule instead of trusting this output.

The checks

bypasses_firewall — warning

A client on this machine is talking to a provider directly.

The most important check here. It exists because the firewall is a control, not a cage: anyone can unset an environment variable, and an agent configured outside your policy is outside your policy.

Fix: vulnetix ai-firewall install <client>, or find out why someone unwired it.

provider_key_missing — error

No key in the vault for a provider you are trying to use. Every request to it will 403.

Fix: vulnetix ai-firewall key set <provider> --from-env <VAR>. See BYOK.

provider_denied — error

A client is wired to a provider your organisation has denied. Every request will 403.

Fix: either allow the provider, or rewire the client to one that is allowed.

model_denied / model_not_allowed — error

A client is configured with a model your policy refuses. model_not_allowed means the provider is in allowlist mode and this model is not on the list — which is the single most surprising behaviour in the product.

Fix: allow the model, or wire the client to one that is allowed. Note that vulnetix ai-firewall install --model validates against policy before writing, so wiring through the CLI cannot produce this state in the first place.

wire_unsupported — warning

A client is wired to a provider that does not serve the request surface it speaks. For example, Codex needs the responses surface, which only openai serves.

This is the local, ahead-of-time version of the gateway’s 404 unsupported_api. Better to find it here than at 3am.

Fix: wire the client to a provider that serves its surface. See base URLs & request surfaces.

key_env_unset — warning

A client is wired to read VULNETIX_API_KEY from the environment, and that variable is not set in this shell.

Fix: export it, or vulnetix ai-firewall install shell to write it into your shell rc permanently. Remember that a GUI application does not inherit your terminal’s environment.

guardrail_pattern_invalid — warning

A guardrail’s regex does not compile. The rule shows as enabled and enforces nothing.

This is the quietest, nastiest failure in the product, and this check is the main defence against it. The hint will usually tell you the cause — most often a lookahead or backreference, which RE2 does not support.

Fix: rewrite the pattern. See the regex reference. Better: manage rules with apply, which validates before anything is applied, so a bad pattern never reaches your policy.

In CI

vulnetix ai-firewall status --strict

Exits non-zero if any error-level check fails. Warnings do not fail the build.

Put it in front of any job that runs an agent, so a misconfigured runner fails loudly instead of quietly talking to a provider you did not approve.

Note The --strict help text says “Exit 2”. It currently exits 1. Gate on non-zero rather than on a specific code.

JSON output

vulnetix ai-firewall status -o json

The complete picture — policy, keys, clients, checks — in one document. This is the first thing to attach to a support request, and the right thing to feed to an observability pipeline.