Agent Configuration

The Infracast Agent is configured via a JSON file written automatically during registration. Most settings can be adjusted without re-registering.

Configuration File Location

Platform	Path
Linux	`/etc/infracast-agent/config.json`
Windows	`C:\ProgramData\Infracast\config.json`
macOS	`/etc/infracast-agent/config.json`

Full Configuration Reference

/etc/infracast-agent/config.json
{
  "agent_id": "agt_7f3d2a1b",
  "server_url": "https://api.infracast.io",
  "tenant_id": "ten_abc123",
  "token": "eyJhbGciOiJIUzI1NiIs...",

  "scan": {
    "interval_seconds": 300,
    "heartbeat_interval_seconds": 30,
    "timeout_seconds": 120
  },

  "collectors": {
    "processes": true,
    "ports": true,
    "software": true,
    "firewall": true,
    "connections": true,
    "users": true,
    "file_integrity": false
  },

  "software": {
    "package_managers": ["apt", "yum", "dnf", "rpm", "pip", "pip3", "npm", "gem", "cargo", "go"],
    "include_system_packages": true,
    "include_user_packages": true
  },

  "file_integrity": {
    "enabled": false,
    "paths": [
      "/etc/passwd",
      "/etc/shadow",
      "/etc/sudoers",
      "/etc/ssh/sshd_config"
    ],
    "exclude_patterns": [
      "/tmp/*",
      "/var/log/*",
      "*.pyc"
    ]
  },

  "exclusions": {
    "processes": ["infracast-agent", "systemd"],
    "ports": [],
    "network_interfaces": ["lo"]
  },

  "resources": {
    "max_cpu_percent": 10,
    "max_memory_mb": 128
  },

  "tls": {
    "insecure_skip_verify": false,
    "ca_cert_path": ""
  },

  "log": {
    "level": "info",
    "format": "json",
    "path": ""
  }
}

Core Settings

Server Connection

Field	Description
`server_url`	Infracast API URL — set during registration, do not change without re-registering
`tenant_id`	Tenant this agent reports to — set automatically during registration
`token`	Agent JWT — set during registration; revoke from UI to force re-registration
`agent_id`	Unique agent ID — assigned by server during registration

Scan Intervals

"scan": {
  "interval_seconds": 300,           // Full discovery scan (default: 5 minutes)
  "heartbeat_interval_seconds": 30,  // Heartbeat to show "Online" status
  "timeout_seconds": 120             // Max time for a single scan to complete
}

tip

The UI marks agents as Stale after 90 seconds without a heartbeat, and Offline after 10 minutes. Keep heartbeat_interval_seconds ≤ 60 to maintain "Online" status reliably.

Collectors

Enable or disable individual data collection modules:

"collectors": {
  "processes": true,     // Running process list (PID, name, user, cmdline)
  "ports": true,         // Listening network ports
  "software": true,      // Installed packages (all package managers)
  "firewall": true,      // Firewall rules (iptables / Windows Firewall)
  "connections": true,   // Active network connections
  "users": true,         // Local user accounts and sudo access
  "file_integrity": false // File checksum monitoring (disabled by default)
}

Software Discovery

Control which package managers are queried:

"software": {
  "package_managers": [
    "apt",    // Debian/Ubuntu
    "yum",    // RHEL/CentOS (legacy)
    "dnf",    // RHEL 8+/Fedora
    "rpm",    // Raw RPM database
    "pip",    // Python 2 pip
    "pip3",   // Python 3 pip
    "npm",    // Node.js global packages
    "gem",    // Ruby gems
    "cargo",  // Rust crates
    "go"      // Go modules (from GOPATH)
  ],
  "include_system_packages": true,   // OS-level packages
  "include_user_packages": true      // User-installed packages (~/.local, ~/go, etc.)
}

Windows Software

On Windows, the agent reads from the Windows Registry (HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall) and WMI for installed software — no separate configuration needed.

