Configuration (YAML)

Yorker uses a declarative YAML file to define monitors, alerts, SLOs, and notification channels as code. The CLI validates every field through the same Zod schemas that the API uses, so defaults and constraints are applied identically.

To get started, create a yorker.config.yaml in your project root.

Root Fields

project: "my-app"

secrets:
  # ...

alertChannels:
  # ...

defaults:
  # ...

groups:
  # ...

monitors:
  # ...

slos:
  # ...

alertChannels

To configure notification channels, define them as named entries under alertChannels. Alerts and SLOs reference channels by name using @channel-name syntax.

Each channel must have a type field. The remaining fields depend on the type.

Slack

alertChannels:
  ops-slack:
    type: slack
    webhookUrl: "https://hooks.slack.com/services/T00/B00/xxxx"

Email

alertChannels:
  team-email:
    type: email
    addresses:
      - oncall@example.com
      - devops@example.com

Webhook

alertChannels:
  generic-webhook:
    type: webhook
    url: "{{secrets.OPSGENIE_WEBHOOK_URL}}"
    method: POST
    headers:
      Authorization: "GenieKey {{secrets.OPSGENIE_KEY}}"

Use the dedicated pagerduty and servicenow channel types below for those targets; the generic webhook type is for Opsgenie, custom integrations, or anything not covered by a first-class channel type.

PagerDuty

alertChannels:
  pagerduty-oncall:
    type: pagerduty
    routingKey: "{{secrets.PAGERDUTY_ROUTING_KEY}}"
    serviceRegion: us

ServiceNow

alertChannels:
  servicenow-prod:
    type: servicenow
    instanceUrl: "https://acme.service-now.com"
    username: "{{secrets.SNOW_USER}}"
    password: "{{secrets.SNOW_PASSWORD}}"
    assignmentGroup: "Platform Oncall"

defaults

To set values that apply to all monitors unless overridden, use the defaults block. Monitors and groups can override any default.

Frequency Format

The frequency value uses a duration string with a numeric value and a unit suffix.

The resolved value in seconds must be between 10 and 86400 (24 hours).

defaults:
  frequency: "5m"
  locations:
    - loc_us_east
    - loc_eu_central
    - loc_ap_northeast

defaults.http

To configure default values for all HTTP monitors, use the defaults.http block.

defaults:
  http:
    timeoutMs: 15000
    followRedirects: true
    maxRedirects: 3
    assertions:
      - type: status_code
        value: 200
      - type: response_time
        max: 5000

defaults.browser

To configure default values for all browser monitors, use the defaults.browser block.

defaults:
  browser:
    timeoutMs: 60000
    viewport:
      width: 1920
      height: 1080
    screenshotMode: every_step
    videoEnabled: false

defaults.alerts

To set alert rules that apply to all monitors by default, define them under defaults.alerts. Each alert requires at least one condition and at least one channel reference.

defaults:
  alerts:
    - name: "default-failure-alert"
      conditions:
        - type: consecutive_failures
          count: 3
      channels:
        - "@ops-slack"

See Groups and Monitors for how alert inheritance works.

groups

To organize monitors that share configuration, use groups. Groups can override defaults for frequency, locations, and alerts.

groups:
  - name: "US API endpoints"
    frequency: "1m"
    locations:
      - loc_us_east
      - loc_us_west
    alerts:
      - name: "api-down"
        conditions:
          - type: consecutive_failures
            count: 2
        channels:
          - "@ops-slack"
          - "@team-email"
    monitors:
      - name: "Users API"
        type: http
        url: "https://api.example.com/v1/users"
      - name: "Orders API"
        type: http
        url: "https://api.example.com/v1/orders"

monitors

HTTP Monitors

To define an HTTP monitor, set type: http and provide a url.

monitors:
  - name: "Homepage"
    type: http
    url: "https://www.example.com"
    method: GET
    timeoutMs: 10000
    assertions:
      - type: status_code
        value: 200
      - type: response_time
        max: 3000
      - type: body_contains
        value: "Welcome"

  - name: "Create Order API"
    type: http
    url: "https://api.example.com/v1/orders"
    method: POST
    headers:
      Content-Type: "application/json"
    body: '{"item": "test", "quantity": 1}'
    auth:
      type: bearer
      token: "{{secrets.API_TOKEN}}"
    assertions:
      - type: status_code
        value: 201

Redirects and credentials

When followRedirects is on, an HTTP monitor follows up to maxRedirects redirects and checks each hop before requesting it. What it sends on each hop depends on where the redirect points.

A redirect is cross-origin when the scheme, host or port differs from the URL that issued it. https://api.example.com to https://auth.example.com is cross-origin; https://api.example.com/v1 to https://api.example.com/v2 is not.

Removed on a cross-origin redirect:

