Browser checks

---

title: Browser checks description: Reviewed browser journeys from two customer-hosted probes, with bounded evidence and execution allowances.

Metrics → Browser checks runs a reviewed journey through two independently authenticated customer-hosted Chromium probes. The control plane schedules work and records technical outcomes; it never fetches the target website.

Connect two probes

In the selected environment, open Probes and budget and register two probes. Give each a name and a declared region. A recent passkey and metrics.write are required. Copy each one-time credential into its deployment's secret manager. Build the supplied source package on two isolated deployments; it is not a hosted service or an already-published npm release.

pnpm install --frozen-lockfile
pnpm --filter @saaspro/shared build
pnpm --filter @saaspro/synthetic-probe build
pnpm --filter @saaspro/synthetic-probe exec playwright install --with-deps chromium --only-shell

Supply these variables through the deployment's secret manager. Never paste real credentials into shell history or source control.

SPM_PROBE_HOST=https://your-control-plane.com
SPM_PROBE_TOKEN=<one-time constrained probe credential>
SPM_PROBE_DEPLOYMENT=eu-west-production-a

node packages/synthetic-probe/dist/cli.js

Run the second agent with its own credential and a different stable deployment identifier. Region and deployment labels must be technical identifiers without personal data. Setup receipts show the last poll, runner version, deployment identifier and credential revision. They do not attest physical location. Two local processes establish distinct identities, not geographic independence.

The agent polls every 15 seconds, executes one journey at a time, and retries the identical terminal result at most twice. Use a process supervisor to restart after a control-plane failure. --once performs one poll and any leased execution, then exits. Control URLs require HTTPS; HTTP loopback is permitted for local verification. Control-plane redirects are refused.

Review the journey and owner

Choose exactly two probes and a current Metrics member as owner. Configure two to eight fixed steps: the first navigates; later steps may navigate again, assert an exact visible text string or assert that a document title contains a static string. At least one assertion is required. Navigation checks a reviewed 2xx HTTP status.

Review up to five exact HTTPS origins, including required static assets. Use final public URLs without query strings, fragments, credentials or custom ports. The broker requires public IPv4 DNS answers and refuses redirects and compressed responses. Targets must honor Accept-Encoding: identity. Do not put personal data into labels, expected strings, names or URLs.

There are no click, fill, submit, login, cookie, target-credential or custom-JavaScript steps. An HTTP GET can still cause application side effects: operators must review every route and dependency for read-only use. Website JavaScript executes inside Chromium; operator-supplied scripts are never accepted.

Select owner delivery channels explicitly and confirm that the assigned owner receives them. Selecting an owner alone does not send email. Existing channel secrets remain in the vault. Probe credentials are high-entropy, hash-only capabilities restricted to polling and reporting that one probe's work. Public ingest keys, secret ingest keys and Management tokens are refused at probe endpoints.

Schedule and execution allowance

Start in manual mode and inspect the first two-probe result before scheduling. Scheduled rounds use elapsed intervals from five minutes to 24 hours; timezone and daylight-saving changes do not shift them. Missed intervals are not backfilled. Each monitor has at most one pending round. A round expires after three minutes; a leased execution has its reviewed duration plus 15 seconds to report.

Each probe execution is limited to 5–60 seconds, 100 broker requests, 2 MiB per uncompressed response, 10 MiB total response bytes and an eight-second request deadline. Both full probe-duration allowances are reserved before a round starts, including manual, missed and cancelled work. Reservations are not refunded; identical result retries consume no extra reservation.

Each environment defaults to 3,600 seconds per UTC day, configurable from 120 to 86,400. A separate hard ceiling covers 86,400 seconds across all environments in one application. Allowances reset at 00:00 UTC. Each environment is capped at 10 probes, 20 check definitions and 20,000 retained rounds. A full allowance or row limit dispatches no work. Probe machines and bandwidth may incur infrastructure costs; the platform neither provisions them nor initiates provider charges.

Evidence and incidents

Results retain probe identity, declared region, deployment identifier, immutable check revision, duration, request/byte counts and ordered technical step outcomes. Failure evidence identifies the first failed step, its HTTP status when available and elapsed time. Page HTML, DOM, actual text, screenshots, console output, exception bodies, cookies and response headers are not retained.

A confirmed failed journey opens one incident. Missing or unknown results never close it. Recovery requires a newer round where both distinct probe and deployment identities pass every step. Policy, runner and budget errors and expired leases remain incomplete. Two credentials reporting the same deployment identifier cannot establish a two-probe pass. These customer-reported outcomes are not a complete uptime census or independently attested geography.

Owner delivery uses the existing dispatcher and one outbox entry per incident, phase and channel. Current monitor revision, enabled state and creator/owner authority are checked before a delivery claim. A worker crash after claiming can leave delivery uncertain; such sends are not blindly retried. Manual incident closure is labeled as unconfirmed recovery.

Changes, pauses and credential rotation cancel pending rounds. A probe already executing a lease may continue until its bounded deadline, but old revisions and expired leases cannot submit fresh evidence. Identical accepted retries stay idempotent while current revision and authority still apply. Revoked creator Metrics authority or owner membership stops new execution and notification claims until an authorized operator reviews the configuration.

Network isolation

Use dedicated non-root deployments without application/cloud credentials, unrelated mounted secrets, private-network access or shared browser profiles. Keep Chromium's sandbox enabled, supply the appropriate seccomp profile, apply process/memory limits and enforce host/container egress policy. Browser routing is not an operating-system security boundary. The official Playwright container guidance explains sandbox requirements; its development image is not a blanket recommendation for untrusted websites.

Each journey uses a fresh offline context and a refusing browser proxy. All permitted requests are fulfilled by the Node HTTPS broker, which validates every public IPv4 answer and pins the connection address while retaining TLS hostname verification. The broker sends only fixed User-Agent, Accept and Accept-Encoding headers; browser cookies, authorization, client headers and probe control credentials are never forwarded. Set-Cookie and unapproved response headers are discarded. Chromium receives only a minimal environment, without the probe token.

Service workers, WebSockets, downloads and additional pages are blocked. The constrained offline context can behave differently from an unrestricted browser, especially for applications that inspect navigator.onLine or require authenticated third-party requests. Compressed content is rejected, so response limits also bound decompressed bytes. Redirects are refused instead of followed. See official network routing and service-worker restrictions for routing capabilities and their limitations.

Private reads and retention

Console and Management reads require the current tenant/environment, enabled Metrics and metrics.read; Management also requires read scope. Owner name/email labels require people.pii.read. Private reads never return probe tokens or hashes.

GET /api/v1/apps/{app}/metrics/browser-checks?env=production
GET /api/v1/apps/{app}/metrics/browser-checks?env=production&id={checkId}
Authorization: Bearer <read-scoped Management token>

These are private read tokens, never probe credentials or client-side examples. Evidence expires after the shorter of seven days and application retention. Reads hide it immediately; fair worker batches purge it, including while Metrics is disabled. Check deletion immediately hides the definition/results and cancels work, then cascades retained evidence. Application/environment deletion cascades scoped tables. Audit events remain separate and append-only. Browser checks do not currently feed SLO aggregation.