Yard Docs
Sign in
On this page

Monitors

Health checks for any address, flows that check your APIs step by step, cron monitors for scheduled jobs, environments and the alerts behind them, all running on your own runner.

Updated November 7, 2026 · 16 min read

A workspace's monitors are checks that run against any address your runner can reach: what your projects build, or a service you only use.

  • Health checks ask one address and expect an answer. A health check is a flow with one GET step.
  • Flows are multi-step HTTP checks: log in, call an endpoint with the token you got back, check what it answered.
  • Cron monitors expect a ping from a scheduled job and tell you when it is late, failed or stuck.
  • Environments hold the values flows use, such as HOST, with secrets sealed.

Monitors belong to a workspace and run on its runner, in the same box as its agents: requests to your services and queries to your database come from your machine, never from Yard's servers. A check is written by hand, from a repository (the agent drafts it, and nothing runs until you turn the draft on) or from an OpenAPI file. Monitors in the sidebar lists what runs and what waits for you.

Flows

A flow is a list of steps, run in order. Each step is a request (method, URL, headers, body) with:

  • Assertions: the status code, the response time, a field that must exist or equal a value, a condition ({{response.body.count}} gt 0, with 23 operators), or a JSON schema the body must match.
  • Captures: a value taken from the response (body.token) that later steps use as {{captures.token}}.
  • Templates anywhere in the URL, headers and body: {{env.HOST}} from the flow's environment, {{steps.0.body.id}} from an earlier step.
  • Run if: a condition that skips the step when it is false.
  • Cleanup: a step marked to run even after an earlier one failed, to delete what the flow created.
  • Retries, a timeout, and sensitive body (the response is stored censored).

A flow runs on demand (Run), on a schedule (30s, 5m, 1h or a cron expression like */15 * * * * in a timezone; at most every 30 seconds), or from outside through its webhook URL (POST <api>/v1/hooks/flows/<token>, for a deploy or CI). Test this step in the editor runs one step on its own, after the steps before it, without recording a run.

Import a flow's steps from an OpenAPI document, a Postman collection or a curl command: choose a file or paste the text. Bare {{name}} variables become {{env.name}}.

What a run says

A run is passed, failed, timeout or error, with every step's response (bodies kept up to 50 KB). A run is inconclusive when only the runner was at fault: it was offline, too old, or its own network could not reach anything. Inconclusive runs never count as downtime and never alert as a failure. Runs are kept 30 days unless the workspace sets another number of days (Monitors → Alerts → Run history).

Your network or not

On a runner of your organization, or your own, flows may reach private addresses (10.0.0.5, localhost on the runner): checking your own network is the point. On Yard's official runners they may not: private, loopback and cloud metadata addresses (169.254.169.254) are refused before any request, also after a redirect.

Environments

An environment (production, staging) is a set of variables. A flow runs with its own environment, or the workspace's default one; switching it on the flow's block or in the flow editor changes the values the next run uses.

The environment editor is the right column of the Monitors page (under the checks on a narrow window):

  • A list picks the environment, with Default beside the default one. New makes another. The … menu has Rename, Make default and Delete; checks that ran in a deleted environment run in the default one.
  • Each variable is a row: its name, its value and a button to remove it. A secret that is set reads Secret, set with Replace; its value is never shown. A variable that drafts read and nobody has set yet is a field to fill in, marked "Needs you: 3 drafts read it".
  • Add a variable takes a name and a value. Tick Secret: kept on your runner, never shown again before Add for a password or a token.
  • Under the variables: "Used by 4 checks and 2 drafts", and the other environments as links.

Run with, over the list of checks, runs every listed flow once with another environment and shows those results in the list, with a line that says so. The flows keep their own environment, and these runs are try-outs: they do not count for a check's status, its history or its alerts. Choose the first entry of the list to see the checks in their own environment again.

A secret variable is sealed in your browser, or by the runner for the yard command, to your organization's vault: only its runners can open it, Yard's servers cannot. Yard never shows its value again, not in the app, not to agents and not in run results: the runner gets it for one run only, passes it to the check on its standard input (never a file), and masks it in everything the run returns.

Cron monitors

A cron monitor has a schedule, a grace period and, optionally, the longest a run may take. Its job pings its URL:

Shell
curl -fsS -m 10 --retry 3 https://api.yard.example/v1/ping/<token>/start
./backup.sh && curl -fsS -m 10 --retry 3 https://api.yard.example/v1/ping/<token> \
  || curl -fsS -m 10 --retry 3 https://api.yard.example/v1/ping/<token>/fail

A /start ping opens an execution and the next success or failure closes it, with its duration; a job that only pings at the end works too (send {"durationMs": …} as JSON to record how long it took). The monitor is healthy after a success, failed after /fail, late when no ping came by the next scheduled time plus the grace period, and stuck when a run started and did not finish within its limit. A run more than twice as slow as usual (with enough history) is flagged slow.

