Configuration reference

molar-guard.config.ts, scenario frontmatter, environment variables, and plan-tier limits.

Configuration reference

Guard configuration lives at three layers:

  1. Repository file — molar-guard.config.ts (optional; plug-and-play works without it)
  2. Scenario frontmatter — .molar/scenarios/*.molar.md YAML headers
  3. Platform settings — dashboard + environment variables on the Guard API/worker

molar-guard.config.ts

The single optional config file in your repository root. If absent, Guard uses defaults (Playwright discovery, advisory mode, no Clones).

Supported filenames: molar-guard.config.ts, .js, .mjs, .cjs

Full example

const config = {
  // Source adapter: auto | playwright | molar-md | glob
  source: "molar-md",

  // Glob patterns when source = "glob"
  globPatterns: ["tests/e2e/**/*.spec.ts"],

  // Override Playwright command
  testCommand: "npx playwright test --project=chromium",

  // App URL per environment
  baseUrl: {
    manual: process.env.BASE_URL ?? "http://localhost:3200",
    pr: process.env.PREVIEW_URL ?? "http://localhost:3200",
    schedule: process.env.STAGING_URL ?? "https://staging.example.com",
  },

  // Start app with clone env injected (Playwright webServer)
  webServerCommand: "pnpm dev",
  webServerPort: 3200,

  // Clones integration (off by default for plug-and-play)
  clones: { enabled: true },

  // Mender behavior
  mender: {
    mode: "suggestive", // off | suggestive | aggressive
    forbiddenPaths: [
      "app/api/auth/**",
      "**/payment*",
      "**/security*",
      "migrations/**",
      "**/.env*",
      "infra/**",
    ],
  },

  // PR check blocks merge when true
  required: false,
};

export default config;

Field reference

FieldTypeDefaultDescription
source"auto" | "playwright" | "molar-md" | "glob""auto"How scenarios are discovered
globPatternsstring[]—Patterns for glob adapter
testCommandstringnpx playwright testTest runner invocation
baseUrl.manualstring—URL for CLI run
baseUrl.prstringPREVIEW_URL envURL for PR runs
baseUrl.schedulestring—URL for production schedules
webServerCommandstring—Command to start app (inherits clone env)
webServerPortnumber3200Port for webServer health check
clones.enabledbooleanfalseSpawn/use Clones on runs
mender.mode"off" | "suggestive" | "aggressive""suggestive"Mender automation level
mender.forbiddenPathsstring[]payment/auth/security defaultsGlob patterns Mender will not patch
requiredbooleanfalseRequired vs advisory PR check

Per-repo overrides can also be set in the dashboard: Settings → Repositories.

Scenario frontmatter (.molar.md)

When using the molar-md source adapter:

---
id: stripe-subscription-upgrade
title: Stripe subscription upgrade
tags: [billing, stripe, critical]
schedule: "*/5 * * * *"
regions: [us-east-1, eu-west-1]
shadow_prod: true
cache: default          # default | never
timeout: 120000         # ms
mender_mode: suggestive # off | suggestive | aggressive
clones: [stripe, email]
destructive: false
---
FieldDescription
idStable slug; used in schedules and Mender branch names
scheduleCron for production monitoring
regionsWhere scheduled runs execute
shadow_prodEnable shadow-prod diff
cachenever forces re-run on every PR
mender_modeOverride repo-level Mender mode
clonesClone kinds to spawn (stripe, twilio, email, auth, s3)

Executable test: colocated .spec.ts (hand-written or Cartographer-generated).

GitHub Action inputs

See GitHub App setup.

Environment variables (self-hosted)

API (apps/api)

VariableRequiredDescription
DATABASE_URLyesPostgres connection string
REDIS_URLyesRedis/Valkey for BullMQ + SSE
GH_APP_IDfor GitHub AppGitHub App ID
GH_APP_PRIVATE_KEYfor GitHub AppPEM private key (or GH_APP_PRIVATE_KEY_SECRET_ID)
GH_WEBHOOK_SECRETfor GitHub AppWebhook HMAC secret
GH_OAUTH_CLIENT_IDoptionalGitHub OAuth for install flow
GH_OAUTH_CLIENT_SECREToptionalGitHub OAuth secret
ARTIFACTS_S3_ENDPOINTyesS3-compatible artifact storage
ARTIFACTS_S3_BUCKETyesBucket name
MOLAR_GUARD_REGIONyesWorker region (us-east-1, etc.)
MOLAR_CLONES_ROOToptionalPath to molar-clones for local clone binaries
MOLAR_LLM_BASE_URLoptionalLiteLLM / gateway for Mender
BETTER_AUTH_SECRETyesSession signing
BETTER_AUTH_URLyesDashboard URL for auth callbacks

Dashboard (apps/dashboard)

VariableDescription
BETTER_AUTH_URLStandalone: http://localhost:3000; combined: https://app.molar.it
GUARD_API_URLFastify API base (http://localhost:4000)
PLUMBING_DASHBOARD_URLCombined mode redirect target
GUARD_DASHBOARD_TARGETlegacy | platform

Worker (apps/worker)

VariableDescription
MOLAR_GUARD_REGIONRegion this worker pool serves
WORKER_CONCURRENCY_PRPR queue concurrency (plan-tier capped)
WORKER_CONCURRENCY_SCHEDULESchedule queue concurrency
MENDER_MONTHLY_BUDGET_CENTSPer-org Mender spend cap override

Alert policy JSON

On scheduled_checks.alert_policy:

{
  "consecutiveFailures": 2,
  "failureRateThreshold": 0.5,
  "failureRateWindowSecs": 1800,
  "latencyP99ThresholdMs": 30000,
  "slackWebhookUrl": "https://hooks.slack.com/services/…",
  "pagerDutyRoutingKey": "…",
  "webhookUrl": "https://your-oncall.example.com/alerts"
}

Usage limits

Parallel workers, concurrent PRs, regions, and Mender budgets are enforced per organization. Limits are shown in Settings → Billing on app.molar.it — this documentation does not publish tier tables.

When a limit is exceeded, the API returns 429 Quota Exceeded with resource, limit, and used fields.

Docker Compose (local)

docker compose up -d postgres redis seaweedfs

Services: Postgres 17, Redis 7 (Valkey-compatible), SeaweedFS (S3-compatible artifacts).

Independence defaults

When no molar-guard.config.ts and no .molar.md:

  • Source adapter: playwright
  • Clones: disabled
  • Mender: off (hosted) or suggestive (if enabled in org settings)
  • Required check: advisory
  • MOLAR_DESTRUCTIVE_ALLOW never set in PR context when Clones enabled

Next