Mergen Quick Start

Prompts are not enforcement. Mergen is the inline gate that physically blocks hazardous AI agent actions before they reach your runtime, databases, or cloud infrastructure.

You install one thing: mergen-server — the runtime every surface connects to. The CLI operates it, the Local Runtime Console (mergen-server dashboard) shows this machine's activity, the Organization Governance Console (mergen-server governance, mergen.app) governs policy/members/billing across the team, AI agents reach it through MCP, and CI through the GitHub Action.

Pilot success condition: Mergen is running on your machine, the local policy gate is intercepting tool calls, and the Agent Blunder Log has at least one entry.

Install

npm install -g mergen-server

Or run without installing:

npx mergen-server

Step 1 — Start the server (30 seconds)

mergen-server start

The server binds to 127.0.0.1:3000 by default. Nothing leaves your machine.

Verify the gate is live:

curl http://127.0.0.1:3000/health

Expected: { "ok": true, "gate": "active", ... }

Step 2 — Add to your AI IDE

The gate only intercepts calls that pass through Mergen's MCP server. Register it:

# Guided setup — detects your IDE automatically
mergen-server setup

# Or manually for Claude Code
claude mcp add mergen --transport stdio -- mergen-server start

One-click installs:

Restart your IDE after setup.

Cursor and Windsurf are VS Code forks and can install the same Mergen panel that ships to the VS Code Marketplace (via OpenVSX, which is what non-Microsoft forks use) — search "Mergen" in the Extensions panel for live status and one-click account connect, on top of the MCP config above.

Connect an account (optional)

Every decision above — pass, block, hold — runs identically with or without an account. Connecting one only matters for org-wide usage aggregation, seats, paid-plan features (Team seats, the Sync Plane, PR comments), and managing billing/organization at mergen.app/settings.

mergen-server login

Opens a browser for one-click device approval — the same flow as the "Connect Account" button in the VS Code panel. Already subscribed on another machine? This links the same account to this install, it doesn't create a new one.

Step 3 — Verify the gate is intercepting

Ask your AI agent to run a destructive command. The gate should block it before the handler runs:

# In your AI IDE, ask:
"Run: terraform destroy prod"

Expected response from Mergen:

🚫 Tool call blocked by Mergen local policy gate.
Tool: execute_fix
Reason: Local Gate: Destructive command pattern matched.
This action was logged to the Agent Blunder Log (GET /agent-blunders).

Check the Agent Blunder Log:

curl http://127.0.0.1:3000/agent-blunders | jq '{total: .stats.total, byType: .stats.byType}'

If you see "total": 1 — the gate is working. Pilot complete.

Step 4 — Configure HITL approval for schema mutations

Schema migrations are held (not blocked) until a human approves. Set a webhook URL and any migration command will suspend until you click Approve or Deny:

MERGEN_HITL_WEBHOOK_URL=https://hooks.slack.com/... mergen-server start

In team/cloud mode, also set the externally reachable URL so Slack can POST the callback:

MERGEN_PUBLIC_URL=https://mergen.your-company.com mergen-server start

Test it — ask your agent to run a migration:

"Run: prisma migrate deploy"

Mergen suspends the call and fires the Slack webhook. Your IDE waits. Click Approve — execution resumes. Click Deny — MCP error returned.

Step 5 — Connect your incident data (optional)

Once the gate is running, connect production signals to enable root cause analysis:

# Docker logs — streams all running containers, zero config
curl -X POST http://127.0.0.1:3000/watchers/docker

# PagerDuty — in PagerDuty: Service → Integrations → Webhooks
# URL: https://your-host:3000/webhooks/pagerduty
export MERGEN_PAGERDUTY_SECRET=your-pd-signing-secret

# OpenTelemetry (any language — one env var)
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:3000 node app.js

# Datadog (trace fetch + blame attribution)
export DD_API_KEY=... DD_APP_KEY=...

In your IDE:

"What caused the last incident?"
"Triage the api-service"

Step 6 — Shadow mode (30-day trust track record before autopilot)

Before enabling autonomous execution, run in shadow mode. Mergen evaluates every incident, records what it would have done, and posts to Slack — without executing anything:

MERGEN_SHADOW_MODE=true \
MERGEN_SLACK_BOT_TOKEN=xoxb-... \
MERGEN_SLACK_CHANNEL=#incidents \
mergen-server start

After 30 days, pull the shadow report:

curl http://127.0.0.1:3000/shadow-report
# → totalEvaluated, wouldHaveBlocked, corpusMatches

This is the evidence package your CISO needs before you flip the autopilot switch.

Step 7 — Build the Override Corpus

Every human override becomes enforcement policy. Two automatic sources:

Slack postmortems — scans your incident channel for override patterns and encodes them:

MERGEN_SLACK_OVERRIDE_LOOP=true mergen-server start