• The Authorization header. This covers basic and bearer auth, and an Authorization header set under headers.
• The header configured for api-key auth, under whatever name you gave it.
• Cookie and Proxy-Authorization.

Not removed: any other header you set under headers, and the request body on a 301, 302, 307 or 308. Yorker cannot tell which of your custom headers are secret. If you send a credential in a custom header through headers and the target can redirect to another host, that header goes with it. Put the credential in auth with type: api-key instead so it is treated as one.

If a monitor needs its credential to reach the final host, point the monitor at that host directly, or turn followRedirects off and assert on the redirect response itself.

yorker test is stricter

A local run with yorker test follows the same rules, with two additions on a cross-origin redirect. They exist because a local or CI run has your secrets in its environment:

yorker test can do the first because it knows which values came from {{secrets.NAME}} placeholders. A deployed monitor's headers are plain strings by the time a runner sees them, so a hosted run cannot make that distinction.

So passing yorker test does not mean a deployed monitor withholds the same things: on a cross-origin redirect a hosted run still sends that custom header and that body. If either carries a credential, move it into auth, or point the monitor at the final host so no redirect is involved.

Agent personas

For a walkthrough, see Monitor AI Agent Access.

To see how an HTTP monitor's URL responds to AI crawlers and agents, add an agentPersonas block. After the normal request succeeds, Yorker repeats it once per persona with that crawler's User-Agent and compares each response with the normal one.

Available personas:

A persona's response is reported as different when:

• Blocked: the normal request got a 2xx and the persona did not.
• Bot challenge: the edge answered the persona with a challenge page.
• Assertion failed: a status_code, body_contains, body_matches, body_json_path or header_value assertion that passed for the normal request failed for the persona.
• Request failed: the persona request errored or timed out. Persona requests time out after 15 seconds or the monitor's timeoutMs, whichever is shorter.

monitors:
  - name: "Pricing page"
    type: http
    url: "https://www.example.com/pricing"
    frequency: "5m"
    assertions:
      - type: status_code
        value: 200
      - type: body_contains
        value: "Plans"
    agentPersonas:
      personas:
        - claude-user
        - chatgpt-user
        - perplexity-user
      every: 6
      failOnDivergence: true

Things to know:

• Each persona request counts as one additional HTTP run, per location. every is the cost control: the example above adds 3 runs to 1 in 6 executions.
• Personas run only when the normal request succeeded. If the URL is down for everyone, the run reports that and skips the personas.
• Sampling is counted per location and restarts when the runner restarts or the block changes, so the first run after either includes personas.
• Results are emitted to your OTLP backend as synthetics.agent.persona.checked events. See OpenTelemetry > Agent persona signals.
• A persona request carries the crawler's user agent, not its verified identity. It tests rules that match on the user agent string. A CDN that verifies bots by signature or IP range can answer the real crawler differently from a persona request.

Agent readiness

For a walkthrough, see Check Agent Readiness.

To monitor the files and behaviours AI agents look for on the monitor's site, add an agentReadiness block to an HTTP monitor.

Probe IDs: robots_txt, robots_consistency, sitemap, llms_txt, markdown_negotiation, markdown_sibling, markdown_parity, mcp_server_card, api_catalog, oauth_discovery, agent_skills. What each one checks is in the guide.

monitors:
  - name: "Docs home"
    type: http
    url: "https://docs.example.com/"
    frequency: "5m"
    agentReadiness:
      every: 12
      require:
        - robots_txt
        - llms_txt

Things to know:

• A readiness run counts as one additional HTTP run per location and makes up to 19 probe requests, all to the monitor's own site.
• Probes run only when the normal request succeeded, and at most once every 4 minutes per location whatever every and the monitor's frequency are.
• robots_consistency needs agentPersonas on the same monitor. To require it, agentReadiness.every must be a multiple of agentPersonas.every so personas run on every readiness run; the config is rejected otherwise. Requiring markdown_negotiation is rejected on a non-GET monitor.
• Results are emitted to your OTLP backend as synthetics.agent.readiness.checked events. See OpenTelemetry > Agent readiness signals.

Browser Monitors

Browser monitors defined in yorker.config.yaml are always scripted: point script at a Playwright TypeScript file and Yorker runs it on each check. URL-mode browser monitors (which navigate a single URL without a script) are currently created through the Web UI or the REST API only; they cannot be deployed via YAML yet.

monitors:
  - name: "Login Flow"
    type: browser
    script: "./monitors/login.ts"
    viewport:
      width: 1920
      height: 1080
    screenshotMode: every_step
    timeoutMs: 60000
    frequency: "10m"
    locations:
      - loc_us_east
      - loc_eu_west

MCP Monitors

To define an MCP monitor (for checking Model Context Protocol servers over Streamable HTTP), set type: mcp and provide an endpoint.

testCalls entry fields:

