Settings

There are three ways to change SentrAI’s settings. They all write the same settings file, and every part reads it when it starts.

• The dashboard: Configuration has every setting, with a search box at the top.
• A guided chat: on a new machine the dashboard opens on Chat with a Set up offer. It asks plain questions (what SentrAI guards, which IPs never to touch, how to alert you) and saves nothing until you confirm the summary. Keys and passwords go in a hidden box.
• The command line: python sentrai_config.py setup asks the same questions in the terminal. python sentrai_config.py shows the current settings.

The file is ~/.sentrai/config.json (%USERPROFILE%\.sentrai\config.json on Windows), or /var/lib/sentrai on a server. It holds your keys, so it is readable by you only. A variable set in the environment always wins over the file. Restart SentrAI after a change, or on a server sudo systemctl restart sentrai.target.

Every other file SentrAI keeps sits in the same folder as the settings file, one sub-folder per part. INDEX.md in that folder lists them all; see where SentrAI keeps its data.

Security preset

One choice sets how quickly SentrAI acts and how long a block lasts.

Strict acts early and holds longer, with more false alarms. Balanced puts day-to-day work first. Advanced lets you set each value yourself.

Never block these

SentrAI never blocks or locks what is on these lists. Put your own admin IP here before anything else.

Your own administrators

SentrAI reads every log line the same way whoever typed it, so your own sudo commands on a server used to look exactly like an intruder covering their tracks. Now it keeps track of who is signed in on each machine and whether it knows that person as an administrator. Root work (a sudo or su command, an administrator action on Windows) by someone it knows is recorded under the machine’s Admins tab and raises nothing. The same work by someone it does not know becomes one incident per address, Root access from an unrecognised sign-in, which never blocks anything on its own: it asks you.

A sign-in is known as an administrator’s in one of three ways:

1. Its SSH key is one of your administrators’ keys (ADMIN_SSH_KEYS, or learned).
2. Its address is one of your administrators’ addresses: ADMIN_IPS (the server installer puts your --protect and dashboard addresses there), learned, or vouched for by your own dashboard sign-in. When an Owner or Admin signs in with the authenticator, root work from that computer’s address counts as theirs for the next 12 hours.
3. It is at the machine’s own keyboard, by one of your administrators’ accounts (ADMIN_ACCOUNTS).

A sign-in made right after password guessing from the same address is not trusted for the next 12 hours (ADMIN_SESSION_HOURS), unless its address or key is one you set or taught, or until you press This was me.

This was me. When the incident was you or a colleague, press This was me on the dashboard or in Telegram. SentrAI learns that sign-in (its address, its SSH key and its account on that machine), closes the incident, undoes any block it had put on you, and does not ask again for that sign-in. When nobody you know was signed in, press Not me: block it: the address is blocked, and the machine should be treated as possibly taken over. Once a sign-in is known, SentrAI also learns the rest on its own: a known key seen from a new address makes the address known, and a new key seen from a known address makes the key known (ADMIN_LEARN).

What it learns, and what you teach it, is kept in people/admins.json next to the core’s own database on the server (/var/lib/sentrai/core/people/ on a server install): addresses, key fingerprints and account names, never a password or a key itself. It is never sent anywhere, and the Admins tab can forget any of it. Entries from the settings below cannot be forgotten there: change the setting instead.

None of them is needed to start: This was me teaches the same things as they come up. They sit under Configuration with the other responder settings; on a server, ADMIN_IPS is in /etc/sentrai/sentrai.env, where the installer wrote it, and a value there wins over the dashboard (restart sentrai.target after a change). For any of this to work, the collector on each machine must send its sign-in and sudo lines: /var/log/auth.log or the system journal, which --add-system-logs approves (see Log sources), plus its own poll of who is signed in, which runs by itself.

Alerts

Telegram

1. In Telegram, message @BotFather, send /newbot, and copy the token it gives you.
2. Send any message to your new bot. Then open https://api.telegram.org/bot<TOKEN>/getUpdates and copy the number after "chat":{"id":.
3. Enter both under Configuration, section Telegram extension (TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID). Saving them turns the Telegram extension on.

Only that chat can press the Approve and Reject buttons.

Staff reports

Staff can report something suspicious without an account. Share the dashboard address with /?report on the end (the Staff reports page shows the exact link). To ask for a shared code first, set SENTRAI_REPORT_CODE. In Telegram they can send /report and what they saw; by default only the alert chat can, and TELEGRAM_REPORT_FROM=any lets staff message the bot directly.

Email

Set the mail server and who gets alerts in the same section. By default email is the backup and is only sent when Telegram fails; choose always to get every alert by email too. For Gmail use smtp.gmail.com, port 587 and an app password.

AI key

SentrAI works without an AI key: its rules decide on their own. A key adds the guided chat’s free-text answers and the log search on servers. Under Configuration, section 5. AI model, pick a provider (Anthropic, OpenAI, DeepSeek or another OpenAI-compatible service) and paste its key.

Firewall blocking

By default a block only goes on SentrAI’s own blocklist (/blocklist, for your app or proxy to read). To block attackers in the machine’s own firewall, go step by step:

1. Make sure your own IP is in PROTECTED_IPS.
2. Set SENTRAI_FIREWALL=auto (or nftables, iptables, or netsh on Windows). SentrAI now only logs the command it would run. Watch the log for a while.
3. When the commands look right, set SENTRAI_FIREWALL_ENFORCE=1. This needs root or administrator rights.

On a server these go in /etc/sentrai/sentrai.env; restart sentrai.target afterwards. On a central panel keep SENTRAI_FIREWALL=off: each added machine applies its own blocks.

Limits on automatic actions

SentrAI keeps every action it takes on its own small, temporary and recorded, so it can be undone. These settings set the limits:

About 10 minutes after each action, SentrAI checks that it worked and that it did not break the page above. A failed undo is tried again a few times, then handed to a person.

Busy servers

A public game server or a big network is scanned and password-guessed by hundreds of addresses a day. On a normal setting each one is its own alert, and together they push the risk index to 100. BUSY_SERVER=on groups them:

• When 10 or more addresses do the same kind of attack (a scan, password guessing) to one machine within 15 minutes, they become one wave. You get one alert when it starts, then one summary every 15 minutes (“40 new, 5 blocked automatically, 35 waiting for a person”) instead of one alert per address.
• A wave counts on the risk index about as much as its worst address, at most twice that, so the index still jumps for anything new or serious, but not for the 300th scanner.
• Every address keeps its own incident, so each can still be blocked, approved and undone. On Approvals, group by type to approve a whole wave at once.

Only put an address in TRUSTED_IPS if you control it or trust whoever does: an attacker behind it would not be seen. A touched decoy is still always reported.

Backups

SentrAI backs up its own settings and records every 24 hours from the start. To back up your own folders too (a website, a game server), list them in SENTRAI_BACKUP_PATHS, for example SENTRAI_BACKUP_PATHS=/var/www:/srv/minecraft (on Windows use ; between folders).

The dashboard’s Backups page shows the last and next backup, has Back up now and Check, and restores a backup. A restore goes into a new folder unless you choose “back where they came from” and type the backup’s name to confirm; SentrAI then saves the current files first, so you can undo it.

All variables

The full list, with every default, is in the MVP README.

Every variable starts with SENTRAI_. Names from before the rename (CACTAI_FIREWALL and the like) still work when the new name is not set; SentrAI prints a reminder to rename them.