# Install the server agent, step by step

> This walks through installing the InfraNest agent on one server, from getting a token to seeing the numbers arrive. It takes about two minutes per server.

Source: https://infranest.io/docs/install-the-agent-step-by-step
Last updated: 2026-09-19

---

Install the InfraNest agent on a server to get memory, disk space and load data. This is for anyone setting up monitoring on a server they manage, and takes about two minutes per server.

> [!NOTE]
> Want to know why you'd install it and what it collects first? Read **Get memory, disk space and load with the agent** — this article assumes you've already decided to go ahead.

## Overview

- The agent is a small program you install once on the server itself, using a one-time token from InfraNest.
- It only sends data out over the internet on port 443 — nothing needs to be opened *to* the server, and no firewall rule has to change.
- Once it's running, the server's memory, disk space and load numbers start appearing in InfraNest, and alert rules that needed the agent become available.

## Before you start

You need three things:

- **A server in InfraNest.** If it isn't there yet, add it under **Infrastructure → Servers**.
- **Administrator access to that server** — `sudo` on Linux, an Administrator PowerShell on Windows. You need it once, to install. The agent itself does not run as an administrator afterwards.
- **The server can reach the internet on port 443.** Outbound only.

You do not need to open a port, install a package manager repository, or give InfraNest any other access to the machine.

## Get the install command

1. Choose **Install the agent** — you'll find this from the server's row in **Monitoring → Servers**, from the server's actions menu, or beside an alert rule that's greyed out because it needs the agent. All three open the same window.
2. Nothing is asked for: the token is created straight away. In the token list afterwards, each one is identified by who added it, when, and when it was last used.
3. The token is shown **once**. Below it is a ready-made install command with the token already filled in.
4. Pick the tab for your system and copy the command.

<!-- screenshot: install-the-agent-step-by-step -->

<!-- docs-screenshots:start:install-the-agent-step-by-step -->

![Install the server agent, step by step](/media/b1921b2b-3617-4266-9d59-61b9ba04983d)

<!-- docs-screenshots:end:install-the-agent-step-by-step -->

> [!WARNING]
> Keep the token to one server. It identifies which server is reporting. If two machines share a token, they write into one set of graphs and nothing detects it — the numbers blend together, and the "server has gone quiet" alert can never fire, because whichever machine is still up keeps checking in for both.

## Run the install command

### Ubuntu and Debian

Paste the command into a terminal on that server. It looks like this:

```sh
curl -fsSL https://github.com/InfraNest-Infrastructure-Organized/infranest-agent/releases/latest/download/install.sh \
  | sudo sh -s -- --token sat_YOUR_TOKEN
```

Tested on Ubuntu 20.04, 22.04 and 24.04, and Debian 11 and 12.

### RHEL, Rocky, AlmaLinux, CentOS Stream, Fedora

Exactly the same command. The installer downloads a single binary and writes a systemd service; it does not use a package manager, so the distribution does not matter as long as it uses systemd.

If `curl` is missing, install it first with `sudo dnf install curl`.

### Windows Server

Open PowerShell as Administrator and run:

```powershell
irm https://github.com/InfraNest-Infrastructure-Organized/infranest-agent/releases/latest/download/install.ps1 -OutFile install.ps1
.\install.ps1 -Token sat_YOUR_TOKEN
```

Tested on Windows Server 2019 and 2022. It installs to `C:\Program Files\InfraNest` and runs as a scheduled task named **InfraNest agent**.

### A server without systemd

Alpine, a container, or anything using OpenRC or runit: the installer places the binary and the config file, then tells you it could not set up a service. Run `infranest-agent run` under whatever supervisor that system uses. The agent expects to be kept running; it is not a one-off job.

## Check it worked

1. **In InfraNest:** wait about a minute and reload the server's page. Memory, disk space and load average start filling in, the coverage badge changes to **Agent**, and previously greyed-out alert rules become available.
2. **On the server**, if you'd rather check locally, run:

```sh
sudo infranest-agent status
```

```powershell
& "C:\Program Files\InfraNest\infranest-agent.exe" status
```

It tells you whether readings are being delivered and, if not, why not. It answers using only what's on the machine and contacts nothing else.

> [!NOTE]
> `sudo` is needed because the config file holds a credential and is readable only by the agent's own user. Without it you'll get an error about a missing token rather than about permissions.

## Read the script before running it

If you'd rather review the script first, the install panel offers this path with the same prominence as the one-liner:

```sh
curl -fsSLO https://github.com/InfraNest-Infrastructure-Organized/infranest-agent/releases/latest/download/install.sh
sha256sum install.sh        # compare with the checksum shown in InfraNest
less install.sh             # about 200 lines
sudo sh install.sh --token sat_YOUR_TOKEN
```

The checksum shown next to the command in InfraNest is the one published with the release, so comparing them is a real check. The script itself isn't the agent — it downloads a versioned binary and verifies that against its own published checksum before installing it.

## Keep the token out of your shell history

A command line ends up in your shell history and is visible while it runs. On a shared machine, use a token file instead:

```sh
printf '%s' 'sat_YOUR_TOKEN' | sudo tee /root/token >/dev/null
sudo sh install.sh --token-file /root/token && sudo shred -u /root/token
```

## Update the agent

1. Run the same install command again. It replaces the binary and keeps your config and token.

InfraNest tells you when an update is available: the server's **System** card shows the agent version, and the fleet table marks servers running an older one.

## Remove the agent

1. Run the uninstall command for your system:

```sh
sudo sh install.sh --uninstall
```

```powershell
.\install.ps1 -Uninstall
```

That removes the service, the user, the binary, the config and the stored readings.

> [!WARNING]
> Deleting the token in InfraNest does not uninstall anything — it just stops the readings being accepted. The agent keeps running and retrying on the machine until you remove it there.

## Troubleshooting

| What you see | What it means |
|---|---|
| `curl: (60) SSL certificate problem` | The server's CA certificates are out of date. Install `ca-certificates` and retry. |
| Install finishes, but nothing appears in InfraNest | Give it 90 seconds, then run `sudo infranest-agent status` — it names the reason. |
| `status` says the token was rejected | The token was deleted in InfraNest, or was copied from a different server. Create a new one on the right server and reinstall. |
| `status` says monitoring is switched off | Monitoring is deactivated for that server in InfraNest. Turn it back on there — nothing needs doing on the machine. |
| `status` says the clock is off | The server's time is wrong, so readings from the future are refused. Turning on automatic time sync fixes it on most systems. |
| Memory and disk arrive, processes do not | Process reporting is off by default, on purpose — command lines often contain passwords. See the note on the server's **Processes & services** tab for how to turn it on. |
| Nothing at all, and `status` cannot read the config | Run it with `sudo`. The config is readable only by the agent's user. |

If none of those fit, run:

```sh
sudo infranest-agent flare
```

It prints everything a support conversation needs — version, configuration, state, what could not be read — with the token removed. Paste that into a support ticket rather than your config file.