On-Prem Relay Connector

The Infracast Relay enables full discovery of on-premises infrastructure — no VPN, no inbound firewall rules required. A lightweight relay runs inside your network and establishes an outbound-only connection (port 443) to Infracast SaaS. All scanning and agent traffic tunnels through this secure connection.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Infracast SaaS                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ Credential   │  │    Task      │  │  WebSocket Hub   │  │
│  │ Store        │◄─│  Dispatcher  │◄─│                  │  │
│  └──────────────┘  └──────────────┘  └────────┬─────────┘  │
└───────────────────────────────────────────────┼────────────┘
                                                │
                              WSS (port 443, outbound only)
                                                │
┌───────────────────────────────────────────────┼────────────┐
│ Your Network                                  ▼            │
│                              ┌────────────────────────┐    │
│                              │   infracast-relay         │    │
│                              │   :8443 (local HTTPS)  │    │
│                              └──┬──────┬──────┬───────┘    │
│                                 │      │      │            │
│         ┌───────────────────────┘      │      └──────────┐ │
│         ▼                              ▼                 ▼ │
│  ┌──────────────┐     ┌─────────────────────┐  ┌────────┐ │
│  │   vCenter    │     │ Switches / Routers  │  │Servers │ │
│  │  (govmomi)   │     │  (SNMP / SSH)       │  │(WinRM) │ │
│  └──────────────┘     └─────────────────────┘  └────────┘ │
└────────────────────────────────────────────────────────────┘

Why Use a Relay?

Traditional Approach	With Relay
VPN tunnel to cloud	No VPN needed
Inbound firewall rules	Outbound-only (port 443)
Complex network config	Single container deployment
Credentials in multiple places	Credentials stay in Infracast SaaS
Agents need internet access	Agents work through relay proxy

What the Relay Can Scan

VMware vSphere

Connects to vCenter via HTTPS (govmomi)
Discovers: vCenter, ESXi hosts, VMs, datastores, resource pools, virtual switches, port groups, clusters

Configuration:

{
  "provider": "vsphere",
  "config": {
    "vcenter_url":  "https://vcenter.internal",
    "username":     "readonly@vsphere.local",
    "password":     "secret",
    "insecure":     false
  }
}

Linux Servers (SSH)

Password and key-based authentication supported
Discovers: OS info, running processes, installed packages (rpm/deb/pip), listening ports, firewall rules (iptables/nftables), active connections, local users, sudo config

Configuration:

{
  "provider": "ssh",
  "config": {
    "host":         "10.0.1.20",
    "port":         22,
    "username":     "svc-infracast",
    "password":     "secret",
    "private_key":  "<base64 PEM>",
    "sudo":         true
  }
}

Network Devices (SNMP)

Supports SNMP v2c and v3
Discovers: interfaces, ARP tables, routing tables, CDP/LLDP neighbors, device model/OS version, VLAN membership
Compatible with Cisco IOS/NX-OS, Juniper JunOS, Palo Alto, Fortinet, and any RFC-compliant device

Configuration:

{
  "provider": "snmp",
  "config": {
    "target":          "10.0.1.1",
    "community":       "public",
    "version":         "2c",
    "port":            161,
    "v3_username":     "",
    "v3_auth_proto":   "SHA",
    "v3_auth_key":     "",
    "v3_priv_proto":   "AES",
    "v3_priv_key":     ""
  }
}

Windows Servers (WinRM)

Connects via WinRM (HTTP or HTTPS), supports domain authentication
Discovers: OS info, running services, installed software (registry), listening ports, firewall rules (netsh), local users, domain membership

Configuration:

{
  "provider": "winrm",
  "config": {
    "host":     "10.0.1.30",
    "port":     5985,
    "username": "DOMAIN\\svc-infracast",
    "password": "secret",
    "https":    false,
    "insecure": true
  }
}

On-prem DNS (Active Directory, Windows DNS, BIND)

