Skip to content
StatusOwlDocs

Installing Watch Owl on Linux

Add the StatusOwl APT or YUM repository, install watch-owl, and enroll a Linux server in under five minutes.

Last updated April 26, 2026

This guide walks through installing Watch Owl on a Linux server, enrolling it with your organization, and confirming metrics are flowing. Installs use StatusOwl's public package repository at packages.statusowl.net, so future versions arrive through the system's normal apt-get upgrade or dnf upgrade cycle.

Requirements

  • Linux amd64 with systemd (Debian 11+, Ubuntu 20.04+, Mint, Pop!_OS, RHEL/Rocky/Alma 8+, Fedora, CentOS Stream, or Oracle Linux).
  • Root or sudo access — the agent runs as a dedicated watch-owl system user.
  • Outbound HTTPS (443) to nest.statusowl.net (metrics) and packages.statusowl.net (initial install + upgrades). No inbound ports required.

Create an install token

  1. In the dashboard, go to System Monitor → Install and click Generate install token.
  2. Choose a token type:
    • One-time — single host, expires in 24 hours by default.
    • Reusable — for fleet rollouts. Set a max-uses count and optional expiry.
  3. Copy the token — it's shown once. It looks like a long opaque string starting with wo_.

Install tokens are sensitive

Anyone with an active install token can enroll a host into your organization. Paste it directly into the machine that's being enrolled — don't post it in chat or commit it to a repo. Revoke unused tokens from the same page.

Install — one-liner (recommended)

The fastest install. The script detects your distro family, adds the StatusOwl repository and GPG key, then installs the watch-owl package via your system's package manager:

text
curl -fsSL https://packages.statusowl.net/install.sh | sudo sh

Inspect the script first if you'd like — it's published verbatim at packages.statusowl.net/install.sh and makes no network calls outside of packages.statusowl.net.

Install — APT (Debian, Ubuntu, Mint, Pop!_OS, elementary)

If you prefer to add the repository manually:

text
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://packages.statusowl.net/statusowl.gpg \
  | sudo tee /etc/apt/keyrings/statusowl.gpg >/dev/null
sudo chmod 0644 /etc/apt/keyrings/statusowl.gpg

echo "deb [signed-by=/etc/apt/keyrings/statusowl.gpg] https://packages.statusowl.net/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/statusowl.list

sudo apt-get update
sudo apt-get install -y watch-owl

Install — DNF / YUM (RHEL, Fedora, Rocky, Alma, Oracle, CentOS Stream)

text
sudo tee /etc/yum.repos.d/statusowl.repo >/dev/null <<'EOF'
[statusowl]
name=StatusOwl Package Repository
baseurl=https://packages.statusowl.net/yum/stable
enabled=1
gpgcheck=1
gpgkey=https://packages.statusowl.net/statusowl.gpg
EOF

sudo dnf install -y watch-owl

The package installs the watch-owl binary, a watch-owl system user, a /etc/watch-owl/ config directory, and a watch-owl.service systemd unit. The service is not started yet — you enroll first.

Enroll the host

Run the enroll command as the watch-owl user, passing the install token. The agent trades the token for a long-lived host credential, writes it to /etc/watch-owl/credentials with 0600 permissions, and exits.

text
sudo -u watch-owl watch-owl enroll --token wo_xxxxxxxxxxxxxxxxxxxx

Then start the service:

text
sudo systemctl start watch-owl
sudo systemctl enable watch-owl   # start on boot

Unattended installs

For configuration management (Ansible, Terraform, cloud-init), pipe the install script and pass the token through an environment variable:

text
curl -fsSL https://packages.statusowl.net/install.sh | sudo sh
sudo -u watch-owl watch-owl enroll --token "$WATCH_OWL_ENROLL_TOKEN"
sudo systemctl enable --now watch-owl

A reusable install token lets you bake the same value into your fleet automation without rotating it per host.

Verify the install

text
# Service status
sudo systemctl status watch-owl

# Recent logs
sudo journalctl -u watch-owl -f

# Current agent info (host UUID, agent version, last metric push)
sudo -u watch-owl watch-owl status

Within 30 seconds, the host should appear in System Monitor → Hosts with a live heartbeat and a first set of CPU, memory, disk, and network charts.

Upgrades

Because watch-owl lives in your system package manager, future versions arrive via the normal upgrade path. No re-enrollment is needed — the credential file persists across upgrades.

text
# Debian / Ubuntu
sudo apt-get update && sudo apt-get install --only-upgrade watch-owl

# RHEL / Fedora / Rocky
sudo dnf upgrade watch-owl

The agent also has a built-in self-update channel for security patches between package releases — see the dashboard release notes.

Uninstall

Removing the package stops the service and cleans up the credential file. The host itself remains in the dashboard until you delete it there — this preserves historical metrics for compliance and post-incident review.

text
# Debian / Ubuntu
sudo apt-get remove watch-owl

# RHEL / Fedora / Rocky
sudo dnf remove watch-owl

To also remove the StatusOwl repository:

text
# APT
sudo rm /etc/apt/sources.list.d/statusowl.list /etc/apt/keyrings/statusowl.gpg

# DNF / YUM
sudo rm /etc/yum.repos.d/statusowl.repo

Troubleshooting

watch-owl enroll fails with "token already consumed" — One-time tokens can only be used once. Generate a new token from the dashboard, or use a reusable token for fleet installs.

Service starts but no host appears in dashboard — Check journalctl -u watch-owl for connection errors. The agent must be able to reach nest.statusowl.net:443 outbound.

apt-get install fails with NO_PUBKEY — The keyring path or signed-by= flag in /etc/apt/sources.list.d/statusowl.list is wrong. Re-run the keyring step from the APT install section above.

Wrong organization — If you enrolled into the wrong organization by accident, delete the host in System Monitor → Hosts, then re-enroll with a token from the correct organization.