Agent Installation

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

Prerequisites

Requirement	Notes
Linux (amd64/arm64) or macOS (amd64/arm64) or Windows (amd64)	Cross-platform
Network access to server port 9090	gRPC + mTLS
Agent TLS certificate	From gen-dev-certs.sh or enrollment

Option A — Build from source

cd /path/to/sielum

# Build for current platform
go build -o sielum-agent ./agent/...

# Or cross-compile for Linux amd64
GOOS=linux GOARCH=amd64 go build -o sielum-agent-linux-amd64 ./agent/...

Option B — Cross-platform release build

make release

Produces binaries for all platforms in dist/:

• sielum-agent-linux-amd64
• sielum-agent-linux-arm64
• sielum-agent-darwin-amd64
• sielum-agent-darwin-arm64
• sielum-agent-windows-amd64.exe

Option C — Automated enrollment (recommended for mass deployment)

Use the enrollment command to automatically obtain a device certificate from the server:

./sielum-agent enroll \
  --server https://your-sielum-server.example.com \
  --token "$ENROLLMENT_TOKEN" \
  --out /etc/sielum/certs/

This generates an ECDSA P-256 keypair, submits the CSR to POST /api/enroll, and saves:

• /etc/sielum/certs/device.crt — signed device certificate
• /etc/sielum/certs/device.key — private key
• /etc/sielum/certs/ca.crt — CA certificate from server

Configuration

Create the agent configuration file:

# /etc/sielum/agent.yaml

server: "your-sielum-server.example.com:9090"  # gRPC server address (no https://)

# mTLS certificates
ca:   "/etc/sielum/certs/ca.crt"
cert: "/etc/sielum/certs/device.crt"
key:  "/etc/sielum/certs/device.key"

# Operating mode:
# - auto: detect capabilities at startup, use privileged if possible
# - privileged: enable firewall rule enforcement (requires CAP_NET_ADMIN)
# - user: monitoring only, no firewall enforcement
mode: auto

# Enable Docker container scanning (opt-in, requires /var/run/docker.sock access)
docker: false

See Agent Configuration Reference → for all options.

Running the agent

Direct execution (development)

./sielum-agent start --config /etc/sielum/agent.yaml

Or using individual flags:

./sielum-agent start \
  --server localhost:9090 \
  --ca   deploy/certs/ca.crt \
  --cert deploy/certs/agent.crt \
  --key  deploy/certs/agent.key

systemd service (Linux, recommended for production)

Use the automated install script:

sudo bash deploy/agent/install-linux.sh \
  --server your-sielum-server.example.com:9090 \
  --token  "$ENROLLMENT_TOKEN" \
  --mode   privileged    # or: user

This script:

1. Creates a dedicated sielum system user
2. Copies the binary to /usr/local/bin/sielum-agent
3. Creates configuration in /etc/sielum/
4. Runs sielum-agent enroll to obtain a device certificate
5. Installs and enables the systemd service

Verify:

systemctl status sielum-agent
journalctl -u sielum-agent -f

Privileged vs. user mode

Feature	Privileged mode	User mode
Process monitoring	✅	✅
API connection monitoring	✅	✅
MCP server detection	✅	✅
Config change detection	✅	✅
Config enforcement	✅	✅
Firewall rule enforcement	✅ (CAP_NET_ADMIN)	❌

For firewall enforcement on Linux, the agent requires CAP_NET_ADMIN. The provided systemd unit (sielum-agent.service) sets AmbientCapabilities=CAP_NET_ADMIN with CapabilityBoundingSet limiting it to exactly this capability.

For workstations where firewall control is not needed, use mode: user — the agent runs without any elevated privileges.

Version

./sielum-agent version
# Sielum Agent v1.0.0 (linux/amd64)