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.

Prebuilt installers (all platforms)​

Every platform now ships a prebuilt desktop installer from the same GitHub release — the CI builds and publishes them for Windows, macOS (both architectures), and Linux. The belay CLI is bundled alongside the app in each one. The landing page at belay.secblok.io auto-detects your OS and links the right file; the direct links are:

PlatformInstaller
Windows x64belay-setup-x64.exe
macOS Apple Siliconbelay-aarch64.dmg
macOS Intelbelay-x64.dmg
Linux (Debian/Ubuntu)belay-amd64.deb
Linux (portable)belay-amd64.AppImage

Each asset has a companion .sha256 in the release; verify it before running. On Windows, the one-command installer (irm .../install.ps1 | iex) fetches and runs the .exe for you.

warning

The Windows installer is not yet code-signed (pending a certificate), so SmartScreen may show "Windows protected your PC." Click More info → Run anyway — the SHA-256 check confirms the download is intact. macOS .dmg builds are likewise unnotarized today, so first launch may need right-click → Open.

Build the desktop app from source​

Contributors can build the app themselves (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

A bare cargo build inside desktop/src-tauri produces a compile-check-only binary — it skips beforeBuildCommand, so the frontend is never embedded and the window opens blank white. To get a runnable binary without full packaging, go through Tauri: cd desktop/src-tauri && cargo tauri build --no-bundle.

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)