Quick Start
Install the standalone Free agent locally on a Linux server. This does not enroll a SaaS node.
Installation
The public self-contained /install.sh bundle installs Free by default on Linux with Bash and root privileges. Download it, inspect it, and only then choose whether to run it. Verify HTTPS/TLS and confirm published /install.sh bytes before running; endpoint availability has not been verified. This does not install the SaaS web app or backend. Standalone Free leaves the SaaS token blank; supplying a SaaS token enables remote scan and subsequent scheduling, so review this on a disposable VPS first. Enrollment also requires a reachable backend. The unsupported root repository install.sh is a different script; do not use it for this path.
curl -fsSLo install.sh https://sentinelvps.online/install.sh
sudo bash ./install.shOptional: review the script before running it with less install.sh (press q to exit), as a separate command.
Free installer options
These extra CLI flags are for the cloned Free repository installer only, not the downloaded public bundle. The public bundle invokes its embedded Free installer with --non-interactive and --email-to only:
--email-to, -e <email>: alert recipient--email-from, -f <email>: alert sender--cpu-threshold, -t <num>: CPU percent threshold (default 80)--sustained-seconds, -s <num>: duration above threshold (default 120 seconds)--check-interval, -i <num>: check interval (default 15 seconds)--cooldown, -c <num>: minutes between alerts (default 30)--non-interactive, -y: skip prompts--reconfigure, --force: overwrite existing configuration--help, -h: display installer help
The Free installer has no --agency option and does not create SaaS API keys. SaaS agent enrollment is a separate workflow; do not use Free installation commands to connect a dashboard.
Interactive English Installer Prompts
The public bundle https://sentinelvps.online/install.sh displays a branded ASCII shield emblem with branded host/SaaS status detection (reporting bundle version, whether an existing installation was found, and current SaaS enrollment link status) followed by 2 clear English interactive prompts:
- Prompt 1: Alert destination email: Sets where incident alerts are sent. On re-runs, it automatically detects and defaults to your current
EMAIL_TO. - Prompt 2: SaaS enrollment token: Leave blank for Free standalone (or to preserve an existing SaaS Fleet link on re-runs); paste a 10-minute token from Servers → Add VPS to link or re-enroll the node with
--allow-remote-scanand a 5-minute telemetry cron. The node links automatically to https://sentinelvps.online; no domain is asked. Ifjqis missing, it is listed in the installation summary and installed from your server's own package repositories (apt-get, dnf or yum) after you confirm; no repository is added.
Idempotent Re-Runs & Upgrades
Re-running sudo bash ./install.sh is fully idempotent:
- It updates EMAIL_TO in /etc/sentinel/sentinel.conf in-place while preserving custom thresholds, whitelists, and vault data.
- On an already-enrolled host, leaving the SaaS token blank on re-run preserves an existing /etc/sentinel/config.env and /etc/cron.d/sentinel-saas without disrupting telemetry.
- If a new token is provided, the installer stages re-enrollment atomically and rolls back to the previous /etc/sentinel/config.env if redemption fails.
Agent Enrollment & VPS Registration
To connect a Linux server to your Sentinel SaaS fleet, an administrator requests a single-use enrollment token from the control plane and provides it during agent setup on the target VPS.
1. Requesting an Enrollment Token in SaaS
Follow this progressive sequence in the web dashboard:
- Add VPS: Sign in as an administrator on an ACTIVE PRO or UNLIMITED subscription and navigate to the Fleet & nodes page (
/servers). Click the Add VPS button in the header. - Select client tenant: Choose the target tenant organization belonging to your agency to assign the new node.
- Optional 6-digit TOTP: If two-factor authentication (2FA) is enabled on your administrator account, provide the 6-digit verification code from your authenticator app. 2FA is optional and only required when enabled on your account; it is not universally mandatory for accounts without 2FA configured.
- Token generation: Click Request enrollment token. The backend validates permissions, subscription status, and capacity (maximum 5 pending tokens per organization, subject to plan node limits).
2. Token Security & Lifecycle
- 10-minute single-use validity: Enrollment tokens expire automatically 10 minutes after generation and can only be redeemed once.
- SHA-256 backend storage: The SaaS backend stores only a secure cryptographic SHA-256 hash of the token, never the plaintext secret.
- Secret memory (copy once): Plaintext tokens are stored only in memory during the active session. Once you navigate away or close the view, the token cannot be retrieved or displayed again.
- Registration semantics: Requesting a token does not create a server record in the fleet. Node registration occurs strictly when the agent successfully contacts the SaaS control plane and redeems the token.
3. VPS Host Agent Redemption
On the target Linux VPS, the agent setup workflow asks for two parameters:
The 43-character base64url single-use token from the dashboard.
The operator must specify a verified reachable backend HTTPS URL. Do not assume separate app. or api. subdomains exist, or that the frontend URL automatically hosts agent endpoints.
Backend redemption: Backend redeems the token against its SHA-256 hash, registers the new server under your selected organization tenant, and returns a durable API key to the node. Subsequent telemetry and task polling use this durable key.
Account & Environment Eligibility
| Environment | Token Issuance | Prerequisites & Behavior |
|---|---|---|
| Signed preview (Demo) | Blocked (Read-only) | Signed preview sessions are strictly read-only and cannot mint real tokens. |
| Real local development | Eligible | Eligible real local accounts with configured local DB and auth can request tokens just like production. Not blocked. |
| Production SaaS | Eligible | Active PRO/UNLIMITED administrators with available node capacity and optional 2FA. |
| Standalone Free | Token blank | Standalone Free agent leaves the token blank; engine runs locally without connecting to SaaS. |
Actual production readiness requires a configured production database, persistent NextAuth session security, an HTTPS-reachable backend control plane, an active tenant plan with capacity, plus still-unverified agent installer packages, public domain certificates, and live VPS acceptance testing.
Frontend token issuance UI and backend verification endpoints are implemented. However, automated remote agent installation is not certified as production ready. Do not execute unverified installation commands directly on live production hosts.
Architecture
The Free agent runs locally on your host. The separate SaaS agent has a pull-based task design, but dashboard queue and telemetry integration are not verified end to end; Free installation does not activate them.
1. Scheduled Execution
The Free installer enables a systemd service for local monitoring. Its default check interval is 15 seconds; consult its configuration before running on a production host.
2. Secure Pull
The separate SaaS agent is designed to poll for tasks with an API key. This is not a feature of the Free installer.
Data Payload Example
The following is an illustrative SaaS payload shape, not telemetry emitted by the Free agent or proof of a working integration:
{
"type": "ROUTINE_SCAN",
"status": "INFECTED",
"durationMs": 1420,
"threatType": "MINER",
"filePaths": "/tmp/.kworker_crypto",
"malwareHashes": "e3b0c442...855",
"payload": {
"filesScanned": 15420,
"cpuUsage": "0.38%",
"actionTaken": "SIGKILL_AND_PURGE"
}
}Agent CLI Commands
The Free CLI runs locally via SSH. Scans and the monitor keep killing and quarantining suspected malware automatically; on an enrolled server the resulting vault records and kill events are also reported to the dashboard (see below).
sentinel monitorsentinel scansentinel cleansentinel webshellssentinel auditsentinel tracesentinel test-alertsentinel test-cpuThese commands can change host state: even scan calls remediation helpers; clean and webshells can remove files and stop processes. Review the upstream CLI and use a disposable host first. These are Free commands, not SaaS remote tasks.
Quarantine, restore & false positives
Every file-system action taken automatically goes through a local vault first, so it can be undone. Process kills cannot be undone; they are only recorded with their forensic capture.
sentinel list [--json]sentinel show <id> [--json]sentinel rollback <id>sentinel allow <id>sentinel allowlist list|add|removerollback restores the item to its original path, owner and mode. allow restores it if still quarantined and adds it to the allowlist so the next scan leaves it alone.
From the dashboard, Restore and Mark as false positive are available on a server's page for quarantined items. They require an agency ADMIN with 2FA enabled and a valid 6-digit code on each request, and every request is recorded in an audit log. The agent only acts on ids that exist in its own local vault.
Quarantine sync and remote actions need the node to run Free v1.1.0 or later (reinstall with the current install.sh) and the agent opt-in line REMOTE_SCAN_OPT_IN=1 in /etc/sentinel/config.env. Without opt-in the dashboard shows no quarantine items and remote requests fail without touching the node.
What an enrolled agent uploads: paths, SHA-256 hashes, rule ids, statuses and timestamps of vault items, plus kill events (process name, pid, rule and forensic capture location). Never file contents.
Webhooks & Alerts
SaaS alert integration settings are separate from the Free agent's local email alerts. Do not assume notifications or per-server inheritance are active until the SaaS integration is verified.
- Slack: Reserved for the UNLIMITED plan. Add your Incoming Webhook URL in the
/integrationspage. - Telegram: Exclusive to the UNLIMITED plan. Requires a Bot Token and a Chat ID.
Slack Notification Output
[CRITICAL] Sentinel intercepted anomaly on Node: eu-west-db.
Action: SIGKILL applied.
Path: /var/www/html/wp-content/uploads/shell.php
Billing & Limits
- • Maximum 3 VPS Nodes
- • No Slack or Telegram integration
- • 7-Day Log Retention
- • Multi-tenant Dashboard
- • Unlimited VPS Nodes
- • Slack + Telegram Integration
- • 90-Day Log Retention
- • Downloadable PDF Receipts