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>"

# 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

What the agent reports

On every heartbeat 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
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 developers 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