Guides
Let an AI Agent Run Your Monitoring
Operate Uptimy through AI coding agents like Claude Code and Cursor via uptimyctl: bootstrap monitoring from a codebase, triage incidents, and wrap deploys in maintenance windows.
Overview
AI coding agents like Claude Code and Cursor are good at exactly the work monitoring involves: reading a codebase to find what needs watching, correlating noisy signals into a diagnosis, and running repetitive commands without forgetting a step. This guide shows how to put an agent in charge of your Uptimy workspace through uptimyctl.
Why it works: uptimyctl is a plain CLI with API-key authentication and -o json output on every command, which is exactly what agent tools consume. Uptimy also publishes /llms.txt and /llms-full.txt, so assistants can learn the product before touching your workspace.
Setup
Install the CLI with either method:
# Quick install
curl -sSfL https://raw.githubusercontent.com/uptimy/uptimyctl/master/scripts/install.sh | sudo bash
# Or with Go
go install github.com/uptimy/uptimyctl@latestFor agent use, authenticate by exporting your API key (keys start with upt_):
export UPTIMYCTL_API_KEY=upt_your-api-key-hereCredential precedence is flag > environment variable > config file (~/.config/uptimyctl/config.yaml, created by uptimyctl auth login). The environment variable is the right fit for agents: no interactive login, no key written into the project.
API Keys Grant Full Workspace Access
There are no read-only keys, so treat the key like a production credential. Keep it in an environment variable or secret manager, never in the repository, and revoke or rotate it from the dashboard if it may have leaked.
Example 1: Bootstrap Monitoring from a Codebase
The classic first task: point the agent at your repository and ask it to set up monitoring. A prompt like "read this repo, identify our services and public endpoints, and create Uptimy healthchecks for them" gives the agent everything it needs. Its plan will look like:
- Read the codebase and identify services and endpoints
- Export the workspace to
uptimy.yamland add a monitor for each endpoint - Show you the plan, then apply the file
The monitors it adds might look like:
version: 2
monitors:
- name: API health
target: https://api.example.com/health
tags: [api]
- name: Web app
target: https://app.example.com
tags: [web]
- name: example.com SSL
type: ssl
target: example.comThe agent then applies it:
# Start from what the workspace has today
uptimyctl export -f uptimy.yaml
# After editing the file: list the changes, then make them
uptimyctl plan -f uptimy.yaml
uptimyctl apply -f uptimy.yaml --yesMonitors are matched by name, so the agent can re-run its plan safely as the codebase evolves: a monitor that already exists is changed, never added twice. Nothing is removed unless it passes --prune.
Example 2: Incident Triage
When something breaks, an agent can do the tedious first pass: gather the open incidents, correlate them, and summarize what is actually going on before a human looks at it.
# Agent pulls all incidents as JSON and summarizes/correlates them
uptimyctl incidents list -o json
# Drill into a specific incident
uptimyctl incidents get <uuid> -o json
# Post its findings to the incident timeline
uptimyctl incidents add-update <uuid> --message "Correlated with the 14:02 deploy; DB connection pool exhausted."
# Resolve an incident opened by hand once fixed
# (incidents a monitor opened resolve when it recovers)
uptimyctl incidents resolve <uuid>
# File the write-up
uptimyctl incidents post-mortem <uuid> -f postmortem.mdThe -o json flag matters here: the agent gets structured incident data it can reason over, rather than scraping a table meant for humans.
Example 3: Deploys and Maintenance Windows
CI or an agent can wrap every deploy in a maintenance window so expected downtime never pages anyone. Alerts are held back only for the monitors in --services (UUIDs from uptimyctl applications list), and the window shows on the status pages in --status-page. It starts and completes on its own at the times given:
# Before the deploy
uptimyctl maintenances create \
--title "Deploy v2.5" \
--description "Rolling deploy of api and worker services" \
--start-at "2026-08-11T02:00:00Z" \
--finish-at "2026-08-11T02:30:00Z" \
--services '[{"uuid":"<api-uuid>","name":"API"},{"uuid":"<worker-uuid>","name":"Worker"}]' \
--status-page <status-page-uuid> -o json
# ... deploy ...
# Done early: complete the window now instead of at --finish-at
uptimyctl maintenances resolve <uuid>For finer control, the agent can pause and resume individual checks around risky steps, and trigger an immediate check run to verify the deploy instead of waiting for the next scheduled interval:
uptimyctl healthchecks pause <uuid>
# ... risky migration ...
uptimyctl healthchecks resume <uuid>
# Immediate post-deploy verification
uptimyctl healthchecks trigger <uuid>Config-as-Code Reconciliation
Agents are already good at diffing and reconciling code; the workspace file lets them treat monitoring the same way. It holds monitors, cron job heartbeats, status pages, alerts and reports:
uptimyctl export -f uptimy.yaml
# Agent edits uptimy.yaml toward the desired state, then:
uptimyctl plan -f uptimy.yaml
uptimyctl apply -f uptimy.yaml --yesThis works for copying a setup to another workspace (apply the same file with that workspace's key), keeping monitoring in version control, or letting an agent verify that what is running matches what the repo says should be running: plan lists every difference and changes nothing.
Other Commands Worth Knowing
- Status pages — manage status pages and their groups
- Schedulers —
uptimyctl schedulers listshows the available monitoring regions - Analytics — per-check execution and rollup queries with
--from/--to, useful for agents answering "how did this service do last week?"
Teach Your Agent About uptimyctl
Agents only reach for tools they know exist. Add a short note to your project's agent instructions file (for example, CLAUDE.md) so the agent knows the CLI is available, how it authenticates, and to always ask for JSON:
## Monitoring
- Uptime monitoring is managed with `uptimyctl` (Uptimy CLI).
- Auth comes from the `UPTIMYCTL_API_KEY` env var; never write the key to files.
- Always pass `-o json` for machine-readable output.With that in place, "check if anything is down and summarize it" becomes a one-line request instead of a walkthrough.