From Settings → Connectors → Relay, click DNS on a relay and pick the source. The relay runs the matching plugin that was installed with it, and the records land on the Certificates and Topology pages labelled with where they came from.

Source	Connects with	You provide
Active Directory–integrated DNS	LDAP / LDAPS to a domain controller	LDAP URL, bind user + password; optional zone list
Windows DNS Server	WinRM (5985, or 5986 over HTTPS)	server(s), user + password; optional zone list
BIND or any RFC 5936 server	DNS zone transfer (AXFR, TCP 53)	server, the zones to transfer, optional TSIG key

Zone transfer cannot list zones — name every zone you want. The server must allow AXFR from the relay's address or with the TSIG key you enter.
A refused transfer, a wrong TSIG key or a bad bind password fails the job with the reason; it is never reported as an empty zone.
The DNS button is disabled while the relay is Degraded (update pending) or lacks the plugin: re-run the relay's install command to update it.
Credentials are sent with the job only and are masked when the job is viewed.

Agent-Through-Relay Proxy

On-premises agents can connect through the relay instead of reaching Infracast SaaS directly. This means on-prem agents also require zero inbound firewall rules.

The relay exposes a local HTTPS API on port :8443. Configure agents to use the relay by pointing them at it:

INFRACAST_SERVER=https://<relay-ip>:8443 \
INFRACAST_TOKEN=<enrollment-token> \
  ./infracast-agent

Equivalently, using flags: ./infracast-agent -server https://<relay-ip>:8443 -token <enrollment-token>.

Variable names

The agent reads INFRACAST_SERVER and INFRACAST_TOKEN. This page previously said INFRACAST_API_URL and INFRACAST_AGENT_TOKEN — nothing reads either name, and the agent accepts no aliases or alternative spellings.

An operator copying the old lines would set variables nothing reads, and the agent would fall through to its default of https://api.infracast.io. A relay deployed specifically because the host has no outbound path would then silently try to reach SaaS directly rather than failing loudly — a wrong-default, which is the harder failure to notice.

The relay auto-generates a self-signed TLS certificate on first start for the local API. Agents must install the relay certificate — the agent has no TLS-skip flag or environment variable.

Agents connected through a relay are identified in the UI as relay-connected and show which relay they are tunneling through.

Quick Start

1. Create a Relay Token

In the Infracast UI:

Go to Settings → Connectors → Relay
Click Create Relay
Give it a name (e.g., "Headquarters")
Copy the enrollment token (shown only once)

Or via API:

curl -X POST https://api.infracast.io/api/v1/tenants/{tenantId}/relays/tokens \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "HQ Relay"}'

2. Install the Relay

One-line install (Linux with systemd — recommended): copy the command shown when you create the relay. It looks like this:

curl -fsSL https://get.infracast.io/install.sh | sudo bash -s -- \
  --token '<token>' --relay-id '<relay-id>' \
  --server 'wss://api.infracast.io/ws/relay' --version '<build>'

The installer downloads the relay and the plugins it runs (Active Directory, Windows Server, DNS zone transfer) into /usr/local/bin/plugins/, writes /etc/infracast-relay/relay.env, and starts the infracast-relay service.

Every file is checked against the SHA256SUMS published with that build; the installer refuses to install a file that is missing from the list or does not match, and aborts if SHA256SUMS itself is missing.

--version installs the relay build that matches your Infracast server. The server only sends plugin work (for example on-prem DNS discovery) to a relay of the same build; a relay of a different build shows as Degraded — update pending on the Relays page until it is reinstalled with the current command.

Manual (review the installer first):

curl -fsSLo install.sh https://get.infracast.io/install.sh
less install.sh
sudo bash install.sh --token '<token>' --relay-id '<relay-id>' --server 'wss://api.infracast.io/ws/relay' --version '<build>'