Insights

Insights are no longer part of Monitors. A question to your database is now a stat, a block on any canvas: an agent writes one read-only query, you approve it, and the block shows the answer. Every insight board from before is a canvas of its own, with the board's name; a block that showed one elsewhere says so and has Open tab. See Stats.

The databases stats ask are on the Insights page, under Sources (the old address …/monitors?section=insights opens Insights): each with its name, its address without the password, and how many stats use it. Rename changes the name, Read tables again reads its tables and columns anew (after a migration), and Remove deletes it from Yard together with the queries and results of the stats that use it; the database itself is not touched. Add source connects one. See the Insights page.

Alerts

A flow alerts once when it failed a number of runs in a row (3 by default), again only after its cooldown (30 minutes) while it keeps failing, and once when it recovers. A cron monitor alerts when it is late, failed or stuck, and when it recovers. When the workspace's runner goes offline, one alert says so, however many scheduled runs it misses, and another when it is back.

Alerts reach everyone who can see the workspace, viewers included: in Yard's notifications, and by email for people with Monitor alerts on (Account → Email; on by default). Add channels under Monitors → Alerts: an email address, or a webhook. Slack and Discord webhook URLs get messages in their own format; any other URL gets JSON with the event, the monitor and a link. Webhooks are sent over https to public addresses only.

The Monitors view

Monitors is under More in the workspace's sidebar (or Go to monitors in the command palette).

Environments opens the environment editor: from a window 1150px wide at the right of the checks, below that under them.

  • The header says "Checks run on your runner against any address. 6 passing, 1 failing, 3 drafts." It has two buttons: Environments, and New check, the one filled button, a menu of the three ways to write a check:
    • Write one by hand opens one dialog with Health check, API flow and Cron. A health check asks for a name, a method, an address (any address, or one built from the environment: {{env.HOST}}/health) and Every N minutes. It passes when the answer is 200 and runs from the moment you add it. An API flow is named there and gets its steps in the flow editor. A cron monitor asks for its schedule, time zone and grace period.
    • Write from an OpenAPI file opens the import dialog: choose a file or paste it, Read steps, then Create flow. It also reads a Postman collection or a curl command.
    • Draft from the repositories opens Set up monitors (below).
  • Drafts are announced in one line: "The agent wrote 3 draft checks from atlas. They do not run until you turn them on." Review drafts shows them: Drafts, one row per canvas, with Open canvas (Open docs for the workspace's main canvas) and Turn on N for the ready ones, and Waiting in projects, one row per project with monitors it has not merged, with Open project and Merge N.
  • Checks is one list of flows and cron monitors. Each row has its name over its request or number of steps and its schedule ("GET /health, every minute") and, on a wide window, where it came from (the repository or file it was written from, else "Written by hand"); its last ten runs as small bars (a failure is a tall red one); its status (Passing, Failing, Paused, Inconclusive or Not run yet); what the last run said ("200 in 84 ms", "Pinged 03:02"); Open and a More menu. A check whose linked files changed says so in blue. The name opens the check's page.
  • A failing flow says why on its row ("Step 3: expected 201, got 500") and has Fix with an agent, which starts a project that reads the failing run and the flow (an investigation) and opens it. Failing unfolds the row to its steps, each with what it answered in the last run ("200, token kept", "Expected 201, got 500", "Not run"), under them "Failing since Monday 08:00, 12 runs." and Open last run.
  • Running, Failing and Drafts, each with its count, narrow the list to what runs, what is failing, or what waits to be turned on or merged. Run with is at the right of the same row (see environments).
  • Alerts, status pages and incidents is a folded section at the foot: the channels (with Send test), the recent alerts and how long runs are kept, the status pages and their incidents.

Links from before still work: …/monitors?section=cron opens the list, ?section=environments opens the editor and ?section=alerts opens the foot.

Set up monitors (New check, then Draft from the repositories) has the workspace's agent do it: tick the repositories, what to look for (API routes and OpenAPI documents as flows, scheduled jobs as cron monitors, env example files as environments), the canvas the drafts go on (Put the drafts on), and one optional line. The agent reads the code and puts the drafts on that canvas for you to review, edit and turn on; see Drafts. It is told which monitors the workspace already has, drafts included, with what each checks and the files it was written from, so it drafts only what is missing and says at the end what it left out and what an existing monitor lacks. In the dialog, a repository that monitors were already written from says so ("Has 2 flows, 1 cron monitor"). The request starts a project of its own, whose chat shows what you asked for as one sentence ("Draft monitors for atlas: flows and cron monitors, in the canvas Monitors.") with your line under it.

  • A flow's page has its name and state ("Failing since 08:57"), Edit steps, Run now and, while it fails, Fix with an agent in its title bar at every width. Under it: the notice when a linked file changed; the last runs as a strip (a failed one carries a dot; picking one shows its steps) with how many passed and failed; the steps of that run, each with its method, its path and what it answered (live while it runs); the response of the step that failed; Recent runs, each with Open; then its linked files and Last run (when, and how long it took), the schedule, the environment and the canvas its block is on. A draft says so, and which values it needs before it can run.
  • The flow editor (Edit steps) has the steps on the left (with the recent runs under them), the open step in the middle with its tabs Request, Checks, Captures and Execution, and the step's last answer on the right, its body as a tree. Typing {{ in a URL, header or body offers the environment's variables (a secret says so, not its value), earlier captures and steps. Edits save themselves a moment after you stop typing. The row has the flow's environment, schedule and alerts, … (rename, pause, delete) and Run flow. A run opens on its own page from the list of runs.
  • A cron monitor shows its executions as bars, their runtime as a line with slow ones marked, the ping URL with Copy and snippets for curl, crontab, Node and Python, its schedule with when the job last ran, and its linked files.

Drafts

A check you write by hand, or read from a file, runs at once. One an agent makes for you starts as a draft: it does not run on a schedule, sends no alerts, and has no ping or webhook URL until you turn it on.

  • On a canvas. Asked to draft monitors, the workspace's agent reads your repositories and puts each draft on the canvas you asked from, naming the repository it was written from. A draft says Ready, or which values it still needs: the {{env.NAME}} variables its steps use that its environment does not set, and for an environment its variables without a value. An agent never writes a secret into a draft: the variable is named, and you give its value under Needs you, where it is sealed like any other secret. Turn on makes one draft live; a canvas with several turns on all the ready ones at once.
  • In a project. A flow, cron monitor or environment that a project's agent creates is always a draft of that project and is listed under Made by this project. Merge into the workspace turns the ready ones on and puts their blocks on a canvas: the one the project was made from, or another you pick. The ones that still need values stay in the project. Closing or deleting a project that still has unmerged monitors asks whether to merge them or delete them with it.
  • A monitor suggested in the chat arrives the same way: confirming its card puts a draft on the canvas the chat is on.

A draft can be run by hand once no value is missing, to see what it does before it is turned on; such a run never alerts.

Run now works for a live flow, a paused one and a ready draft. A run by hand of a live flow counts like a scheduled one (its status, its history, its alerts) and leaves the schedule where it was.

Linked files

A monitor remembers the repository files it was written from, across repositories. Agents record them when they write a monitor; you add or remove one under Linked files. When a fetch brings new commits to the workspace's copy of a repository, Yard compares each linked file with the version the monitor was written from. A file that changed, or was deleted or moved, shows a notice on the monitor: which file, who changed it and in which commit. That is all it does: a changed file never changes the monitor's status, stops it or sends an alert.

Still correct removes the notice until the file changes again. Ask the agent to check starts a project with the monitor as context (a chip such as "Flow: Sign in" above the message) and a message about the changes ready to send: the agent gets the monitor's steps and each changed file with its commit and author. When the agent changes the steps and you agree, the notice goes too. Checking linked files needs a runner on 0.23.0 or newer.

On the canvas

Add, then Monitor on a canvas opens Set up monitors for it; so does Draft monitors in the … menu of a selection of repository blocks, with those repositories ticked. Under the Monitor tile, Flow, Cron monitor and Environment put one of the workspace's on the canvas, or make a new one by hand.

A draft's block has a dashed border and the word Draft, says what it is and which files it came from (or the project that made it), and ends with Ready and Turn on, or Needs 2 values and Open. Open shows the draft's steps, schedule and linked files with Needs you beside them: one field per missing value (a secret is typed into a password field and is never shown again), and Save and run once. A tab with drafts has one line above it: how many there are, how many are ready, and Turn on N ready. The line is above the tab's list view too.

A running flow block shows its steps as a pipeline with each step's last result, live while it runs, with Run now, the environment it runs in and Open. A running cron block says when its job last ran and how long it took ("Last ran Monday 08:00, 2 min"), or "Has not run yet"; the same line is on its row in the tab's list. An environment block edits its variables in place, secrets shown as set. A block whose monitor's linked files changed says "2 linked files changed" in blue, with Review. A flow block sets its environment on the block itself. Deleting a monitor block asks whether the monitor goes too. See the canvas.

With agents

In a terminal or an agent's turn, yard flow, yard cron, yard env and yard insight work with the workspace's monitors (see the CLI reference): an agent can write a flow, run it, read why a step failed, fix it and run it again in one turn, and put it on the canvas with yard-canvas monitor <id>. With --draft it makes a draft on the canvas instead, and in a project's box what it makes is always a draft of the project. --source <repo>:<path> records a file the monitor was written from. When you ask for suggestions instead, it proposes monitors as cards in the chat; nothing exists until you confirm one, and what then exists is a draft on the canvas the chat is on. A monitor block you select as context gives the agent its definition and its last failure.

Was this page useful?
Edit this page