Agent Installation

This guide covers deploying the Infracast Agent on Linux, Windows, macOS, and Kubernetes.

Prerequisites

Outbound HTTPS access to your Infracast server (port 443)
An enrollment token from Settings → Agents → Generate Token
Administrative / root access on the target host

Enrollment Tokens

Enrollment tokens are single-use and time-limited (configurable: 1–168 hours, with optional max-use limits). Generate tokens in bulk for mass deployments. Each token can be labeled for tracking (e.g., "prod-web-servers").

Linux Installation

One-Liner (Recommended)

curl -fsSL https://get.infracast.io/agent | sudo bash -s -- \
  --server https://api.infracast.io \
  --token YOUR_ENROLLMENT_TOKEN

This script:

Detects architecture (x64 or arm64)
Downloads the agent binary
Registers with the Infracast server
Installs and starts the systemd service

Manual Installation

Step 1: Download binary

# x64
curl -LO https://releases.infracast.io/agent/latest/infracast-agent-linux-amd64

# ARM64
curl -LO https://releases.infracast.io/agent/latest/infracast-agent-linux-arm64

sudo mv infracast-agent-linux-* /usr/local/bin/infracast-agent
sudo chmod +x /usr/local/bin/infracast-agent

Step 2: Register with server

sudo mkdir -p /etc/infracast-agent
sudo infracast-agent register \
  --server https://api.infracast.io \
  --token YOUR_ENROLLMENT_TOKEN

This writes a config file to /etc/infracast-agent/config.json with the agent's JWT token.

Step 3: Install systemd service

sudo infracast-agent install-service
sudo systemctl enable infracast-agent
sudo systemctl start infracast-agent

Verify:

systemctl status infracast-agent
infracast-agent status

Systemd Service (Manual)

If you need to manage the service file yourself:

/etc/systemd/system/infracast-agent.service
[Unit]
Description=Infracast Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/infracast-agent run
Restart=always
RestartSec=10
User=root
WorkingDirectory=/etc/infracast-agent

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable infracast-agent
sudo systemctl start infracast-agent

Windows Installation

PowerShell (Administrator)

# Create install directory
New-Item -ItemType Directory -Force "C:\Program Files\Infracast"

# Download agent
Invoke-WebRequest `
  -Uri "https://releases.infracast.io/agent/latest/infracast-agent-windows-amd64.exe" `
  -OutFile "C:\Program Files\Infracast\infracast-agent.exe"

# Register
& "C:\Program Files\Infracast\infracast-agent.exe" register `
  --server https://api.infracast.io `
  --token YOUR_ENROLLMENT_TOKEN

# Install as Windows Service
& "C:\Program Files\Infracast\infracast-agent.exe" install-service

# Start service
Start-Service InfracastAgent

Verify:

Get-Service InfracastAgent
& "C:\Program Files\Infracast\infracast-agent.exe" status

SCCM / Intune Deployment

For mass Windows deployment, package as a script:

deploy-infracast.ps1
$InstallDir = "C:\Program Files\Infracast"
$Token = "YOUR_ENROLLMENT_TOKEN"  # embed token or pull from SCCM variable
$Server = "https://api.infracast.io"

New-Item -ItemType Directory -Force $InstallDir

Invoke-WebRequest `
  -Uri "https://releases.infracast.io/agent/latest/infracast-agent-windows-amd64.exe" `
  -OutFile "$InstallDir\infracast-agent.exe"

& "$InstallDir\infracast-agent.exe" register --server $Server --token $Token
& "$InstallDir\infracast-agent.exe" install-service
Start-Service InfracastAgent

# Verify
if ((Get-Service InfracastAgent).Status -eq "Running") {
    exit 0
} else {
    exit 1
}

macOS Installation

# Intel Mac
curl -LO https://releases.infracast.io/agent/latest/infracast-agent-darwin-amd64

# Apple Silicon
curl -LO https://releases.infracast.io/agent/latest/infracast-agent-darwin-arm64

sudo mv infracast-agent-darwin-* /usr/local/bin/infracast-agent
sudo chmod +x /usr/local/bin/infracast-agent

# Register
sudo infracast-agent register \
  --server https://api.infracast.io \
  --token YOUR_ENROLLMENT_TOKEN

# Install launchd service
sudo infracast-agent install-service

Kubernetes DaemonSet

Deploy as a DaemonSet to monitor all cluster nodes:

