Docs · Operate

Collection

Collection is where operational truth enters Watchpost. Every observation has a post identity, source, event time, ingestion time, quality, and bounded payload.

Central checks

The Run a check view performs an immediate HTTP, ICMP, TCP, DNS, or TLS check for enrollment and diagnosis. The same target can be saved as a durable per-post schedule. Watchpost runs it centrally, records latency, status, TLS expiry and explicit failures, and needs no software on the monitored endpoint.

Every monitoring method — the installed agent, central checks and device adapters — produces the same canonical observation envelope with explicit quality, units and freshness, so no method is a second-class citizen in history, rules or the survey. Check results enter the same rule pipeline as agent telemetry: a rule such as http.ok < 1 fires an alert the moment a scheduled target stops responding, and tls.expires_in_days warns before a certificate lapses.

HTTP  https://example.com/health
TCP   database.internal:5432
DNS   api.internal.example
TLS   example.com:443  server name: example.com

A failed check reports failure rather than manufacturing a healthy value.

Monitor a Linux machine

Install the separate Watchpost Agent before pairing. The post it observes is a post; the walkthrough in that page covers creating or selecting one during approval, and Agent architecture covers installation, pairing, delivery and local management. The loopback website is the normal setup surface; the equivalent CLI supports headless servers.

The agent uses local admin, technician and viewer accounts that remain manageable even while Watchpost is unreachable. The first setup creates the local admin with a chosen email and password; login is by email and password, and identities are normalized. State-changing local operations are recorded in a bounded local audit log.

watchpost-agent setup --email-file /secure/agent-email --password-file /secure/agent-password
watchpost-agent info --json
watchpost-agent pair --server https://watchpost.example.net
watchpost-agent pair-status

Remote exposure of the agent interface is explicitly experimental: binding a non-loopback address requires WATCHPOST_AGENT_EXPOSE=1, HTTPS termination at a reviewed reverse proxy, secure cookies, a bootstrap token for first-run setup over the exposed interface, and explicit proxy trust. List a local proxy with WATCHPOST_AGENT_TRUSTED_PROXIES=127.0.0.0/8 and restrict clients with WATCHPOST_AGENT_ALLOW_CIDRS/WATCHPOST_AGENT_DENY_CIDRS; forwarded headers are ignored from any other peer.

The post address remains useful inventory and an active-check target—it is not an inbound agent endpoint.

./watchpost-agent install
./watchpost-agent pair --server https://watchpost.example.com
./watchpost-agent pair-status
./watchpost-agent rotate
./watchpost-agent upgrade

Installation identity survives upgrade. Credential rotation uses overlap-and-confirm: the agent persists a replacement credential, Watchpost accepts it on the next delivery, and only then is the previous secret revoked; an unconfirmed replacement expires without breaking the old credential. Unpairing is server-first: the agent requests revocation at Watchpost with its current credential and clears local state only after confirmation, retrying while Watchpost is unreachable. A forced local reset warns that a lost machine's connection must still be revoked centrally. Archiving, deletion, revocation, reset and uninstall remain distinct operations so remote authority and retained evidence never change as a side effect.

Before transmission, each batch is written atomically to a private queue. Disconnection retains up to 256 batches or 8 MiB, retries back off, and only acknowledged data is removed.

Edit, archive, or delete a post

Use Posts → Edit to change the display name, address, owner, maintenance state, or archive state. The durable post ID cannot be changed because observations, rules, and evidence are bound to it. Archiving preserves history; permanent deletion requires the exact post ID and removes the post plus its post-scoped evidence. The Posts lifecycle section covers edit, archive, restore, permanent deletion, agent revocation, and replacement in full.

Submit one observation

curl --request POST http://watchpost-host:8080/api/v1/observations \
  --header "Authorization: Bearer $COLLECTOR_SECRET" \
  --header "Content-Type: application/json" \
  --data '{
    "version": 1,
    "post_id": "laptop",
    "collector_id": "laptop-host-agent",
    "observed_at": "2026-08-28T12:00:00Z",
    "sequence": 1,
    "signal": "cpu.percent",
    "value": 37.2,
    "unit": "percent",
    "quality": "good",
    "labels": {}
  }'

Collector health

The Collectors view distinguishes never connected, healthy, stale, offline, skewed, rejected, partial, and revoked. These states come from durable receipt, observation, clock, rejection, and quality facts; an empty history is never called healthy.

Survey every post

Resource survey combines compact trends, exact CPU, memory, and disk values, and dominant health bars across all enrolled posts. Colour is policy-aware: enabled rules and active alerts combine with maintenance, data freshness, quality, and agent health. Missing samples or missing policy are grey and explicitly unknown—not healthy.

The Rules view lists starter policies created during host enrollment. Operators can pause or enable each rule, and every survey card links back to its post policy.

Read-only SNMPv3

The SNMP setup guide uses authPriv with SHA-256 authentication and AES privacy. Select the post, enter the address and credentials, choose a bounded device kind, add no more than 64 named OIDs, then test the connection. A successful test saves address, username, kind and OIDs as a monitoring method beneath that post. Passwords are never returned; when the operator sets a poll interval and Watchpost has an installation master key (WATCHPOST_MASTER_KEY), the authentication and privacy passwords are stored encrypted at rest and the profile is polled on a durable schedule. Metadata-only profiles remain usable without a key.

name: uptime
oid:  .1.3.6.1.2.1.1.3.0
unit: ticks

Starter profiles cover network uptime/interface count, standard UPS battery/input/load values, environmental sensors, and storage appliances. Watchpost prefills standard OIDs where they exist and clearly leaves vendor-specific fields for the operator. Every returned reading includes quality, observation time and a five-minute freshness horizon; stale or missing evidence is never shown as a healthy zero.

Logs and changes

Use Evidence to add or search bounded logs. Change records capture deployments, configuration updates, maintenance, and other operational context.

Storage capacity

Watchpost measures its total SQLite footprint — the main database plus write-ahead and shared-memory sidecars — against a configurable cap and protects the free space on its data filesystem. When the node is at capacity, telemetry and log ingestion are rejected explicitly with HTTP 507 and an immediate retention pass reclaims space. Collectors and agents retry within their bounded queues, and any eventual queue overflow is counted and displayed. No loss is silent: Watchpost rejects writes explicitly, agents retry within bounded storage, and any eventual queue loss is counted and shown. The storage report is available to authenticated operators and is surfaced as a warning in the interface.

Future devices

Cameras, arbitrary consumer IoT, PLC writes, and building-control commands remain future exploration areas. Camera work should begin with availability and health rather than video ingestion. PLC writes and building-control commands require a separate threat model and must never be presented as safety control.