Update, diagnose and remove the agent

Check, update or remove

Use status for the current state, doctor for diagnostics and logs for recent messages. agent start, stop and restart control the service on your machine. Use update or your package manager to update the program. agent uninstall removes the managed service; keys, configuration and pending data remain unless you explicitly choose --purge. For an unfinished connection you want to discard, use --reset-link before starting again.

metribeacon status --json
metribeacon doctor --json
metribeacon logs --lines 100
metribeacon agent restart
metribeacon update
metribeacon agent uninstall

When the connection fails

The agent saves pending readings locally and retries them with the same IDs, even after a restart. Its default buffer is limited to 64 MiB and 24 hours. When full or too old, the oldest batches are discarded and losses counted. Invalid data can also be discarded. Fix key or permission errors promptly. The first heartbeat and reading in your monitor confirm that setup worked; a running process alone does not.

Choosing a download

Use a package offered for your platform and read its support notice. Packages for Linux ARM64, macOS x64 and Windows ARM64 have not been tested natively. macOS and Windows installers currently lack operating-system code signing and may show a warning. Follow the supplied manifest verification instructions; do not disable system protection globally. If the needed package is unavailable, do not substitute another processor architecture.

Update an installed agent

New native installations enable remote updates with a separate key permission. An icon in the server list appears when a newer approved version is available. The workspace owner confirms each update; wait for confirmation after restart. Configuration-write permission is independent. Temporary contention returns 503 with update_busy and Retry-After: 1. Retry with the same operation_id and confirmed target; the interface retries for up to ten seconds. An accepted request is returned again without creating another update. The opaque target_id binds the approved release and source installation/version; refresh and confirm again if they change.

Native services enable owner-confirmed remote updates by default. A local administrator can use metribeacon agent remote-updates disable, enable or status; a saved local opt-out is preserved. “Allow remote updates” can also be disabled for the server key. npm and foreground installations are updated locally.

For a new native installation with an existing server key, use setup --non-interactive --device-id SERVER_ID --key-file /protected/device.key with an authenticated management identity. Setup enables the update permission once. The key must be active and limited to that server; broad or revoked keys cannot be reused. Restarts and normal updates do not change permissions.

Older installations need one local upgrade first. After upgrading, run metribeacon agent remote-updates enable as an administrator to install the updater. Offline servers are never queued for an unexpected later update.