Setting Up a Relay

Step 1: Create the relay

1. Go to Settings > Relays in TridentStack Control
2. Click Set Up a Relay
3. Enter a name for the relay (e.g. "Office Relay" or "DC-East")
4. Click Create Relay

Step 2: Install the relay

After creating the relay, the setup wizard shows a one-line install command. Choose your platform:

Linux

Copy and run the command shown in the wizard. It looks like:

curl -fsSL https://control.tridentstack.com/relay/install | sudo bash -s -- --token <TOKEN>

This downloads the relay binary, enrolls it with TridentStack Control, creates a systemd service, and starts the relay.

Windows

The relay runs on Windows through Docker Desktop. Follow the Docker instructions below, using the token from the wizard.

Docker

docker run -d --name tridentstack-relay \
  -e RELAY_TOKEN=<TOKEN> \
  -p 50051:50051 \
  -p 8080:8080 \
  -p 8443:8443 \
  -v tridentstack-relay-config:/etc/tridentstack-relay \
  -v tridentstack-relay-data:/var/lib/tridentstack-relay \
  --restart unless-stopped \
  --log-driver json-file --log-opt max-size=10m --log-opt max-file=5 \
  ghcr.io/tridentstack/tridentstack-relay:latest

The -p flags publish the relay's listening ports from the container to the host so agents on your LAN can reach them: 50051 for agent connections, 8080 for the certificate bootstrap, and 8443 for air-gapped enrollment. Publishing 8443 now (even if you do not use air-gapped enrollment yet) means you can enable it later without recreating the container. Container port publishing is separate from your host firewall: you still need the host firewall to allow these ports (see Firewall rules below).

The volume mounts preserve the relay's enrollment state, certificates, and message buffer across container restarts. Without them, restarting the container would require re-creating the relay in TridentStack Control.

The logging flags cap the container's logs at 5 files of 10 MB each, 50 MB total. --log-driver json-file selects Docker's file-based log driver, and the --log-opt values bound its size. Docker's default logging has no size limit, so on a long-running relay the log would otherwise grow until it fills the host disk. If your host already defaults to the json-file driver, the --log-driver flag is harmless. If you run the relay with Docker Compose, set the equivalent logging options on the service:

    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "5"

You can optionally set a custom relay name with -e RELAY_NAME="Office Relay". If omitted, the container hostname is used.

Step 3: Verify the relay is online

Return to Settings > Relays. The relay's status changes from "Pending" to "Online" once it connects. This usually takes a few seconds.

Step 4: Connect agents through the relay

Once the relay is online, the relay card shows agent install commands under "Connect Agents." These commands include the relay's address and certificate fingerprint.

For Linux agents:

curl -fsSL https://control.tridentstack.com/linux | sudo bash -s -- \
  --key <ENROLLMENT_KEY> \
  --relay <RELAY_IP> \
  --relay-ca-fingerprint <FINGERPRINT>

Replace <ENROLLMENT_KEY> with an agent enrollment key from your TridentStack Control dashboard.

Firewall rules

Ensure these ports are accessible on the relay server:

Port	Protocol	Direction	Purpose
50051	TCP	Inbound (from agents)	gRPC agent connections
8080	TCP	Inbound (from agents)	Certificate bootstrap (first connection only)
443	TCP	Outbound (to gateway.tridentstack.com)	Upstream connection to TridentStack