Install the agent on a Linux server or VM

For a bare Linux machine — no Kubernetes, no Docker — the ObserveKit agent runs as a systemd service. Use this for EC2 and other cloud VMs, on-prem servers, and anything else where the workload is processes rather than containers.

If the machine runs Kubernetes, use Install on Kubernetes. If it runs containers under Docker, use Install on Docker.

Prerequisites

• systemd. Not optional — the agent's restart behaviour depends on it (see Restart behaviour).
• curl, sha256sum, and root access on the target machine.
• Outbound HTTPS from the machine to your ObserveKit server.

1. Create the source

Sources → + Add Source, choose Linux server / VM, give it a name (the hostname is a good default), and continue. The source row exists from this point on — you can close the wizard and finish the install later.

2. Run the install command

The wizard shows a single command:

curl -fsSL 'https://<your-observekit>/install/<token>' | sudo bash

Run it on the target machine as root. That is the whole procedure.

The installer refuses rather than half-completing: it stops if it is not root, if systemctl/curl/sha256sum are missing, or if it does not recognise the CPU architecture. It verifies the downloaded binary's checksum before installing it — a mismatch, or a missing checksum header, is a refusal rather than a fallback.

It then creates an unprivileged observekit system user, writes the API key to /etc/observekit/agent.env (mode 0600, the only place the key lives), writes a default /etc/observekit/agent.yaml, and enables the service.

3. Verify

systemctl status observekit-agent
journalctl -u observekit-agent -n 50

In the UI the source moves to CONNECTED once the agent heartbeats, and Infrastructure starts showing the machine.

What it collects

So a fresh install is not silent: host metrics and the journal start flowing immediately. What is missing is your *application's* log files, because nothing can guess where they are.

This differs from Kubernetes and Docker, where the agent discovers containers on its own. On a host, application log collection is opt-in: host metrics and the journal start immediately, but no application log file is tailed until you name it. See Agent configuration.

The permission model

The agent does not run as root. It reads logs through exactly two group memberships:

If either group does not exist on the machine, the installer says so and carries on, and the systemd unit is written naming only the groups that are actually present. That is deliberate: a missing systemd-journal group on a distribution with no journal should not abort an otherwise good install.

It also cannot be skipped. systemd refuses to start a unit that names a supplementary group it cannot resolve, so a unit hardcoding both groups on a host that has only one would produce a service that never starts — after an install that reported success.

What you get instead is a running agent that reads less: without adm it cannot open files written root:adm 0640, and without systemd-journal it cannot read the journal. The install is degraded, not broken, and the warning explaining why scrolled past at install time.

So if logs are missing, check this first:

id observekit          # must list adm and systemd-journal

To fix:

sudo usermod -a -G adm,systemd-journal observekit
sudo systemctl restart observekit-agent

The restart is required, not tidiness — a group change does not affect an already-running process.

Restart behaviour

The unit uses Restart=always, and that matters more than it looks. When you push a config from the UI, the agent applies it by writing the file and exiting cleanly. Under Restart=on-failure systemd would read that as a normal stop and leave the machine dark after a routine config change.

If you harden the unit, keep Restart=always, and keep both /var/lib/observekit and /etc/observekit writable — the agent needs the first for its buffer and checkpoints, and the second because a server-pushed config is written back to agent.yaml. Making /etc/observekit read-only causes the config push to fail with a permission error, which the UI reports as *"the agent rejected the configuration you pushed"* — sending you to look for a YAML mistake that does not exist.

Upgrade

Re-run the same install command. It replaces the binary and the unit and leaves `/etc/observekit/agent.yaml` alone, so your log_files survive.

Uninstall

sudo systemctl disable --now observekit-agent
sudo rm -f /usr/local/bin/observekit-agent /etc/systemd/system/observekit-agent.service
sudo systemctl daemon-reload
sudo rm -rf /etc/observekit /var/lib/observekit
sudo userdel observekit

Delete the source in the UI too — otherwise it shows as disconnected forever and will eventually fire a disconnect alert.

Not connecting?