infracast-agent-daemonset.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: infracast
---
apiVersion: v1
kind: Secret
metadata:
  name: infracast-agent-token
  namespace: infracast
type: Opaque
stringData:
  token: "YOUR_ENROLLMENT_TOKEN"
---
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: infracast-agent
  namespace: infracast
spec:
  selector:
    matchLabels:
      app: infracast-agent
  template:
    metadata:
      labels:
        app: infracast-agent
    spec:
      hostPID: true
      hostNetwork: true
      tolerations:
        - operator: Exists  # Run on all nodes including control plane
      containers:
        - name: agent
          image: ghcr.io/azgardtek/infracast-agent:latest
          env:
            - name: INFRACAST_SERVER
              value: "https://api.infracast.io"
            - name: INFRACAST_TOKEN
              valueFrom:
                secretKeyRef:
                  name: infracast-agent-token
                  key: token
          securityContext:
            privileged: true
          resources:
            requests:
              cpu: "50m"
              memory: "64Mi"
            limits:
              cpu: "200m"
              memory: "128Mi"
          volumeMounts:
            - name: host-root
              mountPath: /host
              readOnly: true
      volumes:
        - name: host-root
          hostPath:
            path: /

kubectl apply -f infracast-agent-daemonset.yaml
kubectl get pods -n infracast

Ansible Deployment

roles/infracast-agent/tasks/main.yml
---
- name: Set agent binary name
  set_fact:
    agent_binary: "infracast-agent-linux-{{ 'arm64' if ansible_architecture == 'aarch64' else 'amd64' }}"

- name: Download Infracast Agent
  get_url:
    url: "https://releases.infracast.io/agent/latest/{{ agent_binary }}"
    dest: /usr/local/bin/infracast-agent
    mode: '0755'
  register: agent_download

- name: Register agent with server
  command: >
    /usr/local/bin/infracast-agent register
    --server {{ infracast_server_url }}
    --token {{ infracast_enrollment_token }}
  args:
    creates: /etc/infracast-agent/config.json

- name: Install systemd service
  command: /usr/local/bin/infracast-agent install-service
  args:
    creates: /etc/systemd/system/infracast-agent.service

- name: Enable and start Infracast Agent
  systemd:
    name: infracast-agent
    enabled: yes
    state: started
    daemon_reload: yes

Connection to Server

Direct Connection (SaaS / Public API)

Agents connect directly to the Infracast API over HTTPS:

Agent → HTTPS :443 → api.infracast.io

No special configuration needed — just point --server at your API URL.

Via On-Prem Relay

For agents in isolated network segments that can't reach the internet directly, route through an on-prem relay:

Agent → HTTPS :443 → vulcan-relay → WSS :443 → api.infracast.io

Configure the agent to use a relay:

infracast-agent register \
  --server https://relay.internal.example.com:8443 \
  --token YOUR_TOKEN

Air-Gapped Environments

For fully disconnected environments, see the Air-Gap Deployment Guide.

Verifying Installation

The agent should appear in Agents within 60 seconds of registration.

# Linux: Check service status and connectivity
systemctl status infracast-agent
infracast-agent status

# Expected output:
# Agent ID:    agt_7f3d2a1b
# Status:      online
# Server:      https://api.infracast.io
# Last report: 2 minutes ago

Uninstallation

Linux

sudo systemctl stop infracast-agent
sudo systemctl disable infracast-agent
sudo infracast-agent uninstall-service
sudo rm /usr/local/bin/infracast-agent
sudo rm -rf /etc/infracast-agent

Windows

Stop-Service InfracastAgent
& "C:\Program Files\Infracast\infracast-agent.exe" uninstall-service
Remove-Item "C:\Program Files\Infracast" -Recurse -Force

macOS

sudo launchctl unload /Library/LaunchDaemons/io.infracast.agent.plist
sudo rm /Library/LaunchDaemons/io.infracast.agent.plist
sudo rm /usr/local/bin/infracast-agent
sudo rm -rf /etc/infracast-agent

Prerequisites​

Linux Installation​

One-Liner (Recommended)​

Manual Installation​

Systemd Service (Manual)​

Windows Installation​

PowerShell (Administrator)​

SCCM / Intune Deployment​

macOS Installation​

Kubernetes DaemonSet​

Ansible Deployment​

Connection to Server​

Direct Connection (SaaS / Public API)​

Via On-Prem Relay​

Air-Gapped Environments​

Verifying Installation​

Uninstallation​

Linux​

Windows​

macOS​