Install the agent

Before you start

• Linux with systemd, on amd64 or arm64. Debian, Ubuntu, RHEL, Rocky, Alma and Fedora all qualify.
• Root, to create a system user and install a unit file.
• curl and openssl. Most servers have both; a minimal container image often has neither. The installer stops and tells you if one is missing rather than skipping the signature check.
• Outbound HTTPS to https://dev-api.uptimecraft.com and to https://get.uptimecraft.com/agent.

macOS and Windows are not supported. There is no installer for them, and you should not treat the macOS builds as a supported platform.

1. Create an enrollment token

Go to Settings → Servers and choose Create token.

The token is shown once. We store only a hash of it, so if you lose it, revoke it and make another.

2. Run the installer

The page shows the command with your token already in it. It looks like this:

curl -fsSL https://dev.uptimecraft.com/install.sh \
  | UPTIMECRAFT_ENROLLMENT_TOKEN=uc_enroll_... sh

Run it as root on the server you want to monitor.

What the installer actually does

Piping a script to a shell deserves scrutiny, so here is every step:

1. Works out whether you are on amd64 or arm64 and stops if you are on neither.
2. Checks you have curl, openssl, systemd and a token, before downloading anything — a machine that cannot be installed on is left exactly as it was.
3. Downloads the matching build, the checksum file, and our signature over that checksum file.
4. Verifies the signature using a public key carried inside the script itself. If it does not match, nothing is installed.
5. Verifies the checksum. If it does not match, nothing is installed.
6. Creates the uptimecraft system user, with no home directory and no login shell.
7. Installs the binary to /usr/local/bin/uptimecraft-agent, the unit file, and your token to /etc/uptimecraft/agent.env — mode 0640, readable by that user and root and nobody else.
8. Starts the service, which enrols itself.

Both verification steps matter, and they catch different things. The checksum proves the download arrived intact. The signature proves the checksum file is ours — without it, anyone who could replace the download could replace the checksum beside it and the two would agree with each other all the way onto your server. There is no way to skip either check.

You can verify the same things by hand:

openssl dgst -sha256 -verify release.pub -signature SHA256SUMS.sig SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing

3. Confirm it is reporting

The server appears in Settings → Servers within about one reporting interval, marked Active. Click it to see what it is collecting.

On the machine:

systemctl status uptimecraft-agent
journalctl -u uptimecraft-agent -f

A healthy agent logs that it enrolled, then what it is collecting. Checks appear in the dashboard as soon as the agent says it can perform them — the first numbers follow a minute later, because a minute has to finish before it can be summarised.

It is safe to run again

Enrolment is keyed on the machine, not the request. Running the installer twice, or running it on every converge from Ansible, resolves to the same server rather than creating a second one. That is deliberate: an installer you cannot re-run is an installer you cannot put in configuration management.

Installing on many servers at once

Create one token with Maximum uses left empty or set to the number of machines, then use it in whatever already provisions them.

The one thing to get right: enrol on first boot, not when you bake the image. A machine that enrolled before being cloned shares its identity with every copy, and each copy will be held for approval instead of monitored. Bake the binary if you like; let the first boot do the enrolling.

If it does not appear

• Nothing in Settings → Servers. Check journalctl -u uptimecraft-agent. The usual causes are an expired or used-up token, or outbound HTTPS being blocked.
• "openssl is required". Install it; the installer will not proceed without being able to check the signature.
• Marked "Pending approval". Another machine is already reporting with the same identity — almost always a clone or a restored image. Approve it on the Servers page if it really is a separate server.
• Checks say "Not collected". The agent is running but cannot perform that check. The page says why: either the check needs a newer agent, or it is not collected on this platform.