Skip to main content

Agent Installation

The Sielum agent is a native Go binary that runs directly on employee workstations — not in Docker. It needs direct access to the host OS to detect processes, network connections, and read AI client configuration files.

Prerequisites​

RequirementNotes
Linux (amd64/arm64), macOS (amd64/arm64), or Windows (amd64)Cross-platform
Outbound network access to Sielum on port 443gRPC + mTLS — no inbound ports required
curl and administrator (sudo) access on the endpointNeeded by the installer

Install via the dashboard​

The only supported way to install the agent is the install command generated for you in the dashboard. There is no manual binary download or separate enrollment step — the command handles everything.

  1. In the dashboard, open the Install Agent page (it's also part of the Setup Assistant during onboarding).
  2. Select the operating system of the endpoint — Linux, macOS, or Windows.
  3. Copy the generated one-line command. Your enrollment token is already filled in.
  4. Run it on the workstation you want to monitor.

The command downloads the agent binary, enrolls the endpoint (obtaining a device certificate), writes the configuration, and registers the agent as a system service that starts automatically.

First time?

The First Login & Setup guide walks through the whole flow, including where to find the install command and how the first endpoint connects.

Verify the agent is running​

After running the command, confirm the service is up:

# Linux
systemctl status sielum-agent
journalctl -u sielum-agent -f
# macOS
launchctl list io.sielum.agent
# Windows (PowerShell)
Get-Service sielum-agent

The agent reports in right after installation, so the endpoint appears under Devices in the dashboard within about a minute, with detected AI agents under Agents. After that first report it checks in on its regular interval, by default every 5 minutes.

Platform-specific service management and uninstall steps live on the dedicated pages: Linux, macOS, and Windows.

Privileged vs. user mode​

The installer registers the agent in privileged mode by default, which enables firewall rule enforcement. On workstations where firewall control is not needed, the agent can run in user mode (monitoring only, no elevated privileges).

FeaturePrivileged modeUser mode
Process monitoring✅✅
API connection monitoring✅✅
MCP server detection✅✅
Config change detection✅✅
Config enforcement✅✅
Firewall rule enforcement (IPv4 + IPv6)✅❌

For firewall enforcement on Linux, the agent requires CAP_NET_ADMIN. The systemd unit sets AmbientCapabilities=CAP_NET_ADMIN with CapabilityBoundingSet limiting it to exactly this capability. Firewall blocking is dual-stack: IPv4 rules go through iptables, IPv6 through ip6tables. On macOS, pf handles both address families; on Windows, the Windows Filtering Platform (WFP) does.

Multi-user scanning (service mode)​

When the agent runs as a system service, the service account's home directory is not an employee's home. To avoid scanning the wrong directory, the agent automatically detects all active employee home directories:

  • Linux/macOS: parses /etc/passwd and returns all homes for login users (UID ≥ 1000, valid shell, existing directory)
  • Windows: scans C:\Users\ for existing user directories

Each adapter is scoped to the correct home directory at runtime, so detection, config collection, and enforcement all target the actual employee environment, not the service account.

Next steps​