jkunz
144dd224ca
- every coordinator request is bounded (30 s default, body included) - stop() cancels the pending poll delay and clears its timer - a failing `systemctl disable --now` fails the uninstall and keeps the unit file - license renamed to license.md; readme one-liners use curl -fsSL - install.sh and release.yml regenerated with @git.zone/cli 9.2.2 assets
@uptime.link/uptimerunner
uptime.link runner agent. It connects to an uptime.link instance, fetches assigned checks, executes them from the runner's network location, and reports results back.
It ships as a single executable (Node.js 26 single executable application) for Linux (x64, arm64;
glibc 2.28 or later with libstdc++6 and libatomic1), macOS (x64, arm64; 13.5 or later) and
Windows (x64). The executable trusts the operating system's CA store in addition to Node's bundled
CAs.
Install
As root:
curl -fsSL https://code.foss.global/uptime.link/uptimerunner/releases/download/latest/install.sh | sudo bash
The installer is an asset of every release from 1.0.1 on. It downloads the executable of the
newest release for the host's platform, verifies it against the release's SHA256SUMS.txt, and
runs it with --version before it changes anything. It installs to
/opt/uptimerunner/uptimerunner and links /usr/local/bin/uptimerunner. Pass
--version vX.Y.Z for a given release or --install-dir <dir> for another directory:
curl -fsSL https://code.foss.global/uptime.link/uptimerunner/releases/download/latest/install.sh | sudo bash -s -- --version vX.Y.Z
Running it again updates the runner: a running uptimerunner service is restarted with the new
version, and when any step fails the previous installation and service are restored. The config in
/etc/uptimerunner is not touched. The installer needs curl and sha256sum or shasum.
On Linux the executable needs libstdc++6 and libatomic1 (Debian and Ubuntu:
apt-get install libstdc++6 libatomic1); without libatomic.so.1 it exits with 127 and the
installer stops before it changes anything.
Every release also carries the executables, their third-party notices and SHA256SUMS.txt as
assets for a manual download:
https://code.foss.global/uptime.link/uptimerunner/releases/download/<version>/uptimerunner-<os>-<arch>
with <os> one of linux, macos, windows and <arch> x64 or arm64 (Windows: x64 only,
uptimerunner-windows-x64.exe).
Configure
sudo uptimerunner config write \
--url https://uptime.link \
--runner-id edge-1 \
--token <runner-token>
The config is written to /etc/uptimerunner/config.json (or UPTIMERUNNER_CONFIG) with mode 0600.
UPTIMERUNNER_INSTANCE_URL, UPTIMERUNNER_RUNNER_ID, UPTIMERUNNER_TOKEN, UPTIMERUNNER_LABELS,
UPTIMERUNNER_POLL_INTERVAL_MS and UPTIMERUNNER_MAX_CONCURRENT_CHECKS override its values.
Run
uptimerunner run
For systemd:
sudo uptimerunner service install
sudo uptimerunner service start
Runner Protocol
The runner polls:
GET /api/runner/v1/checks?runnerId=<runnerId>
The uptime.link instance returns:
{
"checks": [
{
"id": "api-health",
"type": "http",
"plannedTime": 1760000000000,
"url": "https://api.example.com/health",
"expectedStatusCodes": [200],
"expectedBodyIncludes": "ok"
}
]
}
The runner reports:
POST /api/runner/v1/results
Supported check types:
httptcpassumption
Results report ok, not ok or timed out, and their timing echoes the job's plannedTime. The
request and response shapes are the data types of
@uptime.link/interfaces.
Development
pnpm install --frozen-lockfile
pnpm build # type-check and compile to dist_ts/
pnpm test # tstest
pnpm run build:binary # tsbundle + tssea: all executables in dist/binaries/
pnpm run dev --help # run from source
Issue Reporting and Security
For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.