Guard quick start

This guide gets you from zero to a running Guard stack locally, then shows the two adoption paths most teams use: self-hosted Molar API (full product) and GitHub Action only (plug-and-play PR checks).

Dashboard: app.molar.it/dashboard/guard · Product page: guard.molar.it

Prerequisites

Local development (full stack)

Download the Guard self-host bundle from your Molar account portal (or contact support@molar.it):

cp .env.example .env

1. Start infrastructure

docker compose up -d postgres redis seaweedfs

This brings up:

• Postgres — Guard data model (guard_runs, scheduled_checks, mender_attempts, scenario graph, etc.)
• Redis — BullMQ job queues (guard-pr, guard-schedule, mender) and SSE log streams
• SeaweedFS — local S3-compatible artifact storage (screenshots, video, HAR, traces)

Production deployments use AWS S3 or Cloudflare R2; SeaweedFS is the on-prem default.

2. Install and migrate

pnpm install
pnpm migrate

Migrations create all Guard tables: scheduled checks, runs, incidents, Mender attempts, scenario graph edges, guard_last_green_sha, and synthetic user records.

3. Start dev services

pnpm dev

Or run services individually:

Verify the API:

curl localhost:4000/healthz

Open the dashboard at http://localhost:3000 (or your configured port). In production, use app.molar.it/dashboard/guard.

Architecture at a glance

apps/api          Fastify REST + webhooks + SSE (:4000)
apps/worker       BullMQ: PR, schedule, mender, ops pollers
apps/dashboard    Next.js UI
apps/cli          molar-guard CLI
apps/mcp          MCP server (stdio)
apps/action       GitHub Action bundle
packages/*        core, runner, affected, github, mender, monitor, synthetic-middleware

CLI reference

The CLI ships as molar-guard (and alias molar) from apps/cli. Use it for local runs, affected detection, and schedule management.

Run a scenario

pnpm molar-guard run <slug> --base-url http://localhost:3010

Runs a single scenario against the given base URL. With Clones enabled in molar-guard.config.ts, vendor calls route to local fakes.

List scenarios

pnpm molar-guard list

Discovers scenarios from your configured source adapter: Playwright (npx playwright test --list), .molar/scenarios/*.molar.md, or glob patterns.

Affected scenarios (PR simulation)

pnpm molar-guard affected --base <sha> --head <sha>

Prints which scenarios would run for a diff between two commits — the same logic the PR gating worker uses. Useful for debugging "why did Guard run these tests?"

Schedule management

# Create a production monitor (every 5 minutes)
pnpm molar-guard schedule create <slug> --cron "*/5 * * * *"

# List, update, pause schedules
pnpm molar-guard schedule list
pnpm molar-guard schedule pause <id>

Schedules enqueue guard-schedule jobs on the worker. Configure regions, shadow_prod, and alert policies in the dashboard or via REST (see Production monitoring).

Verify your install

pnpm test
bash scripts/verify-phase-0.sh
bash scripts/verify-e2e.sh
bash scripts/verify-independence.sh   # vanilla Playwright, no Clones required

verify-independence.sh confirms Guard works as a plug-and-play runner — no Molar Molar API, no Clones, no .molar.md files required.

GitHub Action path (fastest adoption)

For teams that want a hosted PR check without self-hosting, add one workflow file. The Action calls Guard's API to run a registered scenario (by UUID) against your preview URL and posts the result as a GitHub Check.

For affected-scenario selection across your whole catalog, install the GitHub App instead — webhooks enqueue the full PR gating worker.

Steps

1. Sign up at app.molar.it
2. Import or create at least one scenario in the dashboard (copy its UUID)
3. Create an API key at Settings → API keys
4. Add MOLAR_API_KEY to your repository's GitHub Actions secrets
5. Copy the workflow below to .github/workflows/guard.yml

Example workflow

# .github/workflows/guard.yml
name: Molar Guard
on: [pull_request]

jobs:
  guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      # Your normal install + build steps
      - run: npm ci

      # Optional: deploy preview and capture URL
      # - id: deploy
      #   uses: your-platform/deploy-action@v1

      - uses: molar/guard-action@v1
        with:
          api-key: $\{\{ secrets.MOLAR_API_KEY \}\}
          scenario-id: "00000000-0000-0000-0000-000000000001"  # from dashboard

          # Optional: preview/staging URL under test
          # base-url: $\{\{ steps.deploy.outputs.url \}\}

          # advisory = warn only (default)
          # required = fail the job on scenario failure
          mode: advisory

Action inputs

The Action starts a manual run via POST /v1/runs/manual, polls until completion, and respects mode for job failure. No @molar/* packages need to be installed in your repository.

Full PR gating setup (GitHub App, affected selection, caching): PR gating

GitHub App path (full PR gating)

For affected-scenario selection, sticky PR comments, Mender integration, and Check Run lifecycle managed by webhooks:

1. Install the Molar Guard GitHub App from guard.molar.it or the dashboard onboarding wizard
2. Grant the required permissions (see PR gating)
3. Enable repositories and open a test PR

The App receives pull_request webhooks, enqueues guard-pr jobs, and updates Check Runs without a workflow file (though many teams use both App and Action).

Optional configuration

Create molar-guard.config.ts in your repo root when you need more than defaults:

export default {
  source: "playwright", // auto | playwright | molar-md | glob
  baseUrl: {
    pr: process.env.PREVIEW_URL ?? "http://localhost:3200",
    schedule: "https://app.example.com",
  },
  clones: { enabled: true },
  mender: { mode: "suggestive" },
  required: false, // advisory until you flip branch protection
};

See Configuration reference for all options.

Environment variables (self-hosted)

Key variables in .env (see .env.example in the repo):

What to do next

Troubleshooting

• API won't start — confirm Postgres and Redis are up (docker compose ps)
• No scenarios discovered (CLI) — check playwright.config.ts path and molar-guard.config.ts source / globPatterns
• Action fails immediately — confirm scenario-id is a valid UUID from the dashboard
• Check Run stuck queued — verify worker is running and guard-pr queue is draining
• Clones errors — set MOLAR_CLONES_ROOT or disable Clones in config for plug-and-play mode

See Troubleshooting for full runbooks.