Install the server agent, step by step

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.

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

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

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:

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:

sudo infranest-agent status

& "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.

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

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:

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:

sudo sh install.sh --uninstall

.\install.ps1 -Uninstall

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

WarningDeleting 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

If none of those fit, run:

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.