# 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](/hosts/introduction#plan-limits).

## Before you start

- A Linux server with systemd, on amd64 or arm64, or a Mac. See [supported systems](/hosts/introduction#supported-systems).
- Root access with `sudo`.
- `curl` on the server.
- Outbound HTTPS (port 443) to the hosts in [network requirements](#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:

```bash
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](/api-reference/host-install-tokens).

## 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:

```bash
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:

| Command | What it shows |
|---|---|
| `sudo spectate-agent doctor` | Checks the registration, the API connection and token, the clock, the disk buffer, the service, the collectors and the package check. It exits with an error code if a check fails. |
| `spectate-agent status` | The state of the agent, including an available update or a deleted host. Add `--json` for JSON output. |
| `spectate-agent collect --once` | What each collector reports on this server. It sends nothing to Spectate. |
| `spectate-agent config show` | The settings that the agent received from Spectate. |
| `spectate-agent version` | The agent version. |

`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.

```bash
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:

```bash
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](mailto: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.

| Host | Used by | Why |
|---|---|---|
| `api.spectate.net` | The agent | Registration and metrics |
| `get.spectate.net` | The installer | The install script |
| `github.com`, `objects.githubusercontent.com`, `release-assets.githubusercontent.com` | The installer and `update` | Agent releases |
| `api.github.com` | `update` | The list of releases |

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`:

| Variable | Default |
|---|---|
| `SPECTATE_API_URL` | `https://api.spectate.net` |
| `SPECTATE_STATE_DIR` | `/var/lib/spectate-agent` |
| `SPECTATE_SPOOL_MAX_MB` | `50` |
| `SPECTATE_SPOOL_MAX_AGE` | `24h` |
| `SPECTATE_LOG_LEVEL` | `info` |

Spectate sets everything else, such as the intervals and the collectors. Change the collectors on the host page under **Settings & alerts → Collection**. See [metrics](/hosts/metrics#collectors).

## Installer options

| Option | What it does |
|---|---|
| `--token TOKEN` | The install token. You can also set `SPECTATE_INSTALL_TOKEN`. |
| `--import-legacy` | Moves a host from the v1 agent and keeps its token. |
| `--upgrade` | Replaces the binary and restarts the service. |
| `--auto-update` | Adds a daily update timer. Linux only. |
| `--version VERSION` | Installs a specific release, for example `2.1.0`. |
| `--api-url URL` | Uses another API address. |