Windows / macOS: download the relay and its plugins from get.infracast.io, put the plugins in a plugins folder next to the relay, and run it with RELAY_ID, RELAY_TOKEN and RELAY_SERVER set. A container image is not currently published. Each platform directory has a SHA256SUMS file — verify with sha256sum -c SHA256SUMS --ignore-missing (macOS: shasum -a 256 -c SHA256SUMS; Windows: compare Get-FileHash output).

Copy from UI

The Relays page shows the install command with your token, relay ID, server and build pre-filled, with a copy button. The token is shown only once.

3. Verify Connection

The relay will appear as Online in Settings → Connectors → Relay within a few seconds of starting.

4. Run a Discovery Scan

From Settings → Connectors → Relay, click Scan on your relay and choose a provider:

Select VMware vSphere, SSH (Linux), SNMP (Network), or WinRM (Windows)
Fill in the connection details for your target
Click Run Scan

Results appear in your asset graph just like any other discovery.

Relay Management UI

Settings → Connectors → Relay provides:

Token management — create tokens, see active relays, revoke individual tokens instantly
Connection status — online/offline indicator with last-seen timestamp per relay
Test connectivity — send a probe through the relay to verify it can reach a target host/port
Dispatch scans — provider-specific config forms for each scan type (vSphere, SSH, SNMP, WinRM)
Collect DNS — Active Directory, Windows DNS and BIND sources through the relay's plugins
Copy-to-clipboard — all install commands are pre-configured and ready to paste

Security Model

Credential Handling

Credentials are stored only in Infracast SaaS (AES-256-GCM encrypted at rest)
When a scan runs, credentials are sent to the relay over TLS
The relay holds credentials only in memory during execution
Credentials are never written to disk on the relay

Network Security

Outbound-only: The relay initiates the connection to Infracast (no inbound rules)
TLS encrypted: All communication uses WSS (WebSocket Secure)
Token authentication: Relays authenticate with enrollment tokens
Instant revocation: Revoking a token immediately disconnects the relay

If a Relay Is Compromised

Revoke its token in the UI → immediate disconnect
The attacker gains no stored credentials (none on disk)
Deploy a new relay with a fresh token

Configuration

Environment Variables

Variable	Required	Description
`RELAY_TOKEN`	Yes	Enrollment token from Infracast
`RELAY_ID`	Yes	Unique relay identifier
`RELAY_SERVER`	No	Infracast WebSocket URL (default: `wss://api.infracast.io/ws/relay`)
`RELAY_NAME`	No	Friendly name (default: hostname)
`RELAY_PROXY_PORT`	No	Local HTTPS API port for the agent proxy (default: `8443`; `0` disables it)
`RELAY_PLUGIN_DIR`	No	Where the relay looks for its plugins (default: `plugins` next to the relay binary)

Network Requirements

Direction	Port	Destination	Purpose
Outbound	443	api.infracast.io	Infracast SaaS connection
Internal	22	Linux servers	SSH scanning
Internal	161	Network devices	SNMP scanning
Internal	5985/5986	Windows servers	WinRM scanning
Internal	443	vCenter	vSphere scanning
Local only	8443	—	Agent proxy API (not internet-exposed)

Resource Requirements

CPU: 0.5 vCPU minimum
Memory: 256 MB minimum
Disk: 50 MB for binary/container

High Availability

Deploy multiple relays for redundancy or to cover different network segments: create one relay per site in the UI and run each site's install command on a host in that site. Set RELAY_NAME in /etc/infracast-relay/relay.env to label it (defaults to the hostname).

Each relay appears independently in the UI. You can target specific relays for specific scans.

Troubleshooting

Relay Shows "Offline"

Check the container/service is running: docker ps or systemctl status infracast-relay
Verify outbound connectivity to api.infracast.io:443
Check the token hasn't been revoked
Review logs: docker logs infracast-relay or journalctl -u infracast-relay

Discovery Tasks Timeout

Verify the relay has network access to the target (use Test Connection in the UI)
Check credentials are correct
Ensure the target allows connections from the relay's IP

