---
title: 'Configuration (YAML)'
description: 'Complete reference for yorker.config.yaml: every field, type, default, and constraint.'
section: 'Reference'
canonical_url: 'https://yorkermonitoring.com/docs/reference/configuration'
---

# 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

| Field | Type | Required | Description |
|---|---|---|---|
| `project` | `string` | Yes | Project name. Displayed in deploy plan output. |
| `secrets` | `string[]` | No | Names that `{{secrets.NAME}}`, `{{env.NAME}}`, and `${NAME}` placeholders are allowed to read. Required as soon as the config uses any placeholder. See [Secret Interpolation](#secret-interpolation). |
| `alertChannels` | `object` | No | Named notification channel definitions (key-value map). |
| `defaults` | `object` | No | Default values inherited by all monitors. |
| `groups` | `array` | No | Groups of monitors that share frequency, locations, and alerts. |
| `monitors` | `array` | No | Top-level monitor definitions (outside any group). |
| `slos` | `array` | No | Service Level Objective definitions. |
| `maintenanceWindows` | `array` | No | Scheduled silences / pauses. See [`maintenanceWindows`](#maintenancewindows). |

```yaml
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

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `"slack"` | Yes | Channel type. |
| `webhookUrl` | `string` (URL) | Yes | Slack incoming webhook URL. |

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

### Email

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `"email"` | Yes | Channel type. |
| `addresses` | `string[]` | Yes | At least one valid email address. |

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

### Webhook

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `type` | `"webhook"` | Yes | -- | Channel type. |
| `url` | `string` (URL) | Yes | -- | Webhook endpoint URL. |
| `method` | `"POST"` \| `"PUT"` | No | `"POST"` | HTTP method. |
| `headers` | `object` | No | -- | Custom headers (key-value string pairs). |

```yaml
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

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `type` | `"pagerduty"` | Yes | -- | Channel type. |
| `routingKey` | `string` (1-64 chars) | Yes | -- | PagerDuty Events API v2 integration key. |
| `serviceRegion` | `"us"` \| `"eu"` | No | `"us"` | `us` for events.pagerduty.com, `eu` for events.eu.pagerduty.com. |

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

### ServiceNow

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `type` | `"servicenow"` | Yes | -- | Channel type. |
| `instanceUrl` | `string` (URL) | Yes | -- | Full ServiceNow instance URL (e.g. `https://acme.service-now.com`). |
| `username` | `string` (1-128 chars) | Yes | -- | ServiceNow account with permission to create incidents. |
| `password` | `string` (1-512 chars) | Yes | -- | ServiceNow account password or OAuth token. Stored as a secret at rest. |
| `assignmentGroup` | `string` (max 128) | No | -- | Optional group name (maps to `sys_user_group.name`) for new incidents. |

```yaml
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.

| Field | Type | Default | Description |
|---|---|---|---|
| `frequency` | `string` | `"5m"` (300s) | Check interval. Format: `Ns`, `Nm`, or `Nh`. Range: 10s-86400s. |
| `locations` | `string[]` | `["loc_us_east", "loc_eu_central"]` | Location IDs to run from. Must be non-empty. |
| `http` | `object` | -- | Default HTTP check configuration. |
| `browser` | `object` | -- | Default browser check configuration. |
| `alerts` | `array` | -- | Default alert rules applied to all monitors. |

### Frequency Format

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

| Unit | Suffix | Example | Seconds |
|---|---|---|---|
| Seconds | `s` | `30s` | 30 |
| Minutes | `m` | `5m` | 300 |
| Hours | `h` | `1h` | 3600 |

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

```yaml
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.

| Field | Type | Default | Description |
|---|---|---|---|
| `timeoutMs` | `number` | `30000` | Request timeout in milliseconds. |
| `followRedirects` | `boolean` | `true` | Whether to follow HTTP redirects. |
| `maxRedirects` | `number` | `5` | Maximum number of redirects to follow. |
| `assertions` | `array` | `[]` | Default assertion rules. See [Assertions](/docs/reference/assertions). |

```yaml
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.

| Field | Type | Default | Constraints | Description |
|---|---|---|---|---|
| `timeoutMs` | `number` | `30000` | 5000-120000 | Script execution timeout in milliseconds. |
| `viewport` | `object` | `{ width: 1280, height: 720 }` | -- | Browser viewport dimensions. |
| `viewport.width` | `number` | `1280` | -- | Viewport width in pixels. |
| `viewport.height` | `number` | `720` | -- | Viewport height in pixels. |
| `screenshotMode` | `string` | `"every_step"` | `every_step` \| `failure_only` \| `disabled` | When to capture screenshots. |
| `videoEnabled` | `boolean` | `false` | -- | Whether to record video. |
| `device` | `string` | -- | -- | Playwright device name for emulation (e.g., `"iPhone 14"`). |

```yaml
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.

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

See [Groups and Monitors](#groups) for how alert inheritance works.

---

## `groups`

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

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Group name (for display in deploy plan). |
| `frequency` | `string` | No | Overrides `defaults.frequency` for all monitors in this group. |
| `locations` | `string[]` | No | Overrides `defaults.locations` for all monitors in this group. |
| `alerts` | `array` | No | Overrides `defaults.alerts` for all monitors in this group. |
| `monitors` | `array` | Yes | Monitor definitions within this group. |

```yaml
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`.

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `name` | `string` | Yes | - | 1-255 characters | Unique monitor name. |
| `type` | `"http"` | Yes | - | - | Monitor type. |
| `url` | `string` | Yes | - | Valid URL | Target URL to check. |
| `method` | `string` | No | `"GET"` | `GET` \| `POST` \| `PUT` \| `DELETE` \| `PATCH` \| `HEAD` | HTTP method. |
| `headers` | `object` | No | - | - | Custom request headers (key-value string pairs). |
| `body` | `string` | No | - | - | Request body. Sent with every method, including `GET` and `HEAD`, so leave it unset when the target does not expect one. |
| `auth` | `object` | No | - | - | Authentication configuration. See [Auth](#auth). |
| `followRedirects` | `boolean` | No | `true` | - | Whether to follow redirects. Overrides `defaults.http`. |
| `maxRedirects` | `number` | No | `5` | - | Maximum redirects. Overrides `defaults.http`. |
| `timeoutMs` | `number` | No | `30000` | - | Request timeout in ms. Overrides `defaults.http`. |
| `assertions` | `array` | No | `[]` | - | Assertion rules. **Replaces** defaults (not merged). See [Assertions](/docs/reference/assertions). |
| `agentPersonas` | `object` | No | - | - | Repeat the request as AI crawlers and compare the responses. See [Agent personas](#agent-personas). |
| `agentReadiness` | `object` | No | - | - | Probe the site for robots.txt, llms.txt, Markdown and discovery files. See [Agent readiness](#agent-readiness). |
| `frequency` | `string` | No | From defaults/group | 10s-86400s | Check interval. |
| `locations` | `string[]` | No | From defaults/group | Non-empty | Location IDs. |
| `alerts` | `array` | No | From defaults/group | - | Alert rules. |
| `labels` | `string[]` | No | - | See [Labels](#labels) | Labels attached to this check. Emitted as OTel resource attributes. |
| `enabled` | `boolean` | No | `true` | - | Whether this monitor is active. |

```yaml
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.

| On a redirect that is | What happens |
|---|---|
| Same origin | Everything is sent again unchanged. |
| Cross-origin | Credentials are removed (see below). Other headers and the request body are still sent. |
| From `https` to `http` | The run fails. Yorker does not follow a redirect that downgrades to cleartext. |
| A `303 See Other` | The request becomes a `GET` with no body, and the headers that describe a body (`Content-Type`, `Content-Length`, `Content-Encoding`, `Transfer-Encoding`) are dropped. |

Removed on a cross-origin redirect:

- The `Authorization` header. This covers `basic` and `bearer` [auth](#auth), and an `Authorization` header set under `headers`.
- The header configured for `api-key` [auth](#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`](/docs/reference/cli#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:

| | Hosted and private-location runs | `yorker test` |
|---|---|---|
| A custom header whose value contains a secret from your `secrets:` list | Sent | Removed, whatever the header is called |
| The request body on a `301`, `302`, `307` or `308` | Sent | Not sent. The run fails and says why |

`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](/docs/guides/monitor-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.

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `personas` | `string[]` | Yes | - | At least one, no duplicates | Personas to run as. |
| `every` | `number` | No | `1` | 1-1000 | Run personas on 1 in this many runs. `1` runs them every time. |
| `failOnDivergence` | `boolean` | No | `false` | - | Fail the run when a persona's response differs, so alert rules and SLOs see it. When `false` the difference is recorded on the run only. |
| `enabled` | `boolean` | No | `true` | - | Set to `false` to pause persona runs and keep the settings. |

Available personas:

| Persona | Operator | Used for |
|---|---|---|
| `claudebot` | Anthropic | Training crawler |
| `claude-user` | Anthropic | Fetches on behalf of a user |
| `claude-searchbot` | Anthropic | Search index |
| `gptbot` | OpenAI | Training crawler |
| `chatgpt-user` | OpenAI | Fetches on behalf of a user |
| `oai-searchbot` | OpenAI | Search index |
| `perplexitybot` | Perplexity | Search index |
| `perplexity-user` | Perplexity | Fetches on behalf of a user |

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.

```yaml
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](/docs/concepts/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](/docs/guides/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.

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `every` | `number` | No | `12` | 1-1000 | Run the probes on 1 in this many runs. `1` runs them every time. |
| `require` | `string[]` | No | `[]` | Probe IDs, no duplicates | Probes that must pass. One that fails, is not served, or could not be checked fails the run. |
| `enabled` | `boolean` | No | `true` | - | Set to `false` to pause the probes and keep the settings. |

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](/docs/guides/agent-readiness#what-gets-checked).

```yaml
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](/docs/concepts/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.

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `name` | `string` | Yes | - | 1-255 characters | Unique monitor name. |
| `type` | `"browser"` | Yes | - | - | Monitor type. |
| `script` | `string` | Yes | - | - | Path to Playwright script file (relative to config file). |
| `steps` | `array` | No | - | - | Optional named steps. Each entry has `name` (must match a `// @step: Name` marker in the script), optional `timeoutMs`, and optional `assertions`. |
| `viewport` | `object` | No | `{ width: 1280, height: 720 }` | - | Browser viewport dimensions. Overrides `defaults.browser`. |
| `device` | `string` | No | - | - | Playwright device name for emulation. Overrides `defaults.browser`. |
| `screenshotMode` | `string` | No | `"every_step"` | `every_step` \| `failure_only` \| `disabled` | Screenshot capture mode. Overrides `defaults.browser`. |
| `videoEnabled` | `boolean` | No | `false` | - | Whether to record video. Overrides `defaults.browser`. |
| `agentPersona` | `string` | No | - | `claudebot` \| `claude-user` \| `claude-searchbot` \| `gptbot` \| `chatgpt-user` \| `oai-searchbot` \| `perplexitybot` \| `perplexity-user` | Run the monitor presenting this AI agent's user agent. See [Browser monitors: run as an agent](/docs/guides/monitor-agent-access#browser-monitors-run-as-an-agent). |
| `agentView` | `boolean` | No | `false` | - | Measure the page the run ends on as a non-human client meets it. See [Browser monitors: agent view](/docs/guides/monitor-agent-access#browser-monitors-agent-view). |
| `timeoutMs` | `number` | No | `30000` | 5000-120000 | Script timeout in ms. Overrides `defaults.browser`. |
| `frequency` | `string` | No | From defaults/group | 10s-86400s | Check interval. |
| `locations` | `string[]` | No | From defaults/group | Non-empty | Location IDs. |
| `alerts` | `array` | No | From defaults/group | - | Alert rules. |
| `labels` | `string[]` | No | - | See [Labels](#labels) | Labels attached to this check. |
| `enabled` | `boolean` | No | `true` | - | Whether this monitor is active. |

```yaml
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`.

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `name` | `string` | Yes | - | 1-255 characters | Unique monitor name. |
| `type` | `"mcp"` | Yes | - | - | Monitor type. |
| `endpoint` | `string` | Yes | - | Valid URL | Streamable HTTP endpoint of the MCP server. |
| `timeoutMs` | `number` | No | `30000` | 5000-120000 | Request timeout in ms. |
| `auth` | `object` | No | - | - | Same shape as HTTP [`auth`](#auth). |
| `expectedTools` | `string[]` | No | - | - | Tool names that must be present. Missing tools fail the check. |
| `testCalls` | `array` | No | - | - | Tool invocations to exercise. See below. |
| `detectSchemaDrift` | `boolean` | No | `true` | - | Track changes between runs: tools added or removed, and changes to each tool's input schema, description or annotations, plus the server's reported name, version, protocol version and capabilities. Also flags annotation hints that became less safe (for example `readOnlyHint` going from `true` to `false`). |
| `rejectUnauthenticated` | `boolean` | No | `false` | Requires `auth` | Each run also sends an `initialize` request with no credentials and fails unless the server answers HTTP 401 or 403. |
| `frequency` | `string` | No | From defaults/group | 10s-86400s | Check interval. |
| `locations` | `string[]` | No | From defaults/group | Non-empty | Location IDs. |
| `alerts` | `array` | No | From defaults/group | - | Alert rules. |
| `labels` | `string[]` | No | - | See [Labels](#labels) | Labels attached to this check. |
| `enabled` | `boolean` | No | `true` | - | Whether this monitor is active. |

`testCalls` entry fields:

| Field | Type | Required | Description |
|---|---|---|---|
| `toolName` | `string` | Yes | Name of the tool to invoke. |
| `arguments` | `object` | No | Plain JSON key-value map of arguments passed to the tool. |
| `expectedOutputContains` | `string` | No | Substring that must appear in the tool's result. |

```yaml
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

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `"basic"` | Yes | Auth type. |
| `username` | `string` | Yes | Username. |
| `password` | `string` | Yes | Password. |

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

### Bearer Token

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `"bearer"` | Yes | Auth type. |
| `token` | `string` | Yes | Bearer token value. |

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

### API Key

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `type` | `"api-key"` | Yes | -- | Auth type. |
| `header` | `string` | No | `"X-API-Key"` | Header name to send the key in. |
| `value` | `string` | Yes | -- | API key value. |

```yaml
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.

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `name` | `string` | Yes | -- | 1-255 characters | Unique SLO name. |
| `monitor` | `string` | Yes | -- | Must match a monitor `name` | Reference to the monitor this SLO tracks. |
| `target` | `string` \| `number` | Yes | -- | Resolves to 1-9999 basis points | Availability target. `"99.9%"` or `99.9`. |
| `window` | `string` \| `number` | Yes | -- | `"7d"` \| `"14d"` \| `"30d"` or `7` \| `14` \| `30` | Rolling window. |
| `burnRateAlerts` | `boolean` | No | `true` | -- | Enable burn rate alerting. |
| `channels` | `array` | No | `[]` | -- | Channel references for burn rate alerts (e.g., `["@ops-slack"]`). |
| `enabled` | `boolean` | No | `true` | -- | Whether this SLO is active. |

### 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.

```yaml
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`](/docs/reference/cli#yorker-pull) for the round-trip caveat.

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `name` | `string` | Yes | - | Unique window name. |
| `mode` | `string` | No | `pause` | `pause` (stop running checks) or `continue` (run but silence alerts). |
| `checks` | `"all"` \| `string[]` | Yes | - | `"all"` or a list of monitor names covered by the window. |
| `startsAt` | `string` | Yes | - | ISO-8601 start timestamp. |
| `endsAt` | `string` | Yes | - | ISO-8601 end timestamp. Must be after `startsAt`. |
| `recurring` | `boolean` | No | `false` | Enable recurrence. |
| `recurrenceRule` | `string` | No | - | RRULE string (e.g., `FREQ=WEEKLY;BYDAY=SU`). Required when `recurring: true`. |

```yaml
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).

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `name` | `string` | No | - | Optional rule name. |
| `enabled` | `boolean` | No | `true` | Whether the rule is active. |
| `conditions` | `array` | Yes | - | At least one condition. |
| `channels` | `string[]` | Yes | - | Channel references using `@channel-name` syntax. |

### Condition types

| Type | Fields | Description |
|---|---|---|
| `consecutive_failures` | `count` (default `2`, min `1`) | Trigger after N failures in a row. |
| `response_time_threshold` | `maxMs` (required) | Trigger when response time exceeds threshold. |
| `multi_location_failure` | `minLocations` (default `2`, min `2`), `windowSeconds` (default `300`) | Trigger when failures correlate across multiple locations. |
| `ssl_expiry` | `daysBeforeExpiry` (default `14`, min `1`), `severity` (optional) | Trigger when SSL cert approaches expiration. |
| `ssl_certificate_changed` | `severity` (optional) | Trigger when the leaf certificate fingerprint changes between runs. |
| `ssl_self_signed` | `severity` (optional) | Trigger when a self-signed or untrusted certificate is detected. |
| `ssl_protocol_deprecated` | `minProtocol` (default `TLSv1.2`; allowed `TLSv1.2`, `TLSv1.3`), `severity` (optional) | Trigger when the handshake negotiates a protocol older than `minProtocol`. |
| `burn_rate` | `sloId`, `burnRateThreshold`, `longWindowMinutes` (min `60`), `shortWindowMinutes` (min `5`, must be less than long) | SLO burn-rate alert. Most users let SLOs generate burn-rate alerts automatically via `burnRateAlerts: true`. |
| `mcp_schema_drift` | `changeTypes` (optional; subset of `added`, `removed`, `modified`, `escalated`, `server`; defaults to all tool changes), `toolNames` (optional string array; defaults to all tools), `severity` (default `warning`) | Trigger when an MCP server's tools change between runs: added, removed, or modified (input schema, description or annotations). `escalated` matches modified tools whose annotation hints became less safe. `server` matches changes to the server's name, version, protocol version or capabilities, and is opt-in: rules without it never fire on server changes. |
| `baseline_anomaly` | `metric` (required; `response_time`, `dns_lookup`, `tls_handshake`, `ttfb`, `content_transfer`, `lcp`, `fcp`, or `cls`), `sigmaThreshold` (default `3`, 2–10), `consecutiveCount` (default `3`, integer 2–20), `direction` (default `above`; allowed `above`, `below`, `both`), `severity` (default `warning`) | Trigger when the last `consecutiveCount` runs are all successes and each deviates by more than `sigmaThreshold`·σ from its own (hour × day-of-week × location) baseline in the configured direction. Any non-success run inside the window breaks the chain. |

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](/docs/guides/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.

| Label form | OTel attribute |
|---|---|
| `env:production` | `yorker.label.env="production"` |
| `service:payments` | `yorker.label.service="payments"` |
| `critical` *(no colon)* | `yorker.label.critical="true"` |

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

| Behavior | Meaning |
|---|---|
| `labels` omitted | Labels are **unmanaged** by config; the CLI preserves whatever labels exist on the remote. |
| `labels: []` | Explicitly clears all labels on the check. |
| `labels: [...]` | Sets the full list of labels on the check. |

---

## 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.

```yaml
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.

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

### `{{env.NAME}}`

Reads the environment variable `NAME` directly.

```yaml
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.

```yaml
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](/docs/reference/cli#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](/docs/reference/cli#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
```

| Setting | Behavior |
|---|---|
| `frequency` | Monitor overrides group, group overrides defaults. Falls back to 300s (5m). |
| `locations` | Monitor overrides group, group overrides defaults. Falls back to `["loc_us_east", "loc_eu_central"]`. |
| `alerts` | Monitor overrides group, group overrides defaults. **Explicit presence (even an empty array) is an intentional override.** An empty `alerts: []` on a monitor disables all alerts for that monitor. |
| `assertions` | Monitor-level assertions **replace** defaults entirely. They are **not merged** with `defaults.http.assertions`. This matches Terraform/Checkly semantics. |
| `labels` | Monitor-only (no cascade). Omitting leaves labels unmanaged. `labels: []` clears all labels. |
| HTTP config (`timeoutMs`, `followRedirects`, `maxRedirects`) | Monitor overrides defaults. |
| Browser config (`timeoutMs`, `viewport`, `device`, `screenshotMode`, `videoEnabled`) | Monitor overrides defaults. |

---

## Available Locations

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

| Location ID | Display Name | Fly Region |
|---|---|---|
| `loc_us_east` | US East (Ashburn) | `iad` |
| `loc_us_south` | US South (Dallas) | `dfw` |
| `loc_us_west` | US West (Los Angeles) | `lax` |
| `loc_na_north` | Canada (Toronto) | `yyz` |
| `loc_sa_east` | South America (São Paulo) | `gru` |
| `loc_eu_west` | Europe West (London) | `lhr` |
| `loc_eu_west_2` | Europe West (Paris) | `cdg` |
| `loc_eu_central` | Europe Central (Frankfurt) | `fra` |
| `loc_eu_north` | Europe North (Stockholm) | `arn` |
| `loc_ap_southeast` | Asia Pacific (Singapore) | `sin` |
| `loc_ap_northeast` | Asia Pacific (Tokyo) | `nrt` |
| `loc_ap_south` | Asia Pacific (Mumbai) | `bom` |
| `loc_ap_oceania` | Oceania (Sydney) | `syd` |
| `loc_af_south` | Africa (Johannesburg) | `jnb` |

---

## Full Example

```yaml
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"
```