Agent Install¶
Audience: Administrators installing the Sentari agent on managed endpoints
What you need: your server URL and an enrollment token from the dashboard. The agent binary is downloaded from public releases (or staged for air-gap).
The agent is a single static Go binary (no runtime dependencies). It scans installed packages on the endpoint and uploads results to your Sentari server outbound over HTTPS/mTLS. It never accepts inbound connections. Enrollment is a one-time handshake: the agent presents the token, the server issues an mTLS device certificate, and the agent reuses it thereafter.
Bundle contents¶
| File | Purpose |
|---|---|
agent.conf.example |
Linux/macOS agent configuration template. |
sentari-agent.service |
Hardened Linux systemd unit. |
windows/install.ps1 |
Windows installer (config + enroll + service). |
windows/uninstall.ps1 |
Windows uninstaller. |
Supported platforms¶
| OS | Architectures | Service manager | Install method |
|---|---|---|---|
| Linux | amd64, arm64 | systemd | Manual (below) |
| Windows | amd64 | Windows service | windows/install.ps1 |
| macOS (12+) | Intel + Apple Silicon | launchd | install-macos.sh |
Pick the section for your endpoint OS. All three end with the device appearing under Devices in the dashboard.
Step 1 — Obtain the agent binary (Linux and Windows)¶
Download the Enterprise Edition binary from the public Sentari agent releases — signed, with checksums and a build-provenance attestation:
https://github.com/sentari-dev/sentari-agent/releases/latest
sentari-agent-<os>-<arch> is the Enterprise Edition (talks to the server);
sentari-agent-oss-<os>-<arch> is the Community Edition (local scan only).
# Example: Linux x86-64
VERSION=v1.0.0 # pick the release tag you are deploying
BASE=https://github.com/sentari-dev/sentari-agent/releases/download/$VERSION
curl -fsSLO $BASE/sentari-agent-linux-amd64
curl -fsSLO $BASE/SHA256SUMS.txt
sha256sum --ignore-missing -c SHA256SUMS.txt # verify
gh attestation verify sentari-agent-linux-amd64 -R sentari-dev/sentari-agent # optional
macOS: skip this step — the macOS installer downloads and verifies the right binary for you.
Air-gapped sites: mirror the release asset onto your internal artifact host (or push via SCCM/Intune/Ansible/Jamf). Once enrolled, agents self-update over their mTLS channel from the server's
/api/v1/agent/release/*endpoints — that path is for updates, not first-time bootstrap.
Install on Linux (systemd)¶
# 1. Install the binary
chmod +x sentari-agent-linux-amd64
sudo install -m 0755 sentari-agent-linux-amd64 /usr/local/bin/sentari-agent-enterprise
# 2. Service user + directories
sudo useradd -r -s /usr/sbin/nologin sentari
sudo mkdir -p /etc/sentari /var/lib/sentari /var/log/sentari
sudo chown sentari:sentari /var/lib/sentari /var/log/sentari
# 3. Configuration
sudo cp agent.conf.example /etc/sentari/agent.conf
sudo $EDITOR /etc/sentari/agent.conf # set [server] url = https://<server>:8000
# 4. Enroll (one-shot: register + obtain mTLS cert + first upload)
sudo -u sentari sentari-agent-enterprise \
--config /etc/sentari/agent.conf \
--enroll-token "<your-enrollment-token>" \
--upload
# Recommended: pin the server TLS cert on first contact with
# --bootstrap-ca-fingerprint "AA:BB:..." (ask your server operator)
# 5. Run as a service
sudo cp sentari-agent.service /etc/systemd/system/sentari-agent.service
sudo systemctl daemon-reload
sudo systemctl enable --now sentari-agent
Only [server].url is required in the config; all other keys have sensible
defaults (documented inline in agent.conf.example).
Install on Windows¶
Run from an elevated PowerShell. Place the downloaded
sentari-agent-windows-amd64.exe next to install.ps1 (or pass -AgentBinary),
then:
cd windows
.\install.ps1 `
-ServerURL https://<server>:8000 `
-EnrollToken "<your-enrollment-token>" `
-AgentBinary ..\sentari-agent-windows-amd64.exe
The installer writes the config, enrolls the agent (obtaining the mTLS
certificate automatically), registers the SentariAgent Windows service with
auto-restart, and starts it. Options: -InstallDir, -ServiceName,
-ScanInterval, -Unattended.
Uninstall: .\uninstall.ps1 (add -KeepData to retain the offline queue / audit DB).
Install on macOS¶
macOS 12+ on Intel and Apple Silicon. The installer downloads the right binary,
verifies its checksum, writes the config, enrolls, and registers a launchd
daemon (dev.sentari.agent).
curl -LO https://raw.githubusercontent.com/sentari-dev/sentari-agent/main/install-macos.sh
chmod +x install-macos.sh
sudo ./install-macos.sh \
--version 0.1.4 \
--server-url https://<server>:8000 \
--enroll-token "<your-enrollment-token>"
The macOS binaries are not yet Apple-signed; the installer clears the Gatekeeper quarantine attribute so the daemon can start.
Full Disk Access — REQUIRED on macOS 13+¶
macOS Transparency, Consent & Control (TCC) blocks access to ~/Documents,
~/Desktop, ~/Downloads even for root. Without Full Disk Access the agent
sees those folders as empty and silently misses every Python virtualenv in
them. Grant it:
Individual Macs: System Settings → Privacy & Security → Full Disk Access
→ + → add /usr/local/bin/sentari-agent, then restart the daemon:
sudo launchctl kickstart -k system/dev.sentari.agent
Mac fleets (MDM): deploy the TCC configuration profile
sentari-agent-tcc.mobileconfig (ships with the agent release, under
deploy/macos/) to pre-grant Full Disk Access so users see no prompt:
| MDM | How |
|---|---|
| Jamf Pro | Configuration Profiles → Upload → scope to target group |
| Microsoft Intune | Devices → macOS → Configuration profiles → Custom → upload .mobileconfig |
| Kandji / Mosyle | Library/Profiles → Add → upload .mobileconfig |
| Manual (no MDM) | sudo profiles install -path sentari-agent-tcc.mobileconfig |
Verify (all platforms)¶
Within a few minutes the endpoint appears under Devices in the dashboard, with its package inventory and CVE correlation populated.
| OS | Check service | Check logs |
|---|---|---|
| Linux | systemctl status sentari-agent |
journalctl -u sentari-agent -f |
| Windows | Get-Service SentariAgent |
Get-Content 'C:\Program Files\Sentari\logs\agent.log' -Tail 50 -Wait |
| macOS | sudo launchctl print system/dev.sentari.agent |
tail -f /var/log/sentari/agent.log |
Mass rollout¶
Drive the per-OS install with your configuration-management tooling — Ansible (Linux), SCCM/Intune (Windows), Jamf/Kandji/Intune (macOS). Stage the binary on an internal artifact host for air-gapped fleets. An Ansible role ships with the Sentari release; point its binary-staging step at your artifact host.
Upgrading¶
Once enrolled, agents self-update from the server over their mTLS channel. To
update manually, replace the binary and restart the service (Linux/Windows) or
re-run install-macos.sh with a newer --version.
Troubleshooting¶
Agent can't connect / won't enroll. Verify curl https://<server>:8000/api/health
from the endpoint, and that the enrollment token matches the server's. Check the
agent log. If certificates are corrupted, delete the certs/ folder under the
data dir (/var/lib/sentari on Linux/macOS, C:\ProgramData\Sentari on Windows)
and re-enroll.
Device not appearing. Confirm the service is running and the log shows a successful upload.
macOS: inventory missing user environments. Grant Full Disk Access (above) — this is the most common macOS issue.
Linux: missing other users' environments. The agent runs as the unprivileged
sentari user and reads only world-readable / sentari-owned files. Run it as a
more privileged user per your security policy to scan restricted per-user envs.
For additional troubleshooting, see the Troubleshooting guide.
For assistance, contact your Sentari representative.