Docs · Operate

Posts

A post is the central domain object of Watchpost: the system, service, endpoint, or device the operator cares about. Every observation, rule, alert, incident, and piece of evidence refers to a post.

The central rule

A post is the system, service, endpoint, or device the operator cares about. An agent, central check, or device adapter is a monitoring method attached to that post.

What is a post?

A post is a durable identity with a fixed ID. It carries a display name, an optional address, labels, ownership, a post kind, and the set of monitoring methods attached to it. History is stored against the post, not against any particular method, so the answer to “what do we know about this system?” does not depend on how it is being observed today.

post:  warehouse-api-01
kind:  service
address: 192.168.10.42
labels: site=warehouse, tier=api
methods: watchpost-agent, http-check

What is not a post?

An installed agent, a collector, a central check schedule, an SNMP profile, a hostname, and an installation identity are monitoring machinery. None of them is a second inventory object. A post may exist with no method attached at all, and a method does not create a post on its own.

The Watchpost Agent never creates a second inventory object. Pairing an agent associates it with exactly one selected or newly created post; the agent hostname, platform, installation identity, configuration, delivery state, and connection health are connection details shown beneath that post. A collector failure is not evidence that the post is healthy.

Why separate the post from its method?

Because the method is replaceable and the post is not. A machine may start with an agent, later gain a central HTTP check, and eventually move to a device adapter when one exists. The post, its ID, its rules, its history, its alerts, and its incidents survive every method change. If the post and the method were the same object, swapping a collector would destroy the operational memory of the system.

Two programs, one inventory

Watchpost and Watchpost Agent are separate binaries in separate repositories because they have different deployment locations, permissions, release lifecycles, and trust boundaries.

Watchpost

The central monitoring service and operational interface. It owns posts, observations, history, rules, alerts, incidents, evidence, users, and monitoring relationships.

Watchpost Agent

Separately installed software for a machine. It collects local telemetry, maintains a bounded delivery queue, and sends observations outbound to Watchpost.

Installing the Watchpost Agent does not create a second Watchpost server. A post does not require an agent: routers, UPS devices, websites, APIs, sensors, databases, cameras, and other devices may be monitored through other methods.

Watchpost repository - central service and operational interface.
Watchpost Agent repository - the separately installed collector.

Post examples

Choose the useful level of identity. A physical machine and an important service on it can be separate posts when they need separate ownership, rules, history, or incident context. Watchpost does not prescribe an uncontrolled post-per-process model.

Thing being monitored	Post example	Likely monitoring method
Linux server	`warehouse-api-01`	Watchpost Agent plus HTTP check
Website	`public-storefront`	HTTP, DNS and TLS checks
Router	`warehouse-router-01`	ICMP and SNMPv3
UPS	`rack-a-ups`	SNMPv3
Temperature sensor	`cold-room-sensor-02`	Device adapter or SNMP
Database service	`orders-postgres`	TCP check and future database integration

Post kinds

A post kind describes the expected capabilities and observations of a post. Kind is not the collector: selecting a kind declares intent and shapes the survey and rules, but it does not magically enable an unsupported collection path.

host or machine - a physical or virtual machine;
service or application - a named service on a machine;
HTTP endpoint - a website or API reachable over HTTP;
database - a database service;
network device - router, switch, or appliance;
power device - UPS or PDU;
sensor or environmental device - temperature, humidity, or similar;
storage appliance - a storage system;
other bounded device types - currently supported device categories beyond the list above.

Host, service, HTTP endpoint, network device, power device, environmental sensor, and storage appliance are implemented kinds today. Kinds beyond the currently supported set remain descriptive or future-facing: the collection path must exist before a kind is claimed as usable.

Monitoring methods

PostThe system, service, endpoint, or device the operator cares about.

Watchpost AgentLocal machine telemetry

Central checksHTTP, TCP, TLS, DNS, ICMP

SNMPv3 profilesRead-only device polling

Device adaptersFuture bounded protocols

Methods attach beneath the post. A post may use more than one at once.

A post may use more than one monitoring method. A Linux web server can run the agent for CPU, memory, load, and disk while a central HTTPS check measures external reachability. All methods feed the same canonical history, rule, alert, incident, and evidence model, so no method is a second-class citizen.

Create and connect a machine post

This walkthrough uses the separate Watchpost Agent. The local agent website is the friendly default; the CLI is the complete server-friendly surface for SSH, headless systems, automation, configuration management, and recovery. Both are peers over the same service.

Install Watchpost Agent on the machine. Installation creates the service, private state, bounded queue, local website, and CLI before any authority exists.
Open the loopback web interface, or use the equivalent CLI over SSH on a headless server.
Configure the local telemetry profile: enable CPU, memory, load, and uptime, choose up to eight filesystem paths, and set a bounded interval.
Enter the Watchpost URL and request pairing. The agent communicates outbound to Watchpost.
In Watchpost, approve the matching request by confirming the short human-verifiable phrase.
Select an existing post or create a new host post during approval. Pairing associates the agent with exactly one post.
Confirm the first telemetry batch appears for that post.
Open the post and review CPU, memory, load, filesystem, uptime, connection health, graphs, and the starter rules created during enrollment.

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

The local website performs the same steps with forms. See Agent architecture for installation, pairing, delivery, and local-management detail.

Addresses and connectivity

A post address is useful inventory and may be used by central checks or device adapters. It is not an inbound management endpoint for the agent.

The Watchpost Agent sends telemetry outbound to Watchpost; Watchpost does not normally connect inbound to the agent to collect machine metrics.
Entering a machine IP address therefore does not replace agent installation.
Another machine must never be configured to contact Watchpost through 127.0.0.1 - that loopback address belongs to the machine it runs on.
Remote access to the agent website is optional advanced functionality and must use the documented HTTPS, bootstrap-token, trusted-proxy, and client-network controls.

Lifecycle and identity

The durable post ID is stable and cannot be renamed because observations, rules, alerts, incidents, and evidence refer to it. Operators may edit display name, address, labels, ownership, and maintenance state freely.

CreateEnroll the post

ConnectAttach monitoring methods

ObserveCollect and evaluate

MaintainEdit, rotate, revoke

Archive / restorePreserve evidence

Permanently deleteRemove post and its evidence

Archive hides a post while preserving evidence; permanent deletion removes it and its post-scoped evidence.

Editing changes display name, address, labels, ownership, and maintenance state - never the ID.
Changing or adding monitoring methods attaches another collector while history continues to accumulate on the same post.
Replacing or rotating an agent connection issues a new post-scoped credential with overlap-and-confirm.
Revoking an agent removes its server authority without deleting the post.
Archiving and restoring hides or unhides the post while preserving its evidence.
Permanently deleting removes the post and its post-scoped evidence, requiring the exact post ID.
Uninstalling or resetting the remote agent is a machine-side operation that never silently changes central authority; deleting a post does not remotely uninstall an agent.

Archiving, deletion, revocation, reset, and uninstall are distinct operations so remote authority and retained evidence never change as a side effect.

Health and survey behaviour

Opening a post shows its current visual health, safe/warning/critical health bars with exact values, short trends and history, the active monitoring methods, agent or adapter connection health, freshness and quality, the rules and active alerts, maintenance state, and linked evidence and incidents. Unknown, missing, stale, partial, rejected, revoked, and never-connected states are shown explicitly and are never presented as healthy green.

See Collection for how observations enter, Rules and alerts for thresholds and freshness, Incidents for durable episodes, Agent architecture for agent delivery and health, Security model for authority boundaries, and Current limitations for what is not yet proven.