Skip to main content

Explain & Advise (+ optional AI)

A verdict you cannot understand is a verdict you will eventually override for the wrong reason. Every Belay decision therefore carries a plain-English explanation — why the action is risky and what to do about it — so you can approve or deny with context, not guesswork. Optionally, and off by default, you can layer a bring-your-own-key AI explainer on top for extra narrative. The AI is advisory only; it never makes or changes a decision.

When this matters​

The moment an ask lands in your terminal or a chat channel, you have seconds to judge it. The curated explanation gives you the facts every time — deterministic, local, and dependency-free. The AI explainer is there for the cases where you want a longer, situation-specific walkthrough, and it degrades silently to the curated text if anything goes wrong.

Curated explanations (always on, no config)​

Every rule ships with a hand-written explanation, surfaced with each verdict and in the desktop app. Each one has a consistent shape:

  • summary — one line: what just happened.
  • what — what the command or tool call actually does.
  • why_risky — the concrete threat (secret exposure, exfiltration, host damage, …).
  • normal_use — when this action is legitimate, so a false positive is easy to spot.
  • suggested_action — the recommended allow/deny/rework.

These are compiled in, local, and deterministic — no network, no key, no LLM.

Optional AI explainer (off by default, BYOK)​

For a richer, context-aware explanation you can enable an optional AI explainer. It is feature-gated and disabled by default; you turn it on deliberately.

Bring your own key / model:

  • Local — run Ollama on your own machine, no cloud, no key.
  • Cloud — Anthropic, OpenAI, Gemini, xAI, DeepSeek, Mistral, Groq, Cohere, Perplexity, Together, OpenRouter, or MiniMax, with a per-provider model picker.

The cloud key is pasted in-app (stored owner-only 0600 at ~/.belay/ai_key, write-only, never logged) or supplied via the BELAY_AI_KEY environment variable, which takes precedence over the in-app file.

Privacy: redaction before send​

Before anything is sent to a cloud provider, secrets and host paths are redacted from the payload. Cloud mode also requires explicit consent — it is never enabled silently. Local Ollama keeps everything on your machine.

danger

The AI explanation is advisory only. It never makes, overrides, or downgrades a decision — the deterministic engine (Deny > Ask > Allow, fail-closed) owns every verdict. If the AI call errors, times out, or is disabled, Belay falls back silently to the curated explanation.

Enabling it​

The AI explainer is configured through the setup wizard (belay setup) or the desktop app's AI Explanations tab: choose a provider, pick a model, and for cloud providers paste the key and confirm consent. Leaving it off costs you nothing — the curated explanations are always present.