Docs · Operate

Agent architecture

Watchpost Agent is separately installed software that observes one machine and sends telemetry outbound to Watchpost. It is one monitoring method beneath a post - see Posts for the canonical model of what is monitored.

Install first, pair second

The agent is useful software before it has authority to send data. Installation creates its service, private state, bounded queue, local website, and CLI. Pairing is a later, revocable relationship with exactly one Watchpost post.

Pairing lifecycle

The complete lifecycle is: unpaired agent → pairing request → short-lived human-verifiable approval → selected or newly created post → post-scoped credential → first accepted telemetry → connected state.

• Installation happens before pairing, and pairing is initiated by the agent communicating outbound to Watchpost.
• Pairing associates the agent with a post rather than creating a second inventory object.
• Pairing requests expire; an absent, invalid, expired, or already-consumed request fails explicitly rather than being replayed.
• Credentials are private, post-scoped, revocable, and not interchangeable with user sessions.
• Approval, credential issuance, first delivery, rotation, revocation, unpairing, reset, and deletion are different lifecycle events. They are never synonyms.
• Deleting a post does not remotely uninstall an agent, and a deleted or revoked relationship requires a fresh valid pairing operation rather than silently reusing old authority.

Both surfaces call one application service and persist one state model. A feature is not complete if it works through only one surface without an explicit reason.

watchpost-agent install
watchpost-agent pair --server https://watchpost.example.net
watchpost-agent pair-status

See Posts → Create and connect a machine post for the end-to-end walkthrough.

Connection inventory

Once approved, the post row shows the agent hostname, platform and explicit connection health. These are monitoring details beneath the post - not another inventory object. A host with no agent says so directly and keeps its compact Connect action.

Telemetry delivery

The agent collects CPU, memory, one-minute load, uptime, and up to eight absolute filesystem paths on a bounded 15-3600-second interval, then delivers observations in batches to the post identity.

• Bounded batching and sequence: observations carry contiguous sequence numbers within a batch, and acknowledgement refers to the last accepted sequence.
• Private on-agent queue: up to 256 batches or 8 MiB survive restart and replay oldest-first with bounded exponential backoff.
• Watchpost unavailable: the agent keeps collecting into its bounded queue and exposes the skipped-collection count when the queue is full; it never calls missing evidence healthy.
• Rejected batch: an unknown protocol version or partial batch fails closed and remains visible; credentials that no longer match are surfaced as revoked or rejected.
• Freshness, clock skew, missing, partial, rejected, and stale data remain distinguishable; a lack of recent data is never presented as healthy.

Configurable local evidence

The agent website and watchpost-agent configure command edit the same collector profile: enable CPU, memory, load and uptime, choose filesystem paths, and set the interval. Filesystem observations retain their path label.

Explicit health and lifecycle

Connections distinguish never connected, healthy, stale, offline, clock-skewed, partial, rejected and revoked. A Watchpost administrator may revoke server authority. The machine operator may separately unpair the local agent, reset it by typing its installation ID, or uninstall it; these operations are deliberately not synonyms. Credential rotation uses overlap-and-confirm so an unconfirmed replacement expires without breaking the old credential, and unpairing is server-first with retry while Watchpost is unreachable.

Local management and trust boundaries

The agent website listens on loopback by default and protects state changes with an authenticated local session, Origin validation and CSRF controls. Local admin, technician and viewer accounts remain manageable even while Watchpost is unreachable, and state-changing local operations are recorded in a bounded local audit log.

Non-loopback access is an explicit advanced mode requiring HTTPS at a reviewed reverse proxy, secure cookies, a bootstrap token for first-run setup over the exposed interface, and explicit proxy trust. Agent delivery is outbound, so monitored machines do not require an inbound management port. See Security model for the complete trust boundary and safe failures.