Copy page

Servers

Install the agent

The Spectate agent (spectate-agent) sends the metrics of a server to Spectate. You install it with one command from the dashboard. The command contains an install token that registers the server as a host in your team.

Owners, managers and admins can add hosts. Your team must have room for one more monitor or host on its plan. See plan limits.

Before you start

• A Linux server with systemd, on amd64 or arm64, or a Mac. See supported systems.
• Root access with sudo.
• curl on the server.
• Outbound HTTPS (port 443) to the hosts in network requirements.

Install on Linux

1. In the dashboard, go to Hosts.
2. Select Add host.
3. Under Choose platform, select your Linux distribution.
4. Under Run the installer, copy the command. If there is no command, select Generate install command.
5. Run the command on the server.
6. Wait for the host to appear under Wait for the first report.

The dashboard checks for new hosts every 5 seconds. A new host appears as soon as the agent registers it.

The command looks like this:

Code
curl -fsSL https://get.spectate.net/agent.sh | sudo sh -s -- --token YOUR_INSTALL_TOKEN

The installer does these steps:

1. It downloads the newest agent release from GitHub and checks it against the release's checksums.
2. It creates the system user spectate-agent. The agent runs as this user, not as root.
3. It writes /etc/spectate-agent/agent.env.
4. It registers the host. The host token goes to /var/lib/spectate-agent/state.json, which only the agent user can read.
5. It installs and starts the systemd service spectate-agent.service.
6. If the server has apt, dnf or yum, it adds an hourly timer that counts pending updates. The timer never installs updates.

To install on many servers, run the same command on each server. One install token registers any number of hosts until it expires.

Install on macOS

The agent on macOS is best effort. It runs as a launchd agent of your user and starts when you log in.

1. In the dashboard, go to Hosts.
2. Select Add host.
3. Under Choose platform, select macOS.
4. Under Processor, select Apple silicon or Intel.
5. Copy the command under Run the installer.
6. Run the command in Terminal, as the user that the agent must run as.

The command downloads the agent binary and checks it against checksums.txt of the release. Then it installs the binary in /usr/local/bin and registers the host. Last, it loads the launchd agent. The log file is ~/Library/Logs/spectate-agent.log.

Install tokens

An install token lets the agent register a host in your team. Install tokens start with hct_.

• A token is valid for 7 days.
• One token can register any number of hosts until it expires or you revoke it.
• Add host uses an existing token if it is valid for at least one more hour. If not, select Generate install command to create a new token.
• The Install tokens panel on the Hosts page lists the active tokens. Select Revoke to stop a token.

Revoking an install token does not affect hosts that registered with it. Each host has its own host token.

You can also create install tokens with the public API.

Move a host from the v1 agent

If a server runs the legacy v1 agent (spectated), replace it with the v2 agent. The host keeps its identity and history. You do not need an install token.

Run this command on the Linux server:

Code
curl -fsSL https://get.spectate.net/agent.sh | sudo sh -s -- --import-legacy

The installer reads the host token from /etc/spectated/config.yaml, installs the v2 agent and removes spectated. The dashboard also shows this command under Add host and on the Integrations page.

Check the agent

Use these commands on the server:

doctor does not send metrics. It does not mark the host as reporting, so it does not resolve a "Host stops reporting" alert.

Update the agent

The host page shows when a newer agent release is available. The agent also writes a message to its log once a day.

Code
sudo spectate-agent update --check   # show the current and the newest version
sudo spectate-agent update           # install the newest release and restart the service
sudo spectate-agent update --version 2.1.0   # install a specific release

update installs only stable v2.x.y releases. It checks the signature of the release before it replaces the binary. On macOS, update shows the launchctl commands to run instead of a restart.

To update automatically on Linux, add --auto-update to the install command. The installer then adds a daily timer that runs spectate-agent update --if-newer.

Remove the agent

On Linux, run:

Code
sudo spectate-agent uninstall

This removes the service and the update timer. The agent keeps its state in /var/lib/spectate-agent.

On macOS, run spectate-agent uninstall as your user, without sudo. Then remove the binary with sudo rm /usr/local/bin/spectate-agent.

Removing the agent does not delete the host in Spectate. To delete the host, open it and go to Settings & alerts. Under Danger zone, select Delete host and type the host's label to confirm.

When you delete a host, it no longer shows in the dashboard or the API. After 7 days, Spectate permanently deletes the host with its metrics and alerts. In the first 7 days, Spectate support can restore the host. Send an email to help@spectate.net.

If you delete a host while its agent still runs, the agent stops at its next report. It logs This host was removed from Spectate and does not start again. To add the server again, run sudo spectate-agent uninstall and sudo rm -rf /var/lib/spectate-agent. Then run the install command again. The installer keeps an existing registration, so you must remove the old state first.

Network requirements

The agent connects out over HTTPS on port 443. Spectate never connects to your server.

If the agent cannot reach api.spectate.net, it keeps the metrics on disk for up to 24 hours, at most 50 MB. It sends them when the connection comes back.

Settings on the server

The agent reads a few local settings from /etc/spectate-agent/agent.env:

Spectate sets everything else, such as the intervals and the collectors. Change the collectors on the host page under Settings & alerts → Collection. See metrics.

Installer options