Detect & protect an agent
Belay wires itself into an AI coding agent at the tool-call boundary. The two commands
that do the wiring are protect and unprotect; detect is the discovery step that
tells you what is installed and how Belay will intercept it. The setup wizard chains all
three for you.
When to use
- Run
belay setupfor a guided first run that detects, protects, and configures the rest. - Run
detecton any machine where AI coding agents run, to see what is present and which risky flags are enabled. - Run
protect <agent> --observeto wire in log-only mode and tune false positives. - Run
protect <agent>to switch on enforcement. - Run
unprotect <agent>to cleanly back out and restore the original config.
Setup wizard
The fastest way to get protected:
belay setup # interactive: detect -> Quick vs Custom -> protect + configure
belay setup --yes # apply Quick-setup defaults non-interactively
The wizard detects installed agents, asks whether you want Quick or Custom, then protects
the chosen agents and optionally configures the firewall, the AI explainer, messaging
channels, a vuln-scan schedule, and the boot-start service. The installer runs
belay setup for you automatically unless you pass --skip-setup.
Supported agents
belay detect runs its detectors and reports each agent's config paths, risky flags, and
how Belay intercepts it. Belay auto-detects a broad and growing set of agents, including:
| Agent | Detected via | Interception |
|---|---|---|
| Claude Code | ~/.claude/ or claude on PATH | hook (settings.json) |
| Codex | ~/.codex/ | hook (settings.json) |
| Cursor | ~/.cursor/ | Cursor hooks |
| Cline | ~/.cline/ or the editor's global storage | mcp-proxy |
| Roo | ~/.roo/ or the editor's global storage | mcp-proxy |
| Gemini CLI | ~/.gemini/ | config-policy |
| Goose | ~/.config/goose/ | config-policy |
| OpenClaw | ~/.openclaw/ | exec-policy |
| Hermes | ~/.hermes/ | YAML pre_tool_call hooks |
| Antigravity | its config dir | agent-correct interception |
| opencode | its config dir | agent-correct interception |
...and more. The list keeps growing as new agents ship.
The interception style is agent-correct — Belay installs the right mechanism for each
agent. Claude Code and Codex support native PreToolUse/PostToolUse hooks; Cursor uses
its own hooks; Hermes uses its YAML pre_tool_call hooks; OpenClaw uses an exec-policy;
MCP-server agents are gated by routing through mcp-proxy.
Steps
1. Detect installed agents
belay detect
This prints every detected agent, its config path(s), any risky flags it found (for
example a "bypass permissions" or "full access" mode), and the interception method. For a
machine-readable report, add --json:
belay detect --json
2. Protect in observe (dry-run) mode
Start log-only so you can see what would be denied without blocking anything:
belay protect claude-code --observe
In --observe mode, decisions are written to the audit log but never enforced. Let your
agent run its normal workload, then review the rows:
belay logs -n 100
Observe mode is the recommended first step in any new environment. It surfaces false positives against your real workflow before enforcement is ever in the hot path.
3. Switch on enforcement
When the observed decisions look right, enable enforcement:
belay protect claude-code
From here, dangerous actions are blocked outright, ambiguous-but-risky ones escalate
to a human for Allow / Deny (in the terminal, the desktop app, or a chat channel), and
everything is audited. The decision engine is deterministic and fail-closed — timeouts and
errors resolve to deny, and a deny is never downgraded by the allowlist.
4. Check status
belay status # last 20 audit rows
5. Unprotect when you are done
belay unprotect claude-code
This removes Belay's hooks / MCP rewrites and restores the agent's original configuration.
Common flags
| Flag | Applies to | Purpose |
|---|---|---|
--observe | protect | Log-only dry-run; nothing is blocked. |
--json | detect | Emit a machine-readable detection report. |
--home <path> | detect, protect, unprotect, setup | Point at a non-default home directory. |
--yes | setup | Apply Quick-setup defaults without prompting. |
Troubleshooting
detect finds nothing. Confirm the agent is installed for the current user and that
its config directory exists (see the table above). If the agent is installed under a
different home, pass --home <path>.
An agent still runs unguarded after protect. Restart the agent so it re-reads its
config, and confirm the daemon is running (belay daemon, or install it as a service —
see CLI overview).