Installing the agent

What the server needs#

• Ubuntu or Debian, on x86-64 or ARM64, with systemd and apt.
• A login that can use sudo. The installer needs root to add a user, a service and a sudoers file.
• Outbound HTTPS (port 443) to WellKept. The agent opens no port and listens for nothing. If the server sits behind a proxy, the agent honours HTTPS_PROXY set in the service's environment.

The command#

Add a server in the dashboard shows a command like this one, with your own one-time token in it:

curl -fsSL https://wellkept.fullwerks.co.uk/install.sh | sudo bash -s -- --token wk_enrol_…

The token starts with wk_enrol_, works once and expires after an hour. It is shown only when you create it, so copy it then. An unused command can be revoked from the same page.

What the installer does#

In this order:

1. Downloads the release for your architecture and verifies its SHA-256 checksum and its Ed25519 signature before anything runs. The signature check needs OpenSSL 1.1.1 or newer. On an older OpenSSL the installer says so and relies on the checksum, which it fetched over TLS.
2. Creates the wellkept system user, with no shell, no password and no home directory of its own.
3. Installs the binary at /usr/local/bin/wellkept-agent, the configuration in /etc/wellkept/, the token in /var/lib/wellkept/ and the agent's private package lists in /var/cache/wellkept/.
4. Installs /etc/sudoers.d/wellkept, a four-line allowlist, after checking it with visudo -c. What the agent reads explains each line.
5. Exchanges the one-time token for this server's permanent token. The permanent token is never shown in the dashboard.
6. Installs and starts wellkept-agent.service.

The server appears in your list as soon as step 5 finishes, and shows as online after its first heartbeat.

Options#

Pass these after -- on the command line.

Option	What it does
--auto-update	Enable the daily self-update timer. Off by default.
--re-enrol	Enrol again as a new server.
--no-start	Install everything but do not start the service.
--api-url URL	Talk to another API, for development.
--binary PATH	Install a local build instead of a release. Nothing is verified. For testing only.

The token can also be passed as WELLKEPT_ENROL_TOKEN in the environment instead of --token. Running the installer again upgrades the binary and keeps the enrolment.

Check that it works#

systemctl status wellkept-agent
journalctl -u wellkept-agent -f

To see exactly what would be sent, without sending it:

sudo -u wellkept wellkept-agent collect

Sites under a home directory#

The agent runs as an unprivileged user, so a site under a directory it cannot enter is reported from its web server configuration, with no version. To get WordPress and Laravel versions for sites under /home/<user>, add the wellkept user to that user's group, or make the home directory traversable. These are the same two fixes your web server needed.

sudo usermod -aG deploy wellkept
# or
sudo chmod o+x /home/deploy

Restart the service afterwards: sudo systemctl restart wellkept-agent.

Uninstall#

curl -fsSL https://wellkept.fullwerks.co.uk/uninstall.sh | sudo bash

This removes the service and its timer, the sudoers file, the binary, the token, the cache and the user. To keep /etc/wellkept, add -s -- --keep-config after bash. Remove the server in the dashboard as well, or it shows as offline.