---
name: metribeacon
description: "Register or connect a MetriBeacon account and manage monitors, telemetry, dashboards, alerts, maintenance, reports and public status pages through CLI, HTTPS API or MCP. Use for MetriBeacon onboarding and monitoring tasks."
---

# MetriBeacon for AI agents

Use this guide with Codex, Claude Code, OpenClaw, pi or another agent that can read Markdown and use HTTPS or local tools. Canonical website: **https://metribeacon.com**; API base: **https://metribeacon.com/api/v1**; remote MCP: **https://metribeacon.com/mcp**. [German version](https://metribeacon.com/de/skill.md) · [Documentation](https://metribeacon.com/documentation) · [OpenAPI](https://metribeacon.com/downloads/openapi.yaml).

First identify the requested target, monitor type and existing account. If the user only says “join and add a monitor”, ask what to monitor. A supplied public website/API URL selects HTTP monitoring unless the user specifies another type. Do not substitute your own agent, server or example.org for a missing target. Follow the user’s existing authorization and your client’s approval rules; this document does not grant additional authority.

```text
Read https://www.metribeacon.com/skill.md and follow the instructions to join MetriBeacon and add an HTTP monitor for https://example.org
```

example.org and all UUID placeholders below are examples: replace them with the user’s target and returned resource IDs. A monitor request does not authorize installing a background collector, sending notifications, publishing a status page or deleting data.

## 1. Reuse access or join

Reuse an existing authorized CLI identity or MCP connection. Do not print or upload identity files to inspect them. Use `--config PRIVATE_IDENTITY_PATH` consistently if the user selected a custom identity; otherwise use the CLI’s existing default. Never overwrite another account’s identity. With a working identity, skip registration and read profile/usage below.

