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​

  • Linux / macOS install script: just curl and bash (both preinstalled). 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.
  • Windows install script: Windows 10/11 x64 and PowerShell 5.1+ (preinstalled on every supported Windows release).
  • Build from source (secondary path, all platforms): a stable Rust toolchain (cargo). For the static musl target on Linux, install musl-tools.
  • Desktop app, building from source: Linux needs webkit2gtk; macOS needs the Xcode Command Line Tools; Windows needs the WebView2 Runtime (already present on a normal Windows 10/11 install) plus the MSVC Build Tools. None of this is needed if you use the one-command installers below — they ship a prebuilt desktop app.

Both installers verify a SHA-256 checksum against the published sums before installing anything, and refuse to proceed on a mismatch.

Downloads the platform-appropriate static belay binary (auto-detected — Linux x86_64, macOS Intel, or macOS Apple Silicon), verifies it, installs it to /usr/local/bin/belay, and runs the belay setup wizard:

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

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.

On Windows, the one-command installer above (irm .../install.ps1 | iex) already gives you the prebuilt desktop app — you don't need to build it yourself. On Linux and macOS, the desktop app isn't bundled into the CLI installer yet, so build it from source (see Prerequisites above for the per-platform system dependencies — webkit2gtk on Linux, Xcode Command Line Tools on macOS):

cd desktop && npm install
npm run tauri dev      # dev build: starts the frontend and the sidecar binary
npm run tauri build    # bundles the platform package: AppImage + .deb on
                        # Linux, a .dmg/.app on macOS, an NSIS installer on Windows

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)