Mergen FAQ

What is Mergen?

Prompts are not security boundaries; they're suggestions. AI agents don't know your security, infrastructure, or compliance constraints, and asking them nicely doesn't enforce those constraints.

Mergen is the Execution and Security Gateway for AI Agents. It sits inline between AI agents and your systems (a Claude Code/Windsurf Bash+Edit PreToolUse hook, a Cursor/VS Code self-heal watcher, and a mergen-server exec / gate-check CLI entrypoint) and physically intercepts tool calls before the handler runs. Every call is evaluated against a deterministic policy engine in under 1ms and either passes, gets blocked with a structured "why + what to do instead," or is held for human approval in Slack.

No probabilistic guardrails. No LLM in the critical path. Enforcement runs entirely on your machine: no network call decides pass, block, or hold.

Two audiences get distinct value:

• Individual developers: every unsafe command still gets blocked before it runs, on a single machine, for free (up to 1,000 tool calls a month; past that, enforcement pauses until the month resets). No reviewer, no one watching while you're not looking, no shared memory of past incidents. Mergen is the structural backstop for all three.
• VPs of Engineering and CISOs granting agents write access: the Override Corpus and Agent Blunder Log turn every human decision into binding, auditable enforcement policy. Before an agent repeats an action your team already rejected, it's blocked or held, and the block is logged.

Is it free?

Yes. The security gate itself is identical on every plan, including Free. Paid plans change delivery channels, collaboration, and visibility, never the verdict.

See mergen.app/pricing for the full breakdown.

Mergen is commercial software, not open source. You run it on your own machines under the license included with the package; you may not resell it or offer it as a hosted service.

Does my data leave my infrastructure?

It depends on whether you use My Organization. Enforcement is local in every case: the pass/block/hold verdict is computed on your machine and never waits on a network call. What changes is where the record of those decisions lives.

My Machine only (Free, or any install not linked to a paid organization): almost nothing leaves. Ingest binds to 127.0.0.1 by default (unreachable externally without explicit opt-in). Every plan, including Free, requires signing in once (no payment for Free), but a signed-in Free install reports exactly one thing: its cumulative tool-call count, so the 1,000/mo cap is server-authoritative and can't be reset by deleting a local file. (Policies → Describe it is a paid-plan feature: there, the sentence you typed, and nothing else, goes to Mergen's API where Claude drafts the rule; MERGEN_POLICY_DRAFT_AI=false keeps it local.) No machine identity/heartbeat, no command content, no audit or policy sync; every other sync module explicitly skips Free regardless of sign-in state. Your audit ledger, approvals and policy stay in ~/.mergen on your machine.

With My Organization (Team and Business): your data does not stay only on your machine. Once a machine is linked to a paid organization, it syncs to Mergen's hosted backend (api.mergen.app) by default, and that data is stored there, not just on your laptop. This is what powers the Governance Console's fleet view, approval inbox, team policy and audit dashboards; a shared view of many machines cannot exist without a shared store. Two different things sync, and the command text you actually typed is treated much more conservatively than the fact that something happened:

• Always synced (no command content):

  • Machine identity: hostname, platform, runtime + policy version (every 60s)
  • Usage counts: protected tool calls, seat count (every 5 min)
  • Integration health status only, never the credential itself (every 5 min)

