Configuration
Belay is local-first and works out of the box with no configuration. This page documents the user-facing paths and environment variables you may want to set. All state lives under your home directory; nothing is sent off-host by default.
When to use this
Reach for this page when you want to relocate state, point the scanner's optional LLM cascade at a provider, enable the optional AI explainer, or understand the on-disk file layout.
Data directory & state
Everything Belay writes lives under ~/.belay/ on Linux/macOS (and
%ProgramData%\Belay on Windows), owned by the invoking user (the daemon
never runs as root):
| Path | Contents |
|---|---|
~/.belay/ | Belay's per-user state directory |
~/.belay/belayd.sock | The daemon's local IPC socket, which the per-user hook connects to |
~/.belay/audit.ndjson | The hash-chained, tamper-evident audit log (newline-delimited JSON) |
~/.belay/ai.json | AI-explainer settings (provider, model, on/off) |
~/.belay/ai_key | Cloud AI provider key — owner-only 0600, write-only, never logged |
~/.belay/channels.json | Messaging / approval channel configuration |
~/.belay/ssh_guard.json | SSH-guard settings |
~/.belay/net_enrich.json | Egress destination enrichment settings |
~/.belay/feed_state.json | Advisory feed state |
~/.belay/state.db | Local state database |
~/.belay/honeypot/ | Planted honeypot canary files |
Each audit row is hash-chained: it carries a prev_hash plus a sha256 over the
canonical (recursively key-sorted, whitespace-free) JSON of the row, so any edit
is detectable.
Most commands accept --home <path> to point at an alternate home directory,
which relocates both the state directory and the agent configs Belay reads. The
serve command additionally accepts --audit <path> to read a specific
audit log.
Because the daemon runs as the invoking user, its socket and audit log live under
that user's ~/.belay/. If you install the boot-start service, it is scoped to
the user you install it for.
Environment variables
All Belay environment variables use the BELAY_ prefix (they were AIDEFENDER_*
before the rename). All are optional.
| Variable | Purpose |
|---|---|
BELAY_BIN | Path to the belay binary (used when re-pointing hooks). |
BELAY_SOCK | Override the daemon IPC socket path. |
BELAY_ADMIN_PASSWORD | Admin password for privileged runtime operations. |
BELAY_AI_KEY | Cloud AI provider key for the AI explainer; takes precedence over the in-app ai_key file. |
BELAY_NVD_API_KEY | Advanced / self-hosted only. End users never need this — the vuln DB is bundled. |
BELAY_APPROVAL_TIMEOUT_MS | How long an ask waits before it auto-denies (fail-closed). |
BELAY_ECOSYSTEM | Build-time selector for which per-ecosystem advisory DB is compiled in. |
Agent configuration
You do not hand-edit agent configs. belay protect <agent> installs the correct
interception for a detected agent (JSON hook, Cursor hook, Hermes YAML hook,
OpenClaw exec-policy, or the mcp-proxy gate), and belay unprotect <agent>
restores the original. Use --observe on protect for a log-only dry run. See
CLI Commands.
AI explainer (optional, OFF by default)
Every verdict already carries a curated, plain-English explanation
(summary / what / why_risky / normal_use / suggested_action). You can
optionally enable an AI explainer for richer, context-aware wording. It is
feature-gated and OFF by default, and it is advisory only — it never
makes or changes a decision, and any error silently falls back to the curated
explanation.
- Local (no key): point it at a local Ollama instance.
- Cloud (BYOK): Anthropic, OpenAI, Gemini, xAI, DeepSeek, Mistral, Groq, Cohere, Perplexity, Together, OpenRouter, or MiniMax, each with a per-provider model picker. Cloud mode requires explicit consent.
The cloud key is pasted in-app (stored owner-only 0600 at ~/.belay/ai_key,
write-only, never logged) or supplied via BELAY_AI_KEY. Secrets and host paths
are redacted before any send.
Scanner LLM cascade (optional)
Separately from the AI explainer, the static scanner's --llm flag enables an
optional cascade that filters false positives. Providers are selected from the
environment and tried in order, falling back to a deterministic heuristic when
none are configured. With no keys set, the scanner runs heuristic-only —
identical to the pure deterministic path — so these variables are entirely
optional.
| Variable | Enables | Notes |
|---|---|---|
ANTHROPIC_API_KEY | Anthropic provider | Model claude-sonnet-4-5 |
OPENAI_API_KEY | OpenAI provider | Model gpt-4o |
OLLAMA_BASE_URL | Local Ollama provider | Pair with OLLAMA_MODEL (default llama3) |
OLLAMA_MODEL | Ollama model override | Optional; defaults to llama3 |
# Example: run the scanner with the LLM cascade, using a local Ollama model
export OLLAMA_BASE_URL=http://127.0.0.1:11434
export OLLAMA_MODEL=llama3
belay scan ./some-package --llm
The cascade only ever filters the deterministic findings — it never invents new ones and never sits on the gating hot path. The runtime tool-call engine is always LLM-free.
Messaging / approval channels
Channels are configured through the setup wizard or the desktop Messaging tab
and stored in ~/.belay/channels.json. They run inside the daemon's ASK fan-out.
Two-way approvals work over Telegram, Discord, WhatsApp, Matrix, Mattermost, and
Slack; ntfy, Microsoft Teams, WeCom, generic webhook, and the terminal are
notify-only. Approver enrollment is owner-gated and default-deny: the app shows a
one-time code and the approver DMs pair <code> to the bot to become authorized.
Egress destination enrichment (optional, OFF by default)
Outbound destinations can be annotated with reverse-DNS hostname plus
ASN/owner/country (via trippy-dns, no API key and no bundled data), stored in
~/.belay/net_enrich.json. It is display-only — shown as a
hostname · AS<n> <name> · <cc> chip on the egress allowlist and activity feed —
and never gates a decision.
Bundled vulnerability database
The vulnerability database ships bundled per ecosystem and needs no NVD
key. The ecosystem is selected at build time via BELAY_ECOSYSTEM, so the
binary carries the advisory data relevant to your stack. At runtime, lookups are
local and offline, and reports surface CISA KEV and EPSS enrichment. See
Firewall & Bundled Vuln DB.