Agent Configuration

The agent is configured via a YAML file and/or CLI flags. CLI flags override YAML values.

Default paths per platform

Platform	Config directory	Docker socket
Linux	/etc/sielum	/var/run/docker.sock
macOS	/Library/Application Support/Sielum	/var/run/docker.sock
Windows	C:\ProgramData\Sielum	\\.\pipe\docker_engine

The agent uses these defaults when no explicit --ca, --cert, or --key flags are passed.

Full configuration reference

# Linux:   /etc/sielum/agent.yaml
# macOS:   /Library/Application Support/Sielum/agent.yaml
# Windows: C:\ProgramData\Sielum\agent.yaml

# gRPC server address — host:port, no https://
# Production form: agents.<your-host>:443 (SNI-routed via nginx)
# CLI flag: --server
server: "agents.sielum-server.example.com:443"

# HTTPS REST base URL — used for automatic certificate renewal.
# Written automatically by `enroll`. Leave empty to disable renewal.
# CLI flag: --http-server
http_server: "https://sielum-server.example.com"

# CA certificate to verify the server's TLS certificate
# CLI flag: --ca
ca_file: "/etc/sielum/ca.crt"

# Agent TLS certificate (client cert for mTLS)
# CLI flag: --cert
cert_file: "/etc/sielum/device.crt"

# Agent TLS private key
# CLI flag: --key
key_file: "/etc/sielum/device.key"

# Tenant API key — written automatically by `enroll` after a successful
# enrollment-token exchange. Required for automatic certificate renewal
# (POST /api/enroll/renew uses X-API-Key). Treat the file as sensitive: it
# is created with mode 0600.
# CLI flag: --api-key
api_key: "<auto-issued by enroll>"

# Endpoint identity — written automatically by `enroll`. Server-assigned and
# unique per tenant, so two machines with the same hostname in different
# tenants never collide. Leave unset only on configs generated before this
# field existed; the agent then falls back to a hostname-derived id.
# CLI flag: --endpoint-id
endpoint_id: "<auto-issued by enroll>"

# Tick cadence in seconds. One tick drives the heartbeat (which pulls policy,
# firewall rules and enforcement mode from the server), the inventory report,
# the Config Guard check and the unsafe-config/process checks.
# Default: 300 (5 minutes). Lower it for faster policy propagation at the cost
# of more traffic; the agent always sends a first report right after startup.
# CLI flag: --interval
interval: 300

# Operating mode:
#   auto       — detect capabilities at startup (default)
#   privileged — enable firewall enforcement (requires CAP_NET_ADMIN on Linux)
#   user       — monitoring only, no firewall enforcement
# CLI flag: --mode
mode: auto

# Enforcement mode for policy violations:
#   audit   — detect and report only, do not block (default, safe for rollout)
#   enforce — actively block via firewall / config rewrite
enforcement_mode: audit

# Enable Docker container scanning.
# Requires read access to /var/run/docker.sock.
# Default: false (opt-in for security — docker.sock has broad access)
docker:
  enabled: false
  socket_path: "/var/run/docker.sock"

CLI commands

# Show available commands
sielum-agent --help

# Start the agent
sielum-agent start --config /etc/sielum/agent.yaml

# Start with individual flags (override config file)
sielum-agent start \
  --server agents.sielum.example.com:443 \
  --ca /etc/sielum/ca.crt \
  --cert /etc/sielum/device.crt \
  --key /etc/sielum/device.key \
  --mode privileged

# Enroll a new endpoint (obtain signed certificate)
sielum-agent enroll \
  --server https://sielum.example.com \
  --token "$ENROLLMENT_TOKEN" \
  --cert-dir /etc/sielum/

# Print version
sielum-agent version

# One-off local inventory scan, printed to stdout — no server connection.
# Useful to verify detection on a workstation before enrolling it.
sielum-agent scan --verbose

# Continuous local monitoring, printed to stdout — no server connection.
sielum-agent monitor --verbose

scan and monitor are diagnostic commands: they detect AI clients, MCP servers and connections locally and print what they find without reporting anything to Sielum. Both accept --docker / --docker-socket and --verbose.

What the agent reports

On every tick — by default every 5 minutes, plus once right after startup — the agent sends:

Data	Condition
Running AI agent processes (name, PID, CPU, memory)	Process is currently running
Active API connections per process	Process is currently running
Browser-based AI web sessions (browser, service, domain, last seen)	A browser has an active connection to a known web AI service (e.g. claude.ai, chatgpt.com)
MCP server configuration (names, commands, transports)	Always — read from filesystem config files
Client settings (allowed/denied tools, API key names)	Always — read from filesystem config files

MCP servers and client settings are read directly from the filesystem (~/.claude/settings.json, .mcp.json, etc.) and are therefore reported regardless of whether the AI client is currently running. This ensures the dashboard always shows your current MCP server inventory even when employees are not actively using Claude Code or Cursor.

systemd EnvironmentFile

When installed via install-linux.sh, the agent reads configuration from:

• YAML: /etc/sielum/agent.yaml
• systemd unit: /etc/systemd/system/sielum-agent.service

The systemd unit supports two variants:

• sielum-agent.service — privileged mode with AmbientCapabilities=CAP_NET_ADMIN
• sielum-agent-user.service — user mode without any capabilities