FAQ & Troubleshooting
Honest answers to the questions people ask most often about Belay.
How do I install Belay?
One command downloads the verified static binary and runs the setup wizard:
curl -fsSL https://dl.belay.secblok.io/install.sh | bash
It installs /usr/local/bin/belay, verifies a SHA-256 checksum against the
published SHA256SUMS before installing anything, then runs belay setup.
Prefer to review the script first?
curl -fsSL https://dl.belay.secblok.io/install.sh -o install.sh
less install.sh
bash install.sh
For a non-interactive, binary-only install (no wizard), append -s -- --skip-setup.
Distribution is R2-CDN-first (dl.belay.secblok.io) with GitHub Releases as a
fallback. Build-from-source stays supported as the secondary path:
cargo build --release --bin belay.
Which platforms does v0.1.0 support?
Released binaries: Linux x86_64 (fully-static musl — runs on any libc, glibc or musl), macOS x86_64 (Intel), and macOS aarch64 (Apple Silicon).
Is Linux aarch64 supported yet?
Not in v0.1.0. Linux aarch64 is coming soon but is not among the released binaries yet. Build-from-source may work on that target in the meantime, but it is not an officially published asset.
Is Windows ready?
Windows is supported in-tree — the named-pipe transport, the SCM service, and
the Tauri desktop app have all landed. The one remaining gap is the signed
installer, which is pending a code-signing certificate. On Windows,
install-service registers an auto-start service via the Service Control Manager
and needs an elevated (Run as Administrator) shell instead of sudo.
Does Belay run as root?
No. Belay runs as the invoking user, never root. Its socket and audit log
live under that user's ~/.belay/. Staying unprivileged is a deliberate design
choice — it means Belay cannot itself become a root-level foothold. The trade-off
is that true syscall-level prevention (which needs CAP_SYS_ADMIN/root) is out
of scope; Belay is detect-and-respond at the tool-call boundary. See
Self-Protection Layers.
Does it phone home?
No. Belay is local-first and does not phone home by default. State stays
under ~/.belay/; the bundled vulnerability database works offline; standards
tagging and SARIF export happen entirely on your host.
Does it use an LLM to decide whether to block something?
No. The runtime decision engine is deterministic — no LLM on the gating
path — and runs in the hot path in under 100ms. The same tool call always
produces the same verdict. There is an optional AI explainer (OFF by default)
that adds richer plain-English wording to a verdict, but it is advisory only:
it never makes or changes a decision, and any error falls back to the curated
explanation. The static scanner's --llm cascade is likewise off the hot path.
What does "fail-closed" mean here?
If the engine errors, times out, or an ask goes unanswered, the result is
deny — never a silent allow. Verdict priority is Deny > Ask > Allow, and
a DENY can never be downgraded by the dev-toolchain allowlist.
Which AI coding agents are supported?
Belay auto-detects and protects Claude Code, Codex, Cursor, Cline, Roo, Gemini
CLI, Goose, OpenClaw, Hermes, Antigravity, opencode, and more. Interception is
agent-correct: Claude Code / Codex get JSON hooks in settings.json, Cursor gets
Cursor hooks, Hermes gets its YAML pre_tool_call hooks, OpenClaw gets an
exec-policy, and MCP-server agents get the mcp-proxy gate. Run belay detect to
see what is installed on your machine.
Can I approve an ask from my phone?
Yes. When a verdict is ask, Belay can send the approval prompt to a chat
channel and take your Allow/Deny reply back. Two-way channels: Telegram,
Discord, WhatsApp, Matrix, Mattermost, and Slack (Block Kit buttons).
Notify-only channels: ntfy, Microsoft Teams, WeCom, generic webhook, and the
terminal. Approvers enroll by DMing a one-time pair <code> to the bot
(owner-gated, default-deny). Prompts auto-expire — a stale prompt auto-denies.
Configure channels in belay setup or the desktop Messaging tab.
Is serve a web dashboard?
No. serve is a local JSON/SSE API only on 127.0.0.1:8787; it serves
no HTML. The desktop app is the user interface — it connects to this backend
to render the Overview, Activity, Live Feed, Alerts, Scan, Agents, Host Protection, AI
Explanations, Messaging, and My Machines views. Pointing a browser at the port
shows raw API responses, not a UI.
How do I view the audit log?
Use belay status (last 20 rows) or belay logs -n <count> (last N
rows). There is no belay audit command.
Do I need an NVD API key for the vulnerability database?
No. The vulnerability database ships bundled per ecosystem and end users never supply an NVD key. Lookups are local and offline, and reports surface CISA KEV (known-exploited) badges and EPSS exploit-probability percentages.
Is the audit log tamper-evident?
Yes. Every row is hash-chained: each row's hash covers the previous hash plus
the canonical JSON of the row. belay evidence build / belay evidence verify
produce and check a SHA-256 manifest over findings + SARIF for a tamper-evident
pack.
What are honeypot canaries?
Decoy credential files — fake AWS credentials and a .env sentinel (the
BELAY_CANARY_TOKEN bait) — that no legitimate workflow should touch. Any read or
egress of their sentinel bytes trips a Critical verdict. See
Honeypot Canaries.
Does Belay need Python installed?
No. It is a single static Rust binary with no runtime Python dependency. On Linux the released binary is a fully-static musl build that runs on any libc.
What is the difference between the free and enterprise editions?
The Community edition is free and open-source (AGPL-3.0-or-later) and includes
everything documented on this site: runtime gating, the deterministic rule
catalog, session correlation, the scanner, the local backend and desktop app, the
native firewall, the bundled vulnerability database, evidence packs, honeypot
canaries, host protection, messaging approvals, and self-protection. Enterprise
(commercial license) adds the fleet plane, device enrollment, a command channel,
correlation, SSO + SCIM, a hosted curated feed, and a web console — all gated
behind the enterprise build feature and stripped from the open build. Contact
hello@secblok.io.
What license is Belay under?
Open-core. The open repository at github.com/SECBLOK/belay is licensed under GNU AGPL-3.0-or-later. A separate commercial license is available for AGPL-incompatible use and for the proprietary enterprise components — contact hello@secblok.io. Contributions require a CLA plus DCO sign-off.
Troubleshooting
A benign command keeps getting flagged. Run belay protect <agent> --observe
to log without blocking, review with belay logs, and confirm your workflow
before enforcing. The dev-toolchain allowlist already suppresses common build/VCS
commands.
Pointing a browser at 127.0.0.1:8787 shows raw JSON. That is expected —
serve is an API, not a web page. Use the desktop app as the UI.
The firewall shows an empty ruleset on macOS. Also expected — Linux-only enforcement layers compile inert on macOS and degrade cleanly. Host enforcement is fully active on Linux.