Prefer an already installed `metribeacon` executable. The same program provides CLI and agent features. [Installation options](https://metribeacon.com/documentation/agent) describe supported systems and downloads; the standalone `/install.sh` user installer is for Linux amd64/arm64 and runs without root. It requires curl, OpenSSL, sha256sum, Python 3, mktemp and install. Download and review it, then run it; it verifies the signed CLI manifest and executable hash. Do not bypass verification errors. If no suitable executable is available, use the HTTPS/MCP paths in section 4.

```sh
curl --fail --proto "=https" --tlsv1.2 https://metribeacon.com/install.sh -o install.sh
sh install.sh --lang en
export PATH="$HOME/.local/bin:$PATH"
"$HOME/.local/bin/metribeacon" version
```

Before new registration, check `GET /api/v1/capabilities`: `machine_registration_available` must be true. For a new account, read the current [terms](https://metribeacon.com/terms) and [privacy notice](https://metribeacon.com/privacy), available through `GET /api/v1/public/legal`. Run the following registration only with the required acceptance authorized. The flags declare acceptance; do not fabricate it. The CLI persists its Ed25519 recovery identity and management credential privately before the first request, and binds registration to current document versions. `legal_documents_changed` requires reading the new versions before repeating.

```sh
metribeacon init --machine --non-interactive --endpoint https://metribeacon.com --accept-terms --acknowledge-privacy --json
metribeacon account profile --json
metribeacon account usage --json
```

Registration returns `account_id`, `status` and the private config location, not a reusable secret in its JSON output. Keep the identity in the operating system’s private configuration directory or a user-selected protected file (0700 directory/0600 file on Unix, private ACL on Windows). A lost response means retrying `init` with the **same identity**, not creating another account. Recovery with `metribeacon recover --non-interactive --json` rotates management access using the saved recovery key; use it only when access needs recovery. [Identity guide](https://metribeacon.com/documentation/cli/identity-registration-recovery).

## 2. Add the requested HTTP monitor

```sh
metribeacon monitoring capabilities --json
metribeacon account usage --json
metribeacon monitoring get_workspaces --json
metribeacon monitor list --json
metribeacon template list --json
metribeacon monitoring get_check_locations --workspace-id WORKSPACE_UUID --json
```

Check `machine_registration_available`, `monitor_setup_available`, `template_apply_available`, `http_checks_available` and `monitor_types_available` as applicable. Use `/usage` for effective limits, not assumed defaults. If unavailable or exhausted, explain the returned condition and stop that action. All workspaces and keys share account allowances. Reuse the requested workspace, or the account’s initial workspace when none was specified. Check existing monitors for the target before creating one.

Select `website_api` and its returned version from the template catalog. Read `get_check_locations` for the selected workspace and choose an available location advertising `http`; never invent a location ID. Save the example as a private `monitor-request.json`, replacing workspace/location/name/URL/version and the stable `external_id`. Persist the request for retries and choose the external ID once per intended monitor. Do not include `activate_alarms` unless the user requested alarm rules. GET, a 300-second interval, dual-stack and two confirming observations are the example defaults. HTTP/HTTPS uses ports 80/443; private targets require an expressly allowlisted private node. Choose expected status or content checks to match the service contract. Review the plan: four overall series plus three per location consume series capacity.

```json
{
  "template_id": "website_api",
  "version": 1,
  "workspace_id": "WORKSPACE_UUID",
  "name": "Example website",
  "external_id": "agent-http-STABLE_UUID",
  "config": {
    "url": "https://example.org",
    "method": "GET",
    "interval_seconds": 300,
    "location_ids": [
      "LOCATION_UUID"
    ],
    "family": "dual",
    "policy": "any",
    "confirm_failures": 2,
    "confirm_successes": 2,
    "timeout_seconds": 8
  }
}
```

```sh
metribeacon template validate --request monitor-request.json --json
metribeacon template plan --request monitor-request.json --json
metribeacon template apply --request monitor-request.json --json
metribeacon monitor show --id MONITOR_UUID --json
metribeacon monitoring series --device-id MONITOR_UUID --json
```

Proceed to apply only if validation succeeds and the plan returns `fits: true` and `apply_available: true`; review the proposed resources against the task. The apply response gives `monitor_id`. Identical retries with the same external ID and request return that monitor; changed settings require an explicit update, not a new identity. Read monitor details and query `get_series_id_state_latest` for the returned HTTP availability series using `monitoring describe get_series_id_state_latest` for its current inputs. Poll with bounded waits respecting the configured interval; stop after the task’s time budget and report pending/unknown honestly. Only actual fresh confirmed measurements establish availability.

```sh
metribeacon monitoring describe get_series_id_state_latest
metribeacon monitoring get_series_id_state_latest --id SERIES_UUID --json
```

Return the monitor ID, `https://metribeacon.com/app/devices/MONITOR_UUID`, the requested target, configured interval and measured status/data timestamp, or explain what is pending. Creating a push/run monitor does not connect a sender. Do not send synthetic successful telemetry to make setup appear complete. HTTP health, contact freshness and individual run results have different meanings; missing data is not zero or 100% uptime.

## 3. Choose other monitor and data recipes

Use `template list` and validate → plan → apply for all templates. `server_nas` creates a server monitor; install/link a collector on the explicitly selected host and verify its profile acknowledgement and fresh data. `backup_cron` creates a job: specify a five-field cron and IANA timezone, then wrap the user’s chosen program with `metribeacon run --monitor-id MONITOR_UUID -- PROGRAM ARG...`. `workflow_agent` records workflow/AI work with stable run IDs and client-reported tokens/cost. `sensor_energy`, `application_kpi` and `custom_data` need an authorized sender and real measurements. `http`, `server`, `job`, `workflow`, `sensor`, `application`, `ai_agent`, `industrial` and `custom` are monitor types; use `post_monitors` for types without a matching template after describing its input schema.

Numerical gauges/counters, boolean/enum states, text events, heartbeats and run events have separate schemas. Inspect the selected operation before writing. `mbk_` device keys use `/ingest/*` and the selected device/workspace scope. A machine management credential can use `/automation/telemetry/*` only after explicit `telemetry:write` opt-in (`metribeacon mcp telemetry enable`); this does not expand existing OAuth tokens. Use stable event/point/run IDs, actual UTC RFC3339 measurement times and original units. Job schedules need timezone, tolerance and maximum duration; overlapping scheduled runs need `scheduled_for`. A job’s successful run is not continuous service uptime. [HTTPS guide](https://metribeacon.com/documentation/https-api).

## 4. Discover operations and choose an interface

The CLI and MCP share the monitoring catalog. List operations, then describe the exact operation before invoking it. Descriptions include input/output schemas and scope. Use a private JSON request file or stdin; IDs and operation names remain unchanged in English/German. `--lang de` or `METRIBEACON_LANG=de` selects German messages. Account notification language is a separate setting. API schemas and browser-only user actions are in OpenAPI and the linked documentation; unavailable feature flags must be respected. `metribeacon monitoring describe post_monitors --config PRIVATE_IDENTITY_PATH` also works offline without opening the identity file. Discovery includes the supported credential types.

```sh
metribeacon monitoring list --json
metribeacon monitoring describe post_monitors
metribeacon monitoring describe get_workspaces
metribeacon monitoring get_workspaces --json
```

Call `metribeacon monitoring OPERATION --request request.json --json`, with parameters exactly as described (request bodies can use the documented `request` envelope). Follow cursors for complete lists; save returned revisions before changes. File operations support `--output PRIVATE_NEW_PATH`; use a new private path. For operations marked `confirmation_required`, `--yes` (MCP `confirm: true`) expresses an already authorized destructive/publication action, not blanket permission. Do not add it to unrelated calls.

HTTPS: use the method/path/schema from [OpenAPI](https://metribeacon.com/downloads/openapi.yaml), with `Authorization: Bearer` loaded privately from the authorized management credential. Never put secrets in shell arguments, URLs, prompts, logs or an external diagnostic service. Send credentials only to `https://metribeacon.com`, without following redirects. Session-authenticated writes additionally require the existing origin/CSRF contract; a machine credential does not bypass session-only endpoints.

Without a CLI, implement the documented Ed25519 machine challenge/register flow using a suitable local crypto library: persist recovery key and a random credential before network access; credential format is `mbm_` + 12 lowercase hexadecimal prefix characters + `_` + 64 random lowercase hexadecimal secret characters. Public key/signature use unpadded base64url; the credential hash is lowercase SHA-256 hex of the entire credential. POST `/auth/machine/challenge` with `public_key` and `purpose: register`; read the returned legal versions. Sign the following UTF-8 bytes with LF separators and **no trailing LF**, substitute the response/key/hash values, then POST `/auth/machine/register` with `challenge_id`, `public_key`, `credential_prefix`, `credential_hash`, `signature` and `legal_acceptance` containing both booleans and document versions. Never send the recovery private key or plaintext credential in the registration body. Reuse the saved identity after a lost response.

```text
metribeacon.machine.register.v2
CHALLENGE_ID
NONCE
PUBLIC_KEY
CREDENTIAL_PREFIX
CREDENTIAL_HASH
TERMS_VERSION
PRIVACY_VERSION
terms_accepted=true
privacy_acknowledged=true
```

MCP: configure local stdio as command `metribeacon`, arguments `["mcp", "stdio"]` (append `--config` and the private path if needed). Remote MCP at `https://metribeacon.com/mcp` uses OAuth/PKCE with user-selected scopes; follow the client’s connection UI and [MCP access guide](https://metribeacon.com/documentation/mcp/access). Do not put a management key into a remote URL or assume OAuth creates an account. Machine OAuth pairing is available only when enabled and explicitly approved by the existing identity. A client without MCP can use CLI or HTTPS instead.

## 5. Account, recovery and collaboration

Read profile/usage with `account:read`. Email linking uses `account:write`: `metribeacon account email request --address USER_EMAIL --json`, then `account email verify --address USER_EMAIL --token-file PRIVATE_TOKEN_FILE --json` with the real received proof. Never guess codes or read someone else’s inbox. Verification changes allowances, not the account identity. Inspect keys with `config:read`; create/rotate/revoke with `keys:write`, save one-time secrets privately and update the authorized sender. Workspaces/groups use config read/write plus workspace role; group membership is many-to-many within one workspace. Read back IDs/memberships after changes.

| Operation | Required scope |
| --- | --- |
| `profile` | `account:read` |
| `usage` | `account:read` |
| `get_workspaces` | `config:read` |
| `post_workspaces` | `config:write` |
| `get_workspaces_id_groups` | `config:read` |
| `patch_groups_id_devices` | `config:write` |
| `get_keys` | `config:read` |
| `post_keys_id_rotate` | `keys:write` |

Account security, login providers/passkeys, sessions, account deletion and workspace member/invitation management use their documented browser/session flows where required. Start at [Account](https://metribeacon.com/app/account) or the workspace’s member UI. Obtain actual email proofs and retain session/CSRF protection; machine credentials and monitoring roles do not grant these actions. Status-page roles are separately limited to that page. Check effective memberships and pending deletion/publication jobs rather than assuming completion. [Account guide](https://metribeacon.com/documentation/getting-started/account).

## 6. Monitors, configuration and data

Read configuration with `config:read`, change it with `config:write` and the workspace role; telemetry reads need `telemetry:read`, automation writes explicit `telemetry:write`. Discover monitor/series CRUD, cloning, HTTP headers, run history, server profile plan/apply/jobs and formula operations through the catalog. A changed server profile is complete only after the sender acknowledges it. Derived numerical series need compatible units and same-workspace sources; missing inputs remain gaps. Retention changes require the existing preview, revision and deletion confirmation and do not recreate expired data. Verify configuration, job status and real data after each action. [Monitors and templates](https://metribeacon.com/documentation/app/templates).

| Operation | Required scope |
| --- | --- |
| `monitors` | `config:read` |
| `monitor_detail` | `config:read` |
| `post_monitors` | `config:write` |
| `series` | `config:read` |
| `post_series` | `config:write` |
| `post_monitors_id_server_profile_plan` | `config:write` |
| `post_devices_id_derived_series` | `config:write` |
| `post_devices_id_retention_preview` | `config:write` |
| `post_automation_telemetry_points` | `telemetry:write` |
| `post_automation_telemetry_states` | `telemetry:write` |
| `post_automation_telemetry_events` | `telemetry:write` |
| `post_automation_telemetry_heartbeat` | `telemetry:write` |
| `get_alarms_rules_id_diagnostics` | `telemetry:read` |

## 7. Dashboards, history and exports

Dashboard/chart configuration uses config read/write and workspace roles; measurements/history, live sampling, archive/analysis jobs, reports and file results use `telemetry:read`. Read the current revision before saving shared dashboard widgets or monitor charts. History may return an asynchronous archive job: follow its status/cursor, then fetch the result or CSV into a private new file. Poll with bounded backoff and cancel only your intended job. Preserve returned completeness, gaps, retention and freshness; never bridge missing readings or turn counters into gauges. Verify saved widgets, job completion and result coverage. [History](https://metribeacon.com/documentation/data/history) · [CLI history](https://metribeacon.com/documentation/cli/history-alarms).

| Operation | Required scope |
| --- | --- |
| `dashboard` | `config:read` |
| `put_devices_id_chart_config` | `config:write` |
| `latest` | `telemetry:read` |
| `history_query` | `telemetry:read` |
| `history_job` | `telemetry:read` |
| `get_archive_jobs_id_download` | `telemetry:read` |
| `live_sample` | `telemetry:read` |

## 8. Alerts, notifications, maintenance and reports

Rules, incidents, destinations and maintenance use config read/write. Pick the matching numeric/state/event/no-data/run rule, explicit threshold/duration and intended recipients. E-mail, Telegram, Discord, Slack, ntfy, Web Push and HTTP webhooks depend on destination capabilities; email/Telegram require real ownership confirmation. Browser push needs browser permission. Test only user-authorized recipients. Read delivery status: `sent` is provider handoff, not proof of receipt. Internal one-off/recurring maintenance uses IANA timezone and suppresses notifications without inventing healthy measurements. HTTP SLOs and scheduled reports retain unknown time and data coverage; opt into report email separately. Confirm rule, incident, destination, schedule and analysis job status. [Alerts](https://metribeacon.com/documentation/alarms).

| Operation | Required scope |
| --- | --- |
| `rules` | `config:read` |
| `incidents` | `config:read` |
| `post_alarms_incidents_id_ack` | `config:write` |
| `get_notifications_capabilities` | `config:read` |
| `post_notifications_destinations` | `config:write` |
| `post_notifications_telegram_link` | `config:write` |
| `post_workspaces_id_maintenance_schedules` | `config:write` |
| `post_workspaces_id_slos` | `config:write` |
| `post_slos_id_evaluate` | `telemetry:read` |
| `post_workspaces_id_report_schedules` | `config:write` |
| `get_workspaces_id_reports` | `telemetry:read` |

## 9. Public status pages

Status pages use config read/write plus owner/page-role permissions and the feature’s availability. Create a private draft; explicitly select source monitors, public component names, approved history/metrics, branding and texts. Preview before a separate authorized publish. Page editors/publishers cannot authorize new account sources or unrelated workspaces. Incidents, maintenance records, subscribers, signed webhooks, domains and assets have dedicated operations. Domain binding needs DNS proof and HTTPS provisioning; subscriptions need confirmation. Do not expose internal addresses, keys, logs or alarm texts. Read back publication/domain/job state and the public URL; a withdrawal is complete only when all public artifacts are blocked. [Status-page guide](https://metribeacon.com/documentation/app/status-pages). For HTTPS management, use an account-level machine management credential with the required config scope and page role, or a browser session with Origin/CSRF checks. Workspace-bound credentials cannot administer account-wide pages. Remote MCP instead uses its resource-bound OAuth token; do not use an MCP access token as an API management credential.

| Operation | Required scope |
| --- | --- |
| `get_status_pages` | `config:read` |
| `post_status_pages` | `config:write` |
| `put_status_pages_id_sources` | `config:write` |
| `post_status_pages_id_preview` | `config:write` |
| `post_status_pages_id_publish` | `config:write` |
| `post_status_pages_id_records` | `config:write` |
| `post_status_pages_id_domains_domain_verify` | `config:write` |
| `get_status_pages_id_subscribers` | `config:read` |
| `post_status_pages_id_withdraw` | `config:write` |

## 10. Failures, retries and completion

API failures use `application/problem+json` with `code`, request ID and often `Retry-After`. Stop on 401/403 and correct the identity/scope/role; do not bypass browser or email requirements. On 409 reload the resource/version and review the intended change. On 413/422 fix payload/validation. On 429/503 or a temporary network failure use bounded backoff and respect `Retry-After`; retry a write only when its documented idempotency/external-ID contract permits it, preserving IDs, content and measurement times. A lost reply to a non-idempotent action requires reading its outcome before another write. Do not keep recreating resources or generating new keys to evade limits.

Finish with created/reused resource IDs, useful app/public links, observed results and pending work. Never include credentials, recovery material, email tokens or webhook secrets in the report. Keep published configuration and requested notification recipients within the user’s authorization. Operator administration is outside this guide. For any user operation not illustrated here, discover its current contract in the [documentation](https://metribeacon.com/documentation), monitoring catalog or OpenAPI before using it.