Connection Keeps Dropping

Check for proxy or firewall intercepting WebSocket connections
Ensure no aggressive connection timeout policies between relay and api.infracast.io
Update to the latest relay version

Agents Can't Connect to Relay

Verify port 8443 is reachable from the agent host to the relay host
Agent must trust the relay's self-signed certificate — install the relay cert on the agent host. (INFRACAST_INSECURE_SKIP_VERIFY was documented here but does not exist: there is no TLS-verification bypass in the agent, so this is the only option.)
Check docker logs infracast-relay for [local-api] error messages

API Reference

List Relays

GET /api/v1/tenants/{tenantId}/relays

Create Relay Token

POST /api/v1/tenants/{tenantId}/relays/tokens
{"name": "HQ Relay"}

Response includes pre-built install commands:

{
  "relay_id": "abc123",
  "token": "secret-token",
  "install_cmd": "curl -fsSL https://get.infracast.io/install.sh | sudo bash -s -- --token ... --relay-id ... --server ... --version ...",
  "relay_version": "<build>",
  "version_pinned": true,
  "docker_cmd": ""
}

Revoke Relay Token

DELETE /api/v1/tenants/{tenantId}/relays/tokens/{relayId}

Test Connectivity Through Relay

POST /api/v1/tenants/{tenantId}/relays/{relayId}/test
{"target": "10.0.1.50", "port": 443, "protocol": "https"}

Dispatch Scan Through Relay

POST /api/v1/tenants/{tenantId}/relays/{relayId}/tasks
{
  "provider": "vsphere",
  "config": {
    "vcenter_url": "https://vcenter.internal",
    "username": "readonly@vsphere.local",
    "password": "secret"
  },
  "timeout": 300
}

Supported provider values: vsphere, ssh, snmp, winrm

Install Script

curl -fsSL https://api.infracast.io/api/v1/install/relay | sudo bash -s -- --token '<token>' --relay-id '<relay-id>'

Returns a short script that runs the standard installer pinned to this server's address and build. The token and relay ID are passed as arguments, not in the URL.

Architecture​

Why Use a Relay?​

What the Relay Can Scan​

VMware vSphere​

Linux Servers (SSH)​

Network Devices (SNMP)​

Windows Servers (WinRM)​

On-prem DNS (Active Directory, Windows DNS, BIND)​

Agent-Through-Relay Proxy​

Quick Start​

1. Create a Relay Token​

2. Install the Relay​

3. Verify Connection​

4. Run a Discovery Scan​

Relay Management UI​

Security Model​

Credential Handling​

Network Security​

If a Relay Is Compromised​

Configuration​

Environment Variables​

Network Requirements​

Resource Requirements​

High Availability​

Troubleshooting​

Relay Shows "Offline"​

Discovery Tasks Timeout​

Connection Keeps Dropping​

Agents Can't Connect to Relay​

API Reference​

List Relays​

Create Relay Token​

Revoke Relay Token​

Test Connectivity Through Relay​

Dispatch Scan Through Relay​

Install Script​

Architecture

Why Use a Relay?

What the Relay Can Scan

VMware vSphere

Linux Servers (SSH)

Network Devices (SNMP)

Windows Servers (WinRM)

On-prem DNS (Active Directory, Windows DNS, BIND)

Agent-Through-Relay Proxy

Quick Start

1. Create a Relay Token

2. Install the Relay

3. Verify Connection

4. Run a Discovery Scan

Relay Management UI

Security Model

Credential Handling

Network Security

If a Relay Is Compromised

Configuration

Environment Variables

Network Requirements

Resource Requirements

High Availability

Troubleshooting

Relay Shows "Offline"

Discovery Tasks Timeout

Connection Keeps Dropping

Agents Can't Connect to Relay

API Reference

List Relays

Create Relay Token

Revoke Relay Token

Test Connectivity Through Relay

Dispatch Scan Through Relay

Install Script