• Synced, but the command argument itself is withheld by default: when a HOLD is placed, when it resolves, and for Agent Blunder Log entries, Mergen reports that it happened: tool name, timestamps, outcome, and a policy reason (always redacted of secrets before it's sent, regardless of this setting), but the raw command argument is null under the out-of-the-box configuration, because the cross-cutting MERGEN_CAPTURE_CLOUD_RETAIN ceiling defaults to local_only: nothing more sensitive than "a hold/blunder occurred" leaves the machine unless you loosen it. Set MERGEN_CAPTURE_CLOUD_RETAIN=match_local (with a permissive-enough local MERGEN_CAPTURE_TERMINAL_RETAIN) if you want the actual command text visible in the Governance Console's live approvals inbox and audit view; that's an explicit opt-in, not the default. See CONFIGURATION.md for both settings.

• Stored server-side by design: your organization's policy (authored in the console, then pulled down and enforced locally on each machine), plus account and membership data (email, organization, role) for sign-in and access control.

What that means in practice:

• It is not your infrastructure. The backend is operated by Mergen on third-party providers: the API runs on Railway and the database is Supabase-hosted Postgres (both currently in the EU), the console is hosted on Vercel, and sign-in goes through Clerk. Data is isolated per organization, but it lives on servers you don't control. See the Privacy Policy for the full subprocessor list.
• It outlives your machine. Audit and approval records in My Organization are kept for 400 days, including after a machine is removed or the organization is deleted. Deleting ~/.mergen removes the local copy only; to have server-side records erased sooner, email omer@mergen.app and we erase them and confirm within one month (they leave our encrypted backups as those expire, within 30 days).
• Metadata leaves even with content withheld. The default capture ceiling keeps command text local, but hostnames, timestamps, rule names, outcomes and approver identities still sync.

Local enforcement never depends on any of this succeeding, and keeps running identically with or without connectivity. If you want team policy and a fleet-wide audit trail with nothing leaving your infrastructure, point coordination at your own self-hosted Sync Plane instead of My Organization.

• A PII shield redacts emails, phone numbers, AWS keys, PEM certs, JWTs, and credit card numbers on write, before storage and before an AI response can ever see them.
• Admin secrets (MERGEN_ADMIN_SECRET, policy-signing keys) are env-only and never written to disk in production.

Which AI IDEs are supported?

• Claude Code (including the built-in Bash tool, via a PreToolUse hook: a genuine pre-write block)
• Windsurf (Cascade's pre_write_code/pre_run_command hooks: same tier as Claude Code)
• Cursor, per surface, because the two halves are genuinely different tiers:
  • shell — beforeShellExecution with failClosed: true: a real pre-exec block, same tier as Claude Code
  • edits — afterFileEdit detect-and-revert self-heal: the content briefly lands on disk before being reverted, so it is not a block
• Plain VS Code, via the Mergen extension's own document watcher (self-heal, same tier as Cursor)

A raw shell command typed outside an IDE isn't automatically covered; run it through mergen-server exec -- <cmd> to get the same gate explicitly.

How do I get started?

npm install -g mergen-server
mergen-server setup   # detects your IDE, installs the hook
mergen-server start

Then in your IDE, try something the gate should catch, like rm -rf, terraform destroy, or git push --force, and watch it get blocked with a structured alternative instead of executing.

Full guide: QUICKSTART.md

Doesn't my sandbox (Docker, Dev Containers, Codespaces) already handle this?

A sandbox and Mergen answer different questions. A sandbox decides where an agent can run and what it can reach: filesystem isolation, network boundaries, a disposable environment. It has no opinion on whether a specific action, once inside that boundary, should actually happen.

An agent with full permissions inside a properly-configured sandbox can still git push --force to the wrong branch, run terraform destroy against real infrastructure it has valid credentials for, or repeat an action your team rejected last week; the sandbox permits all of that correctly, because none of it violates isolation. Mergen is the layer that decides what's allowed, regardless of where the agent is running: the same deterministic gate whether the agent is on bare metal, in a container, or in a cloud dev environment.

They're complementary, not competing: run Mergen inside your sandbox of choice for defense in depth.

Why not just use my AI IDE's built-in allowlist/denylist?

Two reasons. First, coverage: an IDE-level allowlist typically governs that one IDE's shell tool; it doesn't follow the agent to a CI pipeline or a different IDE a teammate uses. Mergen's policy engine is the same engine everywhere it's wired in (every hook, the CLI, and a CI runner via mergen-server gate-check), so a rule written once applies org-wide, not per-tool.

Second, depth: a plain string allowlist is trivially defeated by encoding, quoting, or command chaining that changes the literal text without changing what the command does. Mergen's rules evaluate what a command actually does (AST-aware parsing, not text matching), which is why it holds up against obfuscation and evasion attempts that regex-based allowlists miss. See the benchmark methodology for the adversarial corpus this is tested against.

BLOCK vs. HOLD: can either be undone?

These are two different verdicts, and they're undone in two different ways. Don't conflate them:

• HOLD means the action needs a human decision: Mergen doesn't yet know if it's safe. Anyone with approver access resolves it directly: mergen-server approve <token>, a Slack button, or the IDE panel. The approval is honored for exactly one re-run of that exact command, within a bounded window (10 minutes by default). This is the only verdict with an agent-facing "request approval" path.
• BLOCK means the action violates policy: Mergen already knows the answer is no. There is no agent-facing appeal: the agent gets a structured reason and a suggested alternative, and reformulates. Nothing is sent for approval, and no one is asked to approve anything on the agent's behalf.

A BLOCK from a hard safety (immutable) rule is final, full stop: no override exists at any layer. A BLOCK from an operator-editable rule has one narrower, operator-only recovery path, separate from the HOLD/approval flow entirely:

• MERGEN_BLOCK_BYPASS=true (the default) lets an operator (not the agent, not an approver clicking a button) self-issue a single-use token from their own terminal to re-run a BLOCK from an editable rule. It's a recovery valve for a policy that's misfiring, not a request-and-approve exchange.
• mergen-server panic on --minutes 15 --reason "..." is the escape hatch for when a bad policy edit blocks everything: a bounded window (capped at 4 hours) where all calls pass, fully audited, ending automatically.

Every override, of either kind, is still written to the Agent Blunder Log and the audit trail. The trade is enforcement for recoverability, never enforcement for invisibility.

What happens if the gate is unreachable, or I'm offline?

Fail-open by default (changed 2026-09-19): if no decision can be obtained at all, the call proceeds unevaluated. The reasoning is that on a developer's own machine, a background daemon that died should not block every subsequent command. Set MERGEN_GATE_AVAILABILITY_MODE=fail-closed to block instead; recommended for shared machines, CI, and any deployment where the agent is less trusted than the developer running it.

Two things this does not change:

• A genuine policy BLOCK is enforced in either mode. The availability setting only governs the "we could not decide" case, never a decision Mergen actually reached.
• Internal faults still fail closed. A rule that throws, a corrupt policy file, or a command that won't parse resolves to BLOCK or HOLD, never a silent pass.

The honest consequence, stated plainly: under the default, an agent with shell access can run mergen-server stop && <anything> and the second command is not evaluated. fail-closed closes that.

The posture is also designed not to deadlock itself:

• gate-check auto-starts a missing local server (clean-unreachable case only, never a live-but-wedged one), so under either mode "nobody started the server" recovers to a real evaluation instead of simply allowing.
• A small set of Mergen's own recovery commands (mergen-server start/stop/doctor/approve <token>/trust-reset) are always recognized locally, without a network round-trip, so a wedged gate can never lock you out of the one command that fixes it.

Your machine's live setting is always visible: mergen doctor --security, or GET /coverage/reliability. See FAIL_OPEN_DESIGN.md for the full breakdown.

How are human approvals handled?

A HOLD suspends the tool call (the agent's Promise doesn't resolve) and, if Slack is configured, posts an approve/deny prompt to your team's channel. A human clicks one button; the call resumes or is denied. Unanswered holds fail closed: they auto-deny after 15 minutes rather than hanging indefinitely.

On the Free plan, a HOLD is still placed and logged locally with an explanation of why no Slack message was sent. Delivery channel is a convenience plans gate, not the safety decision itself. Business plan adds RBAC (who's allowed to approve what). Quorum rules (N distinct approvers required for the highest-blast-radius actions, e.g. terraform destroy) are configurable via MERGEN_HITL_QUORUM_RULES on every plan.

Full setup: HITL_SETUP.md.

Does Mergen inspect prompts, or only execution?

Primarily execution: the architectural bet is that a deterministic gate on what an agent is about to do is more reliable than trying to classify intent from what it said. That said, the gate does look at some call-level signal beyond a bare command string: multi-turn sequence detection (e.g. a chain of calls that adds up to credential exfiltration) and obfuscation/encoding checks that would otherwise hide a command's real intent from plain-text matching. Any such inference only ever escalates a call to HOLD for human review; it never itself produces a BLOCK or a PASS a hand-written rule wouldn't have produced on its own.

How does Mergen differ from monitoring and incident tools?

Those tools tell you after an agent has already done something: a crash, an alert, an incident. Mergen is inline, before the action executes: it's the deterministic gate that decides whether the call happens at all. The category is Agent Execution Governance, not observability. Mergen doesn't replace your monitoring stack: it's the enforcement layer that sits in front of it, so fewer of its alerts fire in the first place.

Full comparison: mergen.app/compare/mergen-vs-observability.

Can I use Mergen in a corporate or air-gapped environment?

Yes, on Free or with a self-hosted Sync Plane. The server binds to 127.0.0.1 by default: no external connections. Multi-user cloud mode (MERGEN_CLOUD_MODE=true) adds TLS, SHA-256 hashed API keys, and per-tenant isolation, but is opt-in; the local execution gate never requires it and works fully offline. Note that signing in to a paid plan against Mergen's hosted backend introduces the account-level sync described above; for a genuinely air-gapped deployment on a paid plan, use the self-hosted Sync Plane instead of the hosted api.mergen.app backend.

What's the performance impact?

• Policy evaluation: sub-millisecond (p50 well under 1ms, p99 low single-digit ms on the published benchmark corpus)
• The verdict itself is in-process: no LLM, no daemon, no external network; a decision never leaves your machine
• The CLI/IDE hook does make one 127.0.0.1 round-trip to the local server per command (plus a one-time port discovery on a cold start). This transport cost is deliberately excluded from the sub-millisecond figure above, which measures the verdict, not the hook.
• Memory: tens of MB for the server process

What does the published benchmark measure?

A reproducible adversarial corpus of real destructive commands, prompt-injection framings, obfuscation/evasion attempts, and benign look-alikes, scored against Mergen, a plain regex baseline, and an LLM judge. The full JSON baseline and methodology are public. See mergen.app/benchmarks and AGENT_RUNTIME_SECURITY_BENCHMARK.md for exact figures, category breakdowns, and disclosed evasion gaps. We publish what doesn't work, not just what does.

Can I use Mergen with my CI/CD pipeline?

Yes, by gating the commands the pipeline runs, not by scanning its diffs. Start the server in the job and pipe each deploy/infra command through mergen-server gate-check -- <cmd>: it hits the same Gate A policy engine your local IDE hook uses, and a non-zero exit fails the job. See QUICKSTART.md for a complete workflow.

Mergen deliberately does not ship a PR-time diff gate. One existed (a GitHub Action posting to POST /ci/gate) and was removed in September 2026: it duplicated enforcement Mergen already does earlier, at the moment the agent writes the file, and it made the product read as a PR scanner. The detectors it used (secrets, deleted tests, auth-bypass, CI-check removal, permission/config weakening) all survive — they now run at edit time, which is strictly earlier than merge.

Separately, build-status ingest (POST /ci/generic) correlates CI run outcomes with runtime errors by commit SHA for incident triage. That is not a gate. mergen-server ci is a different thing again: a server-boot smoke test.

More resources

• QUICKSTART.md: install and first block, in minutes
• CLI_REFERENCE.md: every command
• CONFIGURATION.md: every setting
• TROUBLESHOOTING.md: when something does not work
• ENTERPRISE_SECURITY.md: security and deployment for teams
• omer@mergen.app: bug reports and feature requests