Air-Gapped Agent Enrollment

Air-gapped enrollment lets you install and enroll TridentStack Control agents on endpoints that have no direct internet access. The agent downloads its binary, enrolls, and communicates entirely through the relay.

When to use this

• Fully isolated networks where endpoints cannot reach the internet, even during initial setup
• Strict egress policies where only a designated relay server is permitted outbound access
• OT/ICS environments where production endpoints must not contact external services directly

Prerequisites

• A relay is deployed and online (see Setup Guide)
• The relay server itself has outbound internet access to gateway.tridentstack.com:443
• Air-gapped enrollment is enabled on the relay (see below)

Enable air-gapped enrollment

1. Go to Settings > Relays in TridentStack Control
2. Find the relay and toggle Air-gapped enrollment to on
3. The relay restarts once (a few seconds) to start its port 8443 listener, then resumes serving agents and proxying enrollment requests

When enabled, the relay:

• Serves a TLS bootstrap listener on port 8443 for agent binary downloads and enrollment
• Downloads and caches agent binaries from TridentStack Control over its existing outbound connection
• Proxies agent enrollment requests to TridentStack Control on behalf of the endpoint
• Continues serving its CA certificate on port 8080 for initial trust establishment

Applying the change

Enabling or disabling air-gapped enrollment restarts the relay once so it can bind or release port 8443. Docker (--restart) and the systemd service restart it automatically within a few seconds, and connected agents reconnect on their own. If the relay runs in Docker, make sure port 8443 is published (-p 8443:8443) when the container is created. The standard run command in the setup guide already includes it. Docker only publishes ports at container creation, so if 8443 was not published you must recreate the container to add it.

Security note

A relay with air-gapped enrollment enabled can serve agent binaries and proxy enrollment credentials. Treat the relay host with the same care as a domain controller or certificate authority in your environment.

Install an agent through the relay

The relay card in Settings > Relays shows ready-to-use install commands under Connect Agents when air-gapped enrollment is enabled. Copy the installer script onto the endpoint first (over USB, a file share, or another transfer method), then run it locally.

Linux

Copy get-tridentstack.sh to the endpoint, then run:

sudo bash get-tridentstack.sh \
  --key <ENROLLMENT_KEY> \
  --relay <RELAY_ADDRESS> \
  --relay-ca-fingerprint <FINGERPRINT>

Windows

Copy install-tridentstack.ps1 to the endpoint, then run:

.\install-tridentstack.ps1 -Token "<ENROLLMENT_KEY>" `
  -Relay "<RELAY_ADDRESS>" `
  -RelayCaFingerprint "<FINGERPRINT>"

macOS

Copy install.sh to the endpoint, then run:

sudo bash install.sh \
  --key <ENROLLMENT_KEY> \
  --relay <RELAY_ADDRESS> \
  --relay-ca-fingerprint <FINGERPRINT>

Replace:

• <ENROLLMENT_KEY> with an agent enrollment key from Settings > Agent Enrollment
• <RELAY_ADDRESS> with the relay's IP address or hostname (shown on the relay card)
• <FINGERPRINT> with the relay's CA certificate fingerprint (shown on the relay card, format: SHA256:abc123...)

What happens during installation

1. The installer fetches the relay's CA certificate over plaintext HTTP on port 8080
2. It verifies the certificate fingerprint against the value you provided
3. It connects to the relay's TLS bootstrap listener on port 8443, using the verified CA
4. It downloads the agent binary from the relay
5. It enrolls the agent through the relay (the relay forwards the enrollment request to TridentStack Control)
6. After enrollment, the agent connects to the relay on port 50051 for all ongoing communication

The endpoint never contacts the internet directly at any point during or after this process.

Firewall rules

When using air-gapped enrollment, the relay server needs port 8443 reachable from agents on the LAN, in addition to the standard relay ports:

Port	Protocol	Direction	Purpose
50051	TCP	Inbound (from agents)	gRPC agent connections (same as standard relay)
8080	TCP	Inbound (from agents)	CA certificate bootstrap
8443	TCP	Inbound (from agents)	Agent binary download and enrollment proxy
443	TCP	Outbound (to gateway.tridentstack.com)	Upstream connection to TridentStack Control

If the relay runs in Docker, each inbound port must also be published on the container (-p 50051:50051 -p 8080:8080 -p 8443:8443 on docker run) in addition to being allowed by the host firewall. Publishing a port and opening the firewall are separate steps: the container port publish makes the relay reachable at all, and the firewall rule permits the traffic to arrive. The standard run command in the setup guide publishes all three.

Troubleshooting

"Failed to fetch relay CA certificate"

The endpoint cannot reach the relay on port 8080. Verify:

• The relay is running and online in TridentStack Control
• Port 8080 is open on the relay host's firewall
• The endpoint can reach the relay's IP address on the LAN

"Relay CA fingerprint mismatch"

The certificate returned by the relay does not match the expected fingerprint. This can happen if:

• The fingerprint was copied incorrectly (check for truncation or extra whitespace)
• The relay was re-created since the fingerprint was obtained (get the current fingerprint from the relay card in Settings)
• A different device is responding on the relay's IP address

"Unable to connect" or connection refused on port 8443

The endpoint fetched the relay CA over port 8080 but cannot open port 8443. Port 8443 listens only when air-gapped enrollment is enabled, and for a Docker relay the port must also be published. Verify:

• Air-gapped enrollment is toggled on for this relay in Settings, and the relay shows Online (enabling it restarts the relay once to bind 8443, which takes a few seconds)
• If the relay runs in Docker, the container was started with -p 8443:8443. Docker publishes ports only at container creation, so if the flag is missing, recreate the container: docker rm -f tridentstack-relay, then run the standard command again (it publishes 8443)
• Port 8443 is open on the relay host's firewall

"Failed to download agent package"

The endpoint reached the relay, but the relay could not serve the agent binary. The relay caches binaries pulled from TridentStack Control over its outbound connection. Verify:

• Air-gapped enrollment is enabled on the relay in Settings, and the relay shows Online
• The relay host has outbound access to gateway.tridentstack.com:443 (this is how it pulls binaries)
• Give the relay a minute after it comes online or after you enable air-gapped enrollment. It populates its binary cache from TridentStack Control on connect
• If it still fails after several minutes, toggle air-gapped enrollment off and back on in Settings. The relay reconnects and refreshes its binary cache from TridentStack Control on the way back up
• Port 8443 is reachable from the endpoint (open on the host firewall, and published with -p 8443:8443 if the relay runs in Docker)

Agent installs but does not appear in TridentStack Control

• Check that the enrollment key is valid and has not been revoked
• Verify the relay is online and connected to the TridentStack gateway
• On the endpoint, check the agent log for connection errors