Docs · Start

Getting started

Build one binary, start one local service, create the first administrator, and enroll the first thing you want to monitor—a post.

Install Watchpost

curl -fsSL https://watchpost.cv/install.sh | sh

Use download.sh for a portable verified binary and update.sh for an installed binary with rollback support. Machine-wide installation uses sudo sh -s -- --system and delegates service ownership to the Watchpost CLI.

Install with Go

go install github.com/watchpost-cv/watchpost/cmd/watchpost@latest

This builds Watchpost from source using Go 1.25 or newer and installs it to your configured Go binary directory. Use the release installer when you prefer the published, checksum-verified binary.

Install Watchpost Agent

curl -fsSL https://watchpost.cv/agent-install.sh | sh

The Agent currently supports Linux amd64 and arm64. Install it before pairing it with a post.

Compile Watchpost

Watchpost requires the Go toolchain. From the application repository:

go build -o watchpost ./cmd/watchpost
./watchpost

The default listener is 127.0.0.1:7334. For development you can skip the retained binary:

go run ./cmd/watchpost

The early ./watchpost serve form remains accepted for compatibility, but the subcommand is not required.

Choose the data directory and listener

./watchpost --host 127.0.0.1 --port 7404 --data-dir ./watchpost-data

The canonical listener form is --host/--port, with WATCHPOST_HOST/WATCHPOST_PORT and the defaults applying below them (CLI > environment > default; ports must be 1–65535 and values are trimmed). The legacy single-address --listen flag and WATCHPOST_LISTEN environment remain supported and cannot be combined with the explicit host/port form. --data-dir overrides WATCHPOST_DATA_DIR. Watchpost creates and migrates its SQLite database inside the data directory.

Complete first-run setup

1. Open the local address in a browser.
2. Create the first administrator with a valid email and a password of at least seven characters. Sign in with that email and password; identities are normalized so case differences do not matter.
3. Sign in. Setup and sign-in are deliberately separate and are never shown together.
4. Use Enroll a post to add a host, endpoint, network device, power device, sensor, or storage appliance. The Posts page explains what a post is, the post kinds, and the monitoring methods that can be attached to it.
5. Use Run a check or SNMP devices to verify connectivity.

Setup over a loopback listener is direct. If Watchpost is reachable beyond the loopback interface — or an operator set WATCHPOST_SETUP_TOKEN or WATCHPOST_SETUP_TOKEN_FILE — the first-run form asks for a short-lived bootstrap token printed once to the server console. The token is consumed atomically with the first administrator's creation, only its hash is stored, and it is never returned by any API.

A first HTTP example

Enroll website-production as an HTTP endpoint, then run an HTTP check against https://example.com/health. A successful response records immediate health and latency in the result panel. Scheduled checks and rule evaluation build on the same post identity.

Continue with core concepts, then see collection for the available monitoring paths.