File Integrity Monitoring

Track cryptographic checksums of sensitive files:

"file_integrity": {
  "enabled": true,
  "paths": [
    "/etc/passwd",
    "/etc/shadow",
    "/etc/sudoers",
    "/etc/sudoers.d/*",
    "/etc/ssh/sshd_config",
    "/etc/ssh/authorized_keys",
    "/boot/grub/grub.cfg"
  ],
  "exclude_patterns": [
    "/tmp/*",
    "/var/log/*",
    "/proc/*",
    "*.pyc",
    "*.log"
  ]
}

When enabled, checksums (SHA-256) are computed at each scan and reported. Changes trigger a finding in Infracast.

Performance

File integrity monitoring on large directory trees can be CPU/IO intensive. Start with a small list of critical files and expand gradually. Use max_cpu_percent to limit impact.

Exclusions

Exclude specific processes, ports, or network interfaces from reports:

"exclusions": {
  "processes": [
    "infracast-agent",    // Exclude the agent itself
    "kworker",            // Kernel workers
    "watchdog"
  ],
  "ports": [
    "32768-60999"         // Exclude ephemeral port range
  ],
  "network_interfaces": [
    "lo",                 // Loopback
    "docker0",            // Docker bridge
    "cni0"               // Kubernetes CNI
  ]
}

Resource Limits

Prevent the agent from consuming excessive CPU or memory:

"resources": {
  "max_cpu_percent": 10,   // Maximum CPU % (soft limit via scheduling)
  "max_memory_mb": 128     // Maximum RSS memory in MB
}

If the agent exceeds memory limits, it restarts automatically. Reduce scan scope or increase the limit if restarts are frequent.

TLS Configuration

For self-hosted deployments with custom CA certificates:

"tls": {
  "insecure_skip_verify": false,        // Never set to true in production
  "ca_cert_path": "/etc/pki/ca.crt"   // Custom CA certificate for server verification
}

For mTLS (mutual TLS) in high-assurance environments:

"tls": {
  "ca_cert_path": "/etc/infracast-agent/ca.crt",
  "client_cert_path": "/etc/infracast-agent/client.crt",
  "client_key_path": "/etc/infracast-agent/client.key"
}

Logging

"log": {
  "level": "info",       // debug, info, warn, error
  "format": "json",      // json (default) or text
  "path": ""             // empty = stdout (captured by journald/EventLog)
}

Set level: "debug" temporarily when troubleshooting connectivity or discovery issues. Debug logs include full HTTP request/response details.

Applying Configuration Changes

After editing config.json:

# Linux
sudo systemctl restart infracast-agent

# Windows
Restart-Service InfracastAgent

# macOS
sudo launchctl stop io.infracast.agent
sudo launchctl start io.infracast.agent

Environment Variable Overrides

Configuration values can be overridden with environment variables (useful for containers):

Environment Variable	Config Field
`INFRACAST_SERVER`	`server_url`
`INFRACAST_TOKEN`	`token`
`INFRACAST_TENANT_ID`	`tenant_id`
`INFRACAST_SCAN_INTERVAL`	`scan.interval_seconds`
`INFRACAST_LOG_LEVEL`	`log.level`
`INFRACAST_MAX_CPU`	`resources.max_cpu_percent`

Example (Docker sidecar):

env:
  - name: INFRACAST_SERVER
    value: "https://api.infracast.io"
  - name: INFRACAST_TOKEN
    valueFrom:
      secretKeyRef:
        name: infracast-token
        key: token
  - name: INFRACAST_SCAN_INTERVAL
    value: "300"

Configuration File Location​

Full Configuration Reference​

Core Settings​

Server Connection​

Scan Intervals​

Collectors​

Software Discovery​

File Integrity Monitoring​

Exclusions​

Resource Limits​

TLS Configuration​

Logging​

Applying Configuration Changes​

Environment Variable Overrides​