Skip to main content

Installation

Belay is a single static Rust binary (belay) plus an optional Tauri desktop app. This page covers the one-command installer (the primary path), building from source, installing the desktop app, and running the resident daemon as a boot-start service.

When to use this​

Read the Quickstart first for the five-minute path. Come here when you want the full detail on the installer's options, a build from source, a fully-static musl build, the desktop tray app, or an always-on service that starts at boot.

Prerequisites​

  • Install script: just curl and bash. No Rust toolchain, no runtime Python dependency, and no NVD or other data key is ever required from an end user — the vulnerability database ships bundled in the binary.
  • Build from source (secondary path): a stable Rust toolchain (cargo). For the static musl target, install musl-tools.
  • Desktop app (Linux): webkit2gtk for the webview, plus Node.js and npm to build the frontend assets.

The installer downloads the platform-appropriate static belay binary, verifies its SHA-256 checksum against the published SHA256SUMS, installs it to /usr/local/bin/belay, and then runs the belay setup wizard:

curl -fsSL https://dl.belay.secblok.io/install.sh | bash

Distribution is R2-CDN-first (dl.belay.secblok.io) with a GitHub Releases fallback, so platforms not yet mirrored to the CDN still install. The binary and its checksum file are always fetched from the same host, and the script refuses to install on a checksum mismatch.

Review before you run it​

If you'd rather not blind-pipe a script to bash:

curl -fsSL https://dl.belay.secblok.io/install.sh -o install.sh
less install.sh
bash install.sh

Binary-only / non-interactive install​

Skip the wizard and install just the binary (for images, CI, or provisioning):

curl -fsSL https://dl.belay.secblok.io/install.sh | bash -s -- --skip-setup

Any flag other than --skip-setup / --no-setup / -y is forwarded verbatim to belay setup (for example the wizard's own --yes).

Environment overrides​

VariableDefaultPurpose
BELAY_DOWNLOAD_BASEhttps://dl.belay.secblok.ioPrimary download host; GitHub Releases is always tried as a fallback.
BELAY_REPOSECBLOK/belayGitHub owner/repo used for the fallback.
BELAY_VERSION(latest)Pin a specific GitHub release tag (forces the GitHub source; the CDN mirrors only latest).
BELAY_INSTALL_DIR/usr/local/binWhere the binary is placed.

Build the binary from source​

The unified binary contains every subcommand:

cargo build --release --bin belay

The binary is written to target/release/belay.

Fully static musl build​

For a binary with no libc dependency — a single file you can drop onto any Linux host, glibc or musl — install musl-tools, then:

cargo build --release --target x86_64-unknown-linux-musl --bin belay

The repository's .cargo/config.toml points the target's C compiler at x86_64-linux-musl-gcc so aws-lc-sys links cleanly.

Run the test suite​

cargo test --workspace
tip

Copy the release binary somewhere on your PATH (for example ~/.local/bin/belay) so you can invoke subcommands directly. If you plan to run the boot-start service, install-service will stage a copy to a stable system path for you — see below.

Install the desktop app​

The desktop app is the graphical UI. It carries the refreshed brand (a faceted low-poly blue "B" icon) and a left sidebar: Overview, Activity, Live Feed, Alerts, Scan, Agents, Host Protection, AI Explanations, Messaging, and My Machines (plus the fleet console under a commercial license). It surfaces scanning, agent detection, protect/unprotect, the approval queue, AI explanations, messaging, and host protection — not just monitoring — with a system-tray icon and privacy-safe native notifications (category only, never the secret path). It reads ~/.belay locally.

To build it from source (Linux requires webkit2gtk):

cd desktop && npm install
npm run tauri dev      # dev build: starts the frontend and the sidecar binary
npm run tauri build    # bundles an AppImage + .deb

The Tauri build drives the web frontend, so it auto-installs the frontend dependencies on first run — no separate frontend setup step is needed for the desktop app.

note

The desktop app renders its views from the local backend that serve exposes on 127.0.0.1:8787. serve itself is API/SSE-only and serves no HTML; the desktop app is what you actually look at.

Optional features worth turning on​

The setup wizard can configure these, or you can enable them later from the desktop app:

  • AI explainer (off by default). Every verdict already ships with a curated, plain-English explanation. You can optionally add an AI explainer — a local Ollama model or a cloud provider (Anthropic, OpenAI, Gemini, xAI, DeepSeek, Mistral, Groq, Cohere, Perplexity, Together, OpenRouter, MiniMax) via BYOK. The cloud key is pasted in-app (stored owner-only 0600 at ~/.belay/ai_key, write-only, never logged) or via BELAY_AI_KEY. Secrets and host paths are redacted before any send, cloud mode requires consent, and the AI output is advisory only — it never makes or changes a decision, and any error falls back silently to the curated explanation.
  • Messaging / approval channels. When a verdict is ask, Belay can send the approval prompt to a chat channel and take your Allow/Deny reply back. Two-way: Telegram, Discord, WhatsApp, Matrix, Mattermost, Slack (Block Kit buttons). Notify-only: ntfy, Microsoft Teams, WeCom, generic webhook, terminal. Approvers enroll by DMing pair <code> to the bot (owner-gated, default-deny), and prompts auto-expire (stale => auto-denied).
  • Firewall. A native Rust firewall (via rustables, no shell-out to nft/iptables) with a manual and a one-click auto setup that previews the ruleset before applying it.
  • Vulnerability scanning. A bundled per-ecosystem advisory DB — no NVD key required — with CISA KEV (known-exploited) badges and EPSS exploit-probability percentages in reports. The wizard can add a scan schedule.

Run as a boot-start service​

For an always-on deployment, register the resident daemon as a boot-start service. One command stages the binary to a stable location (so the service survives a cargo clean), enables the service, re-points the agent hook at the staged binary, and waits for the daemon socket to come up:

sudo belay install-service --enable
  • On Linux this writes and enables a systemd unit.
  • On macOS it writes and loads a launchd service.
  • On Windows it registers a LocalSystem auto-start service via the Service Control Manager.

The daemon runs as the invoking user, never root, so its socket and audit log live under that user's ~/.belay/.

Useful flags​

Preview the generated unit without writing anything (no privileges required):

belay install-service --print

Skip staging and point the service at an existing binary path (handy for distro packaging):

sudo belay install-service --enable --exec-path /usr/bin/belay
warning

On Windows, install-service needs an elevated (Run as Administrator) shell instead of sudo. Windows support is in-tree, but the signed installer is still pending a code-signing certificate. See Platform Support.

Verify the install​

belay detect     # lists the agents Belay can see
belay status     # prints the most recent audit rows

Uninstall​

belay uninstall           # stop + remove the service, unit, and staged binary
belay uninstall --purge   # also delete ~/.belay (config, audit log, keys)