Git ADRs — reads architectural decision records and materialises operational constraints:

MERGEN_GIT_ADR_SYNC=true mergen-server start

Check what's been encoded:

curl http://127.0.0.1:3000/override-corpus | jq '.summary'

After 30–90 days the corpus contains your team's specific enforcement policy — Friday settlement windows, compliance holds, infrastructure constraints — impossible to replicate from a standing start.

Step 8 — Enable autopilot (after shadow track record)

MERGEN_AUTOPILOT=true \
MERGEN_SHADOW_MODE=false \
MERGEN_PAGERDUTY_SECRET=... \
mergen-server start

PagerDuty triggers → Mergen analyzes → fixes at ≥85% confidence → validates → posts audit trail to Slack. Every action stays within the policy bounds the gate enforces.

CI/CD Safety Gate

There are two separate CI gates, gating two different things — use either or both:

Change Authorization Gate — reviews the diff (the one that posts a PR comment)

This is what evaluates a PR against your override corpus, blast-radius, and the Change Authorization Gate's deterministic detectors (secrets, deleted tests, auth-bypass, CI-check removal, permission/config weakening) plus a task-to-diff scope check. It's the bundled composite action.yml, invoked with uses:, not a CLI subcommand — mergen-server ci is a server boot smoke test used elsewhere in CI/release pipelines, and does not call this gate, so it can't be substituted in for it:

# .github/workflows/mergen-aeg-gate.yml — distinct from mergen-gate.yml below,
# which gates a manifest of literal commands, not the PR diff.
name: Mergen AEG Gate
on: [pull_request]
permissions:
  pull-requests: write   # required to post the PR comment and apply the review label
  statuses: write        # required for the commit status (branch protection)
jobs:
  gate:
    runs-on: ubuntu-latest
    env:
      MERGEN_SECRET: ${{ secrets.MERGEN_SECRET }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22.x

      - name: Start the gate
        run: |
          npm install -g mergen-server
          # Provision the team policy if it's committed in the repo.
          if [ -f .mergen/enterprise-policy.json ]; then
            mkdir -p "$HOME/.mergen"
            cp .mergen/enterprise-policy.json "$HOME/.mergen/enterprise-policy.json"
          fi
          mergen-server start > mergen-server.log 2>&1 &
          for i in $(seq 1 30); do
            curl -sf http://127.0.0.1:3000/health >/dev/null 2>&1 && exit 0
            sleep 1
          done
          echo "::error::mergen-server failed to start"; cat mergen-server.log; exit 1

      # Pin to a release tag once one exists (@main tracks the default branch).
      - name: Gate the change
        uses: omertt27/Mergen@main
        with:
          mergen-url: http://127.0.0.1:3000
          mergen-secret: ${{ secrets.MERGEN_SECRET }}
          # Optional: enables the Change Authorization Gate's task-to-diff scope
          # check. Omit both and it's skipped — everything else still runs.
          # Falls back to `Mergen-Task:` / `Mergen-Plan:` trailer lines in the
          # PR body if you'd rather have the agent write them there.
          # task-description: ${{ github.event.pull_request.title }}
          # plan-summary: ''

AI-generated PRs that touch areas your team has historically overridden — or that a deterministic detector flags, or whose diff doesn't match the stated task — get blocked or routed to human review before merge. The action posts a structured PR comment (updated in place on every push, not reposted) with verdict, risk score, and reasons, applies a mergen/needs-human-review label when a human review is required, and sets a mergen/aeg-gate commit status you can require via branch protection ("require status checks to pass before merging"). Full input/output reference is in action.yml's own description: and inputs: blocks.

Command Execution Gate — gates a manifest of literal deploy/infra commands

A separate, narrower mechanism: runs Gate A (the same policy engine your local hook uses) against an exact list of commands you maintain in .mergen/ci-gate-commands.txt (e.g. terraform apply -auto-approve, a migration script) — for teams whose real risk is a specific deploy step, not the PR diff in general. See .github/workflows/mergen-gate.yml in this repo for the full example; it's opt-in and a no-op until that manifest file exists.

Policy configuration

The local gate is configured by ~/.mergen/enterprise-policy.json — created automatically on first start. Edit it to add your own rules:

{
  "enabled": true,
  "rules": [
    {
      "id": "no_prod_deploys_friday",
      "name": "Block production deploys on Fridays",
      "action": "block",
      "reason": "No production deploys after 14:00 UTC on Fridays.",
      "conditions": {
        "commands": ["deploy", "helm upgrade", "kubectl apply"],
        "actorType": "ai",
        "daysOfWeek": [5],
        "hourWindow": [14, 24]
      }
    }
  ]
}

Changes are hot-reloaded — no server restart required.

Check integration status

mergen-server doctor

Prints a health report of every integration with exact export commands for anything missing.

Troubleshooting

Questions? Open an issue · Full docs → · Design partner program →