monitors:
  - name: "Docs MCP"
    type: mcp
    endpoint: "https://mcp.example.com/mcp"
    frequency: "5m"
    auth:
      type: bearer
      token: "{{secrets.MCP_TOKEN}}"
    expectedTools:
      - search_docs
      - fetch_page
    testCalls:
      - toolName: search_docs
        arguments:
          query: "pricing"
        expectedOutputContains: "Plans"
    detectSchemaDrift: true
    rejectUnauthenticated: true
    locations:
      - loc_us_east

auth

To authenticate HTTP requests, add an auth block to an HTTP monitor. Three authentication types are supported.

Basic Auth

auth:
  type: basic
  username: "{{secrets.BASIC_USER}}"
  password: "{{secrets.BASIC_PASS}}"

Bearer Token

auth:
  type: bearer
  token: "{{secrets.API_TOKEN}}"

API Key

auth:
  type: api-key
  header: "X-Custom-Key"
  value: "{{secrets.CUSTOM_API_KEY}}"

slos

To define Service Level Objectives, add entries to the slos array. Each SLO is linked to a monitor by name.

Target Format

The target can be specified as a percentage string or a number:

• "99.9%" -- parsed as 9990 basis points
• 99.9 -- treated as a percentage, parsed as 9990 basis points
• Valid range: 1-9999 basis points (0.01% to 99.99%)

Window Format

The window can be a duration string or a number:

• "7d", "14d", "30d" -- string format
• 7, 14, 30 -- numeric format (days)
• Only these three values are allowed.

slos:
  - name: "Homepage Availability"
    monitor: "Homepage"
    target: "99.9%"
    window: "30d"
    burnRateAlerts: true
    channels:
      - "@ops-slack"

  - name: "API Uptime"
    monitor: "Users API"
    target: 99.95
    window: 7d
    channels:
      - "@ops-slack"
      - "@team-email"

maintenanceWindows

To silence alerts during scheduled work, add entries to maintenanceWindows. A window can pause checks entirely or let them continue running while suppressing notifications.

Single-file format only. maintenanceWindows is supported when you deploy from a single yorker.config.yaml. The directory format (yorker init --format directory) does not currently support a per-resource maintenance-window YAML file. If you need maintenance windows in code, stay on the single-file format. Also note that yorker pull does not export maintenance windows and overwrites the YAML file; see the CLI reference for yorker pull for the round-trip caveat.

maintenanceWindows:
  - name: "Weekly DB maintenance"
    mode: pause
    checks: all
    startsAt: "2026-04-12T02:00:00Z"
    endsAt:   "2026-04-12T03:00:00Z"
    recurring: true
    recurrenceRule: "FREQ=WEEKLY;BYDAY=SU"

  - name: "Black Friday cut-over"
    mode: continue
    checks:
      - "Homepage"
      - "Checkout Flow"
    startsAt: "2026-11-27T05:00:00Z"
    endsAt:   "2026-11-27T06:00:00Z"

alerts (alert rule definitions)

Alert rules live on monitors, in groups, or in defaults. Each rule has a list of conditions (ANDed together) and channels (channel references).

Condition types

All SSL conditions (including ssl_expiry), mcp_schema_drift, and baseline_anomaly support an optional severity field: critical, warning, or info. mcp_schema_drift and baseline_anomaly default to warning from the schema; SSL conditions fall back to critical via the evaluator when unset.

See Set Up Alerts for worked examples.

Labels

Labels attach metadata to checks. They serve two purposes:

1. Filtering and grouping in the dashboard.
2. OTel resource attributes: Yorker emits every label as a yorker.label.* resource attribute on metrics and traces, so you can slice telemetry by label in your observability backend.

Labels follow this format: [a-zA-Z0-9][a-zA-Z0-9_.:-]*, max 128 characters.

monitors:
  - name: "Payments API"
    type: http
    url: "https://api.example.com/payments"
    labels:
      - env:production
      - service:payments
      - critical

Secret Interpolation

To inject secrets and environment variables into your config, use placeholder syntax. Placeholders are resolved at deploy time from environment variables.

The secrets allowlist

Every name used in a placeholder must be listed in the top-level secrets array. This applies to all three placeholder forms and to browser script files.

project: "my-app"

secrets:
  - API_TOKEN
  - BASE_URL

monitors:
  - name: "Private API"
    type: http
    url: "{{env.BASE_URL}}/health"
    auth:
      type: bearer
      token: "{{secrets.API_TOKEN}}"

List the bare name. API_TOKEN covers {{secrets.API_TOKEN}} whether the value comes from YORKER_SECRET_API_TOKEN or API_TOKEN.

The list is a safety boundary, not bookkeeping. yorker deploy usually runs in CI with access to your pipeline's environment, so without an allowlist a config change could read any variable there and send it to an endpoint of the author's choosing. With it, a new secret reference always shows up as a visible, reviewable line in the diff.

A placeholder whose name is not listed fails yorker validate and yorker deploy:

Secret placeholder(s) reference env vars not listed in top-level `secrets:` allowlist: API_TOKEN.

{{secrets.NAME}}

Reads YORKER_SECRET_NAME first, then falls back to NAME from the environment.

auth:
  type: bearer
  token: "{{secrets.API_TOKEN}}"
# Resolves: $YORKER_SECRET_API_TOKEN ?? $API_TOKEN

{{env.NAME}}

Reads the environment variable NAME directly.

url: "{{env.BASE_URL}}/health"
# Resolves: $BASE_URL

${NAME} (Legacy)

Reads the environment variable NAME directly. This is the legacy syntax, supported only in YAML config values. It is not applied inside browser script files because ${...} conflicts with JavaScript template literals.

url: "${BASE_URL}/health"
# Resolves: $BASE_URL

Script Interpolation

Browser script files (.ts files referenced by script:) support {{secrets.NAME}} and {{env.NAME}} interpolation. The legacy ${NAME} syntax is intentionally excluded from scripts to avoid conflicts with JavaScript template literals.

Redaction in CLI output

The CLI knows which values came from your secrets: list, so it replaces them with ***REDACTED*** in the warnings and validation errors it prints while loading a config, in yorker test results, and in the plan that yorker deploy and yorker diff print or return as JSON (see Secrets in the plan). A secret interpolated into a monitor name or a script path will not appear in a terminal or CI log through one of those messages. Values shorter than four characters are not redacted: the list also covers plain {{env.NAME}} settings such as a port or a region, and replacing those everywhere would garble ordinary output. Do not rely on redaction for a secret that short.

Separately from secrets, all CLI output has terminal escape sequences and CI log commands (such as GitHub Actions' ::error::) neutralised, so a monitor name or a script path in a config you did not write cannot take over your terminal or a CI job. See Output safety.

This covers the CLI's own messages. It does not stop a secret from being stored where you put it: a monitor named with a secret is deployed with that name.

Unresolved Placeholders

If a placeholder cannot be resolved, a warning is printed and the raw placeholder text is preserved. After interpolation, the CLI checks for any remaining unresolved placeholders and fails with an error listing each one and its location in the config.

Inheritance Rules

Configuration values cascade through three levels: defaults, group, and monitor. The most specific value wins.

monitor > group > defaults

Available Locations

To see all available locations and their IDs, call GET /api/locations.

Full Example

project: "acme-production"

alertChannels:
  ops-slack:
    type: slack
    webhookUrl: "{{secrets.SLACK_WEBHOOK_URL}}"
  oncall-email:
    type: email
    addresses:
      - oncall@acme.com
  pagerduty-oncall:
    type: pagerduty
    routingKey: "{{secrets.PAGERDUTY_ROUTING_KEY}}"

defaults:
  frequency: "5m"
  locations:
    - loc_us_east
    - loc_eu_central
  http:
    timeoutMs: 15000
    followRedirects: true
    assertions:
      - type: status_code
        value: 200
  browser:
    timeoutMs: 60000
    screenshotMode: every_step
  alerts:
    - name: "default-alert"
      conditions:
        - type: consecutive_failures
          count: 3
      channels:
        - "@ops-slack"

groups:
  - name: "Critical APIs"
    frequency: "1m"
    locations:
      - loc_us_east
      - loc_us_west
      - loc_eu_west
    alerts:
      - name: "critical-api-alert"
        conditions:
          - type: consecutive_failures
            count: 2
          - type: multi_location_failure
            minLocations: 2
            windowSeconds: 300
        channels:
          - "@ops-slack"
          - "@pagerduty-oncall"
    monitors:
      - name: "Auth API"
        type: http
        url: "https://api.acme.com/v1/auth/health"
      - name: "Payments API"
        type: http
        url: "https://api.acme.com/v1/payments/health"
        assertions:
          - type: status_code
            value: 200
          - type: response_time
            max: 1000

monitors:
  - name: "Homepage"
    type: http
    url: "https://www.acme.com"

  - name: "Checkout Flow"
    type: browser
    script: "./monitors/checkout.ts"
    frequency: "10m"
    locations:
      - loc_us_east
    alerts:
      - name: "checkout-alert"
        conditions:
          - type: consecutive_failures
            count: 1
        channels:
          - "@ops-slack"
          - "@oncall-email"

slos:
  - name: "Auth API SLO"
    monitor: "Auth API"
    target: "99.95%"
    window: "30d"
    channels:
      - "@ops-slack"

  - name: "Homepage SLO"
    monitor: "Homepage"
    target: "99.9%"
    window: "7d"
    burnRateAlerts: true
    channels:
      - "@ops-slack"