One panel, many machines

One SentrAI server can watch other machines too. That server becomes the panel: it scores every machine on its own, decides on blocks and shows them all on its dashboard. Each other machine runs only the small agent, which sends that machine’s logs to the panel and puts the panel’s blocks for it into its own firewall.

The agent only makes outgoing HTTPS calls to the panel, so no port is opened on the machines you add. Each machine gets its own key, so removing one never touches the others.

The examples use panel.example.com for the panel’s name and 203.0.113.10 for your own computer’s IP. Put your real ones in their place.

1. Install the panel

Install SentrAI on the server that will be the panel as in Install on a server, and add --panel:

git clone https://github.com/RexGuard/SentrAI && cd SentrAI/mvp
sudo ./deploy/install.sh --protect 203.0.113.10 --admin-email you@example.com --panel

Already installed? Run sudo ./deploy/install.sh --panel on its own; your settings are kept.

--panel does three things:

• opens a second port, 8443, for agents only. It uses HTTPS with a certificate the installer makes, and answers only what a machine key may do. Your API token and the dashboard never face the network through it.
• scores each machine on its own (SENTRAI_RISK_SCOPE=host), so an attack on one machine never blocks traffic on another.
• prints the address agents will use and the certificate’s pin (sha256:...). You don’t need to copy it: the dashboard shows it with every join code.

If the server’s own name is not what other machines use to reach it, give the address yourself:

sudo ./deploy/install.sh --panel 8443 --panel-url https://panel.example.com:8443

When the panel only watches other machines, keep its own firewall out of it: add SENTRAI_FIREWALL=off to /etc/sentrai/sentrai.env and run sudo systemctl restart sentrai.target.

The installer opens 8443 in ufw or firewalld when either is running. If your cloud provider has its own firewall, allow 8443 there too, ideally only from the machines you add. sudo ./deploy/install.sh --panel off closes the port again.

2. Make a join code

On the panel’s dashboard, open Machines. In Add machine:

1. Type a name for the machine, like web-01, or leave it empty to use its own host name.
2. Check that Panel address is the https://...:8443 address from step 1.
3. Press Make join code.

You get a one-time join code, valid for 24 hours, and the exact command to paste on the new machine, for Linux and for Windows. The command carries the panel’s pin, so the machine talks to your panel and refuses anything pretending to be it.

3. Install the agent

On Linux

Linux with systemd, Python 3.10 or newer with venv, and sudo. Get the code and paste the command from the dashboard:

git clone https://github.com/RexGuard/SentrAI && cd SentrAI
sudo ./mvp/deploy/install-agent.sh --panel https://panel.example.com:8443 --code ABCD-EFGH-JKLM --pin sha256:... --name web-01

The installer joins the panel, approves the machine’s nginx, SSH, Suricata and database logs if it finds them, and starts the sentrai-agent service. Within a minute the machine shows on Machines with the services running on it.

On Windows

Windows 10, 11 or Server 2016 and newer, with Python 3.10 or newer from python.org installed for all users (the Microsoft Store Python cannot run as a service). Get the code, open PowerShell as Administrator in the SentrAI folder and paste the Windows command from the dashboard:

powershell -ExecutionPolicy Bypass -File .\mvp\deploy\install-agent.ps1 -Panel https://panel.example.com:8443 -Code ABCD-EFGH-JKLM -Pin sha256:... -Name pc-01

It installs the SentrAI agent Windows service, which starts with Windows and restarts itself after a crash. Check it with Get-Service SentrAIAgent. Its output is in C:\ProgramData\SentrAI\agent\service\SentrAIAgent.out.log.

Blocks start as a dry run

On a new machine the agent only logs the firewall command it would run for each block. Watch it for a while (journalctl -u sentrai-agent -f on Linux, the log file above on Windows). When the commands look right, let it really change the firewall:

sudo ./mvp/deploy/install-agent.sh --enforce --protect 203.0.113.10

powershell -ExecutionPolicy Bypass -File .\mvp\deploy\install-agent.ps1 -Enforce -Protect 203.0.113.10

The panel’s own address is never blocked on an added machine. Add --protect (-Protect) for every address you manage that machine from, just as on the panel. A rerun keeps what earlier runs set: --protect adds to the addresses already kept, and enforcing stays on until you pass --dry-run (-DryRun on Windows) to go back to only logging.

Agent installer options

On Linux the settings are in /etc/sentrai/agent.env and the machine’s key in /var/lib/sentrai/agent/, where INDEX.md lists every file the agent keeps (C:\ProgramData\SentrAI\agent\INDEX.md on Windows). After editing agent.env by hand, run sudo systemctl restart sentrai-agent. On Windows, rerun the installer with the option you want to change; the others are kept.

On a laptop, without a service

For a quick test, the agent can run from a checkout while a terminal is open. From mvp/lab, with its Python environment from a first run.sh / run.ps1:

.venv/bin/python -m agent join --panel https://panel.example.com:8443 --code ABCD-EFGH-JKLM --pin sha256:...
.venv/bin/python -m agent run

On Windows use .\.venv\Scripts\python.exe in place of .venv/bin/python.

Look after your machines

A revoked machine stops at once: its key no longer works. To bring it back, make a new join code and run the installer again with it.

Scans and backups run on the machine itself, on folders set there and never by the panel. List them in that machine’s /etc/sentrai/agent.env and restart the agent:

SENTRAI_THREAT_PATHS=/var/www:/srv/minecraft/plugins
SENTRAI_BACKUP_PATHS=/srv/app/data

The agent picks a job up within about 15 seconds. Serious scan findings open an incident on that machine, and backups stay on the machine.

Admins shows who is signed in on the machine right now (the account, how and from where, and whether SentrAI trusts that sign-in and why), the root work your known administrators did lately, and the administrators it knows: accounts, addresses and SSH keys, each with how it came to know them (a setting, taught, or learned) and a Forget button, except for the ones from the settings. A small form adds an address, key or account with a label. Root work from a sign-in SentrAI does not know opens a Root access from an unrecognised sign-in incident, which never blocks anything by itself and has two answers on the incident and in its Telegram alert: This was me teaches SentrAI that sign-in and closes the alert, Not me: block it blocks the address. The panel’s installer puts your --protect and dashboard addresses in ADMIN_IPS, so your own work from your computer counts as yours on every machine from the start. See Your own administrators.

Hardware comes from the agent every 30 seconds: CPU, memory, each disk, network traffic, uptime, and temperatures where the machine has sensors it can read (most Linux machines; usually none on Windows or in a cloud VM). The panel keeps the last hour for the charts. It alerts the on-duty person once when a disk passes 90% full, or CPU or memory stays over 90%, or a sensor stays over 85 °C, for 5 minutes. Change the limits with SENTRAI_HW_* in the panel’s settings (see the API reference), or set SENTRAI_HW_ALERTS=off to only show them. Agents installed before this need an update (sudo sentrai-update) to start sending it.

Update the agents

On each Linux machine, one command updates the agent to the newest code. It stays joined and keeps --enforce/dry run, --protect and its approved logs:

sudo sentrai-update

On Windows, from an Administrator PowerShell:

& "C:\Program Files\SentrAI\update-agent.ps1"

Both save the running version first, check the agent runs and keeps running, and put the saved version back when it does not. --check (-Check) only says whether a newer version is out, and --rollback (-Rollback) goes back to the version before the last update. Update the panel first (also sudo sentrai-update, on the panel): a newer agent may need a newer panel.

Agents installed before the updater was added get it with one last update the old way: git pull, then sudo ./mvp/deploy/update.sh (Linux) or the install command again without --code (Windows).

When the panel cannot be reached

• Blocks already in place stay for 24 hours (SENTRAI_AGENT_OFFLINE_HOLD_H) and are then removed, so a lost panel never leaves a block in force forever.
• Logs wait on the machine and reach the panel when it is back.
• After 30 seconds the agent’s own rules take over and block clear attacks (password guessing, SQL injection, port scans and the like) for an hour at a time, at most 10 new blocks an hour. Private and protected addresses are never blocked. SENTRAI_AGENT_LOCAL_RULES=off turns this off.
• When the panel answers again, it gets a report of every block made alone. Machines shows it under Last time offline.

Renewing the panel’s certificate

The panel’s certificate lasts five years. If you replace it, every machine needs the new pin. The dashboard shows the new pin with every join code. On each machine, from the SentrAI folder:

sudo ./mvp/deploy/install-agent.sh --pin sha256:...

powershell -ExecutionPolicy Bypass -File .\mvp\deploy\install-agent.ps1 -Pin sha256:...

The installer keeps every other setting and restarts the agent.

A panel behind a publicly trusted certificate, for example nginx with Let’s Encrypt, can leave the pin out.

Not tested yet

The Windows agent installer is tested on a real Windows machine for every change, including a real Windows Firewall block. install-agent.sh has not yet been run on a real systemd machine, and the Linux agent has not yet changed a real firewall with --enforce. Try it on a test machine first, keep the dry run on for a while, and make sure your own IP is protected before you turn enforcement on.