Skip to main content

Quickstart

Get Belay guarding an AI coding agent in about five minutes: install the single binary with one command, let the setup wizard detect the agents already on your machine and protect them, then start the local backend that the desktop app reads from. Prefer to drive it by hand? The manual detect → observe → enforce path is right below the wizard.

When to use this​

Follow this page the first time you set Belay up on a laptop or a headless VPS. It walks the shortest path from a fresh machine to a live, enforcing tool-call boundary. For deeper install options (build-from-source, musl static builds, the desktop app, boot-start service) see Installation; for the mental model behind the verdicts you'll see, read How it works.

Prerequisites​

  • A supported OS: Linux x86_64, macOS x86_64 (Intel), or macOS aarch64 (Apple Silicon). See Platform Support for the full v0.1.0 matrix.
  • At least one supported AI coding agent installed (Claude Code, Codex, Cline, Roo, Cursor, Gemini CLI, Goose, OpenClaw, Hermes, Antigravity, opencode, and more).
  • No Rust toolchain and no runtime Python dependency are required for the install-script path. No NVD or other data key is ever required from an end user — the vulnerability database ships bundled in the binary.

1. Install Belay​

One command downloads the verified static belay binary for your OS/arch, checks its SHA-256 checksum, installs it to /usr/local/bin/belay, and then runs the interactive setup wizard:

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

Prefer to read the script before running it (recommended):

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

Belay always runs as the invoking user, never as root. Its socket and audit log live under that user's ~/.belay/ (%ProgramData%\Belay on Windows).

2. Let the setup wizard protect your agents​

If you did not skip it, the installer hands straight off to the setup wizard. You can also run it any time:

belay setup

What it does: detects the AI coding agents installed on this machine, asks whether you want Quick (sensible defaults) or Custom, then protects the agents you choose and optionally configures the firewall, the AI explainer, messaging/approval channels, a vulnerability-scan schedule, and the boot-start service.

Non-interactive Quick defaults (handy for provisioning scripts):

belay setup --yes

To install the binary only and skip the wizard entirely:

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

If you took the Quick path, Belay is already detecting and protecting your agents — you can jump to step 6. The steps below show the same flow driven by hand.

3. Detect installed agents​

Ask Belay what it can see:

belay detect

What you'll see: a table of the AI coding agents found on this machine, each with its config path, any risky flags that are enabled (for example Claude Code's bypassPermissions, or Codex's danger-full-access), and how Belay would intercept it (a native JSON hook, a Cursor hook, a Hermes YAML hook, an OpenClaw exec-policy, or the MCP proxy). Add --json for machine-readable output.

4. Protect an agent in observe mode first​

Start in dry-run so you can watch what would be blocked without actually blocking anything. This is the recommended way to tune out false positives before you enforce.

belay protect claude-code --observe

What you'll see: Belay wires itself in at the agent's tool-call boundary (the interception is agent-correct — a JSON hook for Claude Code / Codex, a Cursor hook for Cursor, Hermes' YAML pre_tool_call hook for Hermes, exec-policy for OpenClaw, or the mcp-proxy gate for MCP-server agents) and begins logging would-be decisions to the audit log. In observe mode nothing is ever blocked — every decision is log-only.

tip

Let the agent run through its normal workflow in observe mode for a while. Review the decisions with belay logs (or belay status for the last 20 rows) and confirm nothing you rely on is being flagged before you move to enforcement.

5. Switch to enforcement​

When you're happy with what observe mode logged, re-run protect without the flag to start enforcing:

belay protect claude-code

What you'll see: from now on, dangerous tool calls are blocked outright (deny), ambiguous-but-risky ones pause the agent and wait for a human Allow / Deny (ask), and everything else proceeds (allow). The decision engine is deterministic and runs in the hot path — no LLM call, sub-100ms — and it fails closed: a timeout or an internal error becomes a deny, never a silent allow. A deny can never be downgraded by the allowlist. See Verdicts for the full model.

Every verdict now also carries a plain-English explanation (what happened, why it's risky, the normal use, and a suggested action). An optional AI explainer is available too (off by default) — see Installation.

6. Start the local backend​

serve runs a local API and Server-Sent-Events stream that the desktop app reads from:

belay serve

By default this binds 127.0.0.1:8787.

warning

serve is a local JSON/SSE API only — it is not a web dashboard. 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, and Messaging views. Point a browser at the port and you'll see raw API responses, not a UI.

7. Stop protecting (when you need to)​

To remove Belay's hooks and restore the agent's original configuration:

belay unprotect claude-code

Run it as a boot-start service (optional)​

For an always-on setup, install the resident daemon as a boot-start service (systemd on Linux, launchd on macOS, SCM on Windows). It runs the daemon as the invoking user, never root, so its socket and audit paths match where the per-user hook connects:

sudo belay install-service --enable

To remove Belay later:

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

See Installation for the full service walkthrough.