The server agent

What the machine needs

• Linux with systemd: Ubuntu 20.04 or newer, Debian 11 or newer, and the same era of anything else.
• amd64 or arm64. The installer works out which and stops if it is neither.
• Outbound HTTPS to api.serverinspector.com. No inbound rule, no open port.
• Root for the install itself, to create a user and a unit. The agent then runs as that user.
• Docker is optional. Without it everything else still reports.

Add the server in Servers. You get a command with a token already in it. Run it on the machine:

curl -fsSL https://serverinspector.com/install.sh | sudo sh -s -- --token si_srv_YOUR_TOKEN

The token is shown once and identifies exactly one machine. If you lose it, issue a new one from the server's page; the old one stops working the moment you do.

What the script does, in order

1. Works out the architecture and downloads the matching binary.
2. Checks its SHA-256 against the published SHA256SUMS and stops if they differ.
3. Creates the serverinspector system user, in docker, systemd-journal and adm.
4. Writes the token to /etc/serverinspector-agent.env, readable only by that user.
5. Writes /etc/systemd/system/si-agent.service and starts it.

If you would rather not pipe a script into a shell

Nobody should have to, and it is the same file either way:

curl -fsSL https://serverinspector.com/install.sh -o si-install.sh
less si-install.sh                      # sixty lines, read them
sudo sh si-install.sh --token si_srv_YOUR_TOKEN

The binaries and their checksums sit beside it, if you want to fetch one by hand: serverinspector.com/agent/v1.0.0/.

If you work with an AI assistant that can reach the machine, give it this. It tells the assistant what to check before it runs anything, what not to touch, and how to prove the agent is reporting afterwards.

Install the ServerInspector agent on a Linux server I own.

Server: <how you reach it, e.g. ssh deploy@198.51.100.10>
Token:  <the si_srv_ token from the Servers page>

Treat the token as a secret: do not print it, do not echo it, and do not
repeat it back to me.

Do exactly these steps and nothing else:

1. Check the machine is Linux with systemd, on amd64 or arm64, Ubuntu 20.04+
   or Debian 11+. If it is not, stop and tell me.
2. Download the installer and read it before running it:
     curl -fsSL https://serverinspector.com/install.sh -o /tmp/si-install.sh
   Confirm it creates an unprivileged user, verifies a SHA-256 checksum
   against a published list, and writes one systemd unit. If it does anything
   beyond that, stop and tell me what it does.
3. Run it as root, passing my token:
     sudo sh /tmp/si-install.sh --token "<token>"
4. Delete /tmp/si-install.sh.
5. Prove it works:
     systemctl is-active si-agent
     journalctl -u si-agent -n 20 --no-pager
   It reports every 60 seconds. Wait two minutes and check the log again.
6. Report back: the hostname, whether the unit is active, and any line in the
   log that is not an ordinary start.

Do not open any port, change any firewall rule, install any other package, or
restart any other service. The agent needs outbound HTTPS to
api.serverinspector.com and nothing inbound. If a step fails, stop and tell me
what happened rather than working around it.

Replace the two lines at the top. Keep the token out of the conversation if you can: paste it into the machine yourself and tell the assistant it is already in /tmp/si-token, or hand it over and rotate it afterwards from the server's page.

Memory is reported from MemAvailable, the kernel's own answer to how much a new process could have, rather than free memory, which makes a healthy machine look full. Disk is reported per mount and the fullest one is the one we warn about: a root filesystem with room and a data volume at 97% is a machine about to stop, and an average across the two would hide it.

If the machine runs fail2ban, the agent reads /var/log/fail2ban.log, which is root:adm and therefore readable by the unprivileged user the agent already runs as. No new permission, nothing executed.

The server's page then lists what was blocked, which rule caught it, how many attempts it made and whether it has come back before. A machine without fail2ban reports nothing here and is not nagged about it.

Visitors are counted, attackers are named

Everywhere else the agent cuts an address to its network before sending it: a /24 for IPv4, a /48 for IPv6, so no visitor's address ever leaves the machine. A banned address is the one exception and is sent whole, because a ban list that will not say which address was blocked cannot be checked against another machine, looked up, or handed to anyone.

We do not block anything and cannot lift a ban. The agent has no path to act on the machine, and this page is the view of a decision your own machine made.

The country beside an address comes from IP Geolocation by DB-IP (CC BY 4.0), looked up on our side rather than on your machine. It names a country, not a person or a place, and is wrong often enough that it is worth treating as a hint.

• It opens no inbound port. It dials out, and nothing dials in.
• It executes nothing. The reply to a report carries an interval, a collection setting and a version number, and there is no code path that would run anything else.
• It is not root. It runs as its own user and refuses to start as root without an explicit flag.
• It scrubs before it sends. Anything that looks like a password, a key, a token or an email address is removed from command lines on the machine, before the report leaves it.

The systemd unit says the same thing to the kernel: NoNewPrivileges, ProtectSystem=strict, ProtectHome, PrivateTmp, with memory capped at 128 MB and CPU at 10% of one core.

systemctl status si-agent      # is it running
journalctl -u si-agent -f      # what it is saying
systemctl restart si-agent     # after changing the token
si-agent --once --root /       # collect once, print it, send nothing
si-agent --version

The token lives in /etc/serverinspector-agent.env. To move a machine to a new token, issue one on the server's page, replace the value and restart.

Removing it

curl -fsSL https://serverinspector.com/install.sh | sudo sh -s -- --uninstall

That stops and removes the unit and the binary. The system user is left in place; delete it with userdel serverinspector if you want it gone.

The server's page waits for the first report and updates itself when it arrives. If it does not, the agent usually says why:

journalctl -u si-agent -n 50 --no-pager

• The token was refused. The server was removed, or its token was rotated. Issue a new one and replace the value in the env file.
• Nothing in the log and no reports. Check the machine can reach api.serverinspector.com on 443 outbound. The agent needs no inbound rule at all.
• Docker shows as absent although it is installed. The agent's user is not in the docker group yet. Add it and restart the unit.
• It refuses to start as root. That is deliberate. Use the installer, which creates the right user.

Does it need root?

No. The installer creates a serverinspector system user and puts it in the docker, systemd-journal and adm groups, which is everything the agent reads. The binary refuses to start as root unless you pass --allow-root. Nothing it does needs the privilege.

Can it run a command on my machine?

No, and not as a setting either. The only thing our server can say in reply to a report is how often to report, what to collect and which version exists. There is no code path that executes anything, no inbound port and no remote shell. A stolen token buys somebody a view of your load average.

What does it cost the machine?

One reading of /proc a minute and one HTTPS request of about 10 KB. The unit caps it at 128 MB of memory and 10% of one core, and it has never come close in our own use.

What if the agent stops, or the machine dies?

After three missed reports we say we have lost contact with that server, through the channels you already use. We say contact was lost rather than that the machine is down, because from outside those look identical and claiming the stronger one is how alerts stop being believed.

Which machines does it run on?

Linux with systemd, amd64 or arm64. Ubuntu 20.04 and newer and Debian 11 and newer are what we test; the binary is static, so Alpine and older glibc work too. Docker is optional. There is no Windows or macOS agent.

What happens to the data?

A row of numbers a minute, kept for as long as your plan keeps history, with minutes becoming hourly averages after two days. Command lines are truncated and scrubbed of anything that looks like a credential before they leave the machine.