Open Status
Monitoring agents

Monitoring agents

Register, inspect, and manage private monitoring agents.

The Agents page is the fleet inventory for the workers that execute checks. It shows both organization-bound private agents and activity reported by the deployment's shared worker credential. Agents go stale after two minutes without configuration sync or result delivery.

Read the fleet view

The page reports online count, regions, worker versions, and distinct configuration revisions. More than one current revision can mean a rollout is still converging or that a worker is no longer polling. Inspect last-config and last-result times separately: a worker can poll successfully while its durable result queue cannot drain.

Each row shows the worker ID and name, health (online, stale, draining, disabled, revoked, or awaiting connection), declared and reported region, provider, environment, capabilities, labels, version, configuration revision, last configuration activity, and last result activity. When the declared region differs from the region the worker reports, the row calls it out—regional aggregation depends on the worker's actual report.

Register a private agent

Select Register agent and fill in the drawer:

  • Agent name and an optional stable Worker ID (a stable ID is generated when left empty; worker IDs cannot be changed later).
  • Declared region, Zone, and Provider describe where the worker should run.
  • Environment is required and groups the agent in the fleet view.
  • Capabilities and Labels are inventory metadata for operators (for example ipv6, private-dns, network=payments, or owner=platform). They do not change monitor assignment by themselves.
  • Operator notes hold deployment or maintenance context.

After creating the credential, copy the revealed WORKER_ID and MONITOR_WORKER_TOKEN values now—they are not shown again. Configure one worker deployment with those values plus the control plane URL and region:

dotenv
CONTROL_PLANE_URL=https://status.example.com
WORKER_ID=agent-internal-1
WORKER_REGION=internal-us
MONITOR_WORKER_TOKEN=agent_...

A private credential can only retrieve configuration and submit results for its own organization. Use private agents when a target is reachable only from a particular network—for example, an internal or customer-operated network.

Control scheduling

Every private agent has one of three scheduling modes, set from the agent's Manage drawer:

  • Active receives its assigned configuration and submits results normally.
  • Draining remains authenticated and may submit in-flight results, but its next configuration snapshot is empty. Wait at least one configuration poll before maintenance so the worker drops its local schedule cleanly.
  • Disabled is rejected by both configuration and result endpoints. Use this for an immediate operational stop that can later be reversed.

Changing scheduling mode does not reassign a monitor. Make sure another eligible worker or agent covers its region and exact assignments before draining or disabling it.

Assign monitors to an agent

The monitor editor's Network tab can restrict a monitor to one or more registered, non-revoked private agents (up to 20). With no exact assignment, the region rules determine eligible workers.

Revoke or replace an agent

Revoke stops the agent immediately and cannot be undone. Status refuses revocation while monitors still have an exact assignment to that agent, so reassign those monitors first. To replace a credential, register a new agent, assign its monitors, confirm successful check delivery, then revoke the old agent.

Shared-token workers are rotated from Settings → Instance → Monitoring workers. Rotation reveals the replacement once and takes effect immediately; update the token on every worker deployment.

Related documentation