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 local MCP proxy, plus a Claude Code Bash-tool hook 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. 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, including seats and overage rates.

The core server, SDKs, and IDE integrations are MIT-licensed. The policy engine and intelligence layer (calibration, corpus similarity, autonomous remediation planning) are Elastic License 2.0 — free for internal use, not for resale as a hosted service. See LICENSE.

Does my data leave my infrastructure?

On Free: no. Ingest binds to 127.0.0.1 by default — unreachable externally without explicit opt-in — and Free needs no account, so nothing is sent anywhere. Enforcement data (events, policy) is stored locally (SQLite) or in your own cloud-mode Postgres — never a third-party datastore.

On a paid, signed-in plan: some account-level telemetry syncs to Mergen's own hosted backend (api.mergen.app) by default, to power the Governance Console's fleet visibility, approval inbox, and audit dashboards. 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.

This is Mergen's own infrastructure, isolated per organization, not a third party — but on a paid plan it is not exclusively your infrastructure, and the metadata above still leaves the machine by default even with command content withheld. Local enforcement itself never depends on any of this succeeding, and keeps running identically with or without connectivity. For a fully self-contained deployment on a paid plan, point coordination at your own self-hosted Sync Plane instead.

• A PII shield redacts emails, phone numbers, AWS keys, PEM certs, JWTs, and credit card numbers on write, before storage — 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)
• Cursor
• Windsurf
• VS Code (with an MCP-compatible extension)
• Any IDE that implements the Model Context Protocol (MCP)

Every MCP tools/call is covered unconditionally on all of the above. A raw shell command typed outside an IDE — or a non-MCP tool call in an IDE without an equivalent hook — 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, writes MCP config
mergen-server start

Then in your IDE, try something the gate should catch — rm -rf, terraform destroy, 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, a different IDE a teammate uses, or an MCP tool call. Mergen's policy engine is the same engine everywhere it's wired in (every MCP client, the Claude Code Bash hook, the CI gate), 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 — and 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-closed by default: if a decision can't be obtained at all, the call doesn't proceed. That posture is deliberately designed not to deadlock itself — a few structural guarantees:

• gate-check auto-starts a missing local server (clean-unreachable case only, never a live-but-wedged one) so "nobody started the server" doesn't fail-close every command until someone reads the hook output.
• 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.
• MERGEN_GATE_AVAILABILITY_MODE=fail-open exists for onboarding only — a genuine policy BLOCK always blocks regardless of this setting, which only governs what happens when no decision is obtainable at all.

See FAIL_OPEN_DESIGN.md for the full breakdown of what fail-closed does and doesn't cover.

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. Growth plan adds RBAC (who's allowed to approve what) and quorum rules (N distinct approvers required for the highest-blast-radius actions, e.g. terraform destroy).

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. See ARCHITECTURE.md for the full Gate A / Gate B split.

How does Mergen differ from Datadog, PagerDuty, or Sentry?

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)
• No network calls on the enforcement path in local mode
• 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 — the bundled action.yml runs as a GitHub Actions workflow step, evaluating agent-generated PRs against blast-radius analysis, the override corpus, and the Change Authorization Gate (deterministic detectors for secrets, deleted tests, auth-bypass, CI-check removal, and permission/config weakening, plus a task-to-diff scope check) before merge — then posts a structured PR comment (updated in place on every push) and, when a human review is warranted, applies a mergen/needs-human-review label. It's a separate endpoint (/ci/gate) from the build-status ingest (/ci/generic), which just correlates CI runs with runtime errors by commit SHA. mergen-server ci is a different thing again — a server-boot smoke test, not this gate. See QUICKSTART.md for setup and CLAUDE.md for the distinction between these mechanisms.

More resources

• README.md — full product overview
• QUICKSTART.md — install and first block, in minutes
• INSTALL.md — all install methods
• ARCHITECTURE.md — the gate design in full
• docs/enterprise.md — enterprise deployment guide
• GitHub Issues — bug reports
• GitHub Discussions — feature requests