Agent Enrollment

Agents are lightweight services that run on your endpoints (servers, workstations, laptops) and communicate with TridentStack Control over gRPC. Once enrolled, an agent continuously reports system information, software inventory, patch status, and vulnerability data back to the platform, and receives commands for update installation, policy enforcement, and compliance evaluation.

Each agent maintains a persistent connection to the TridentStack Control gateway, so changes you make in the console (approving updates, assigning policies, triggering scans) are delivered to endpoints in real time.

Prerequisites

Supported operating systems

Platform	Minimum Version
Windows Server	2012 R2 and later
Windows Desktop	8.1 and later
Ubuntu	20.04 and later
Debian	12 and later
RHEL / CentOS Stream	8 and later
Rocky Linux / AlmaLinux	8 and later
Fedora	Latest stable
Amazon Linux	2 and later
macOS	14.0 (Sonoma) and later

note

All features, including application updates, are supported on all Windows versions listed above. The macOS agent provides system telemetry, software inventory, vulnerability detection, compliance evaluation, application updates, and Microsoft Office update management in the current release. Operating-system update management for macOS is in development.

Network requirements

Agents require outbound access on port 443/TCP to reach TridentStack Control. No inbound ports need to be opened on the endpoint.

The agent connects to two TridentStack Control hostnames, both on port 443:

Host	Purpose
gateway.tridentstack.com	Persistent command channel (gRPC over HTTP/2) that delivers approvals, policy assignments, and scan requests in real time
control.tridentstack.com	Enrollment, inventory and telemetry uploads, agent self-update downloads, and log collection (HTTPS/REST)

TLS inspection must be exempted for the command channel

The connection to gateway.tridentstack.com requires direct TLS passthrough. As a security measure, the agent verifies that the certificate presented by the gateway chains to the expected public certificate authority and refuses any connection where the certificate has been replaced, including replacement by your own security appliance. Allowlisting the hostname is not enough on its own: if a firewall, secure web gateway, or cloud security service (for example Cisco Umbrella, Zscaler, or a UTM appliance) performs HTTPS/SSL inspection on this connection, the agent will reject it and the command channel will never come up. Add gateway.tridentstack.com to your inspection exemption/bypass list. The command channel also connects directly and does not use a configured web proxy, and it requires HTTP/2, which some older proxy appliances do not support.

Traffic to control.tridentstack.com is ordinary HTTPS and tolerates inspection and proxies normally.

How this looks when it is misconfigured: the endpoint enrolls successfully and appears in the console, but stays in the Onboarding state indefinitely and never shows as Online. Enrollment and check-ins use control.tridentstack.com (which works through inspection), while the command channel to gateway.tridentstack.com is silently broken. When TridentStack Control can determine the cause, the endpoint's detail page shows a banner naming the likely reason (for example, a security appliance intercepting the connection, including the certificate authority it presented) and what your network team needs to allow, and the Endpoints list flags the affected endpoint. To confirm manually, open https://gateway.tridentstack.com in a browser on the affected endpoint and view the certificate: if the issuer is anything other than Let's Encrypt, your network is intercepting the connection and an inspection exemption is needed.

Why the gateway connection cannot be inspected

This is a deliberate security control, and it matches the posture used by other security-sensitive endpoint and management agents. If your team inspects all outbound traffic by policy, here is the reasoning to bring to a security review before granting the exemption.

The command channel to gateway.tridentstack.com is the most sensitive connection the agent makes. It carries the instructions the agent carries out with system-level privileges, including the agent's own updates. If that channel could be impersonated, whoever impersonated it could direct agents across your fleet. To prevent that, the agent pins the connection to the public certificate authority the gateway actually uses and refuses any certificate that has been substituted, whether by a misissued or compromised public certificate or by an inspection appliance re-signing the traffic with its own authority. An SSL-inspection appliance presents its own certificate in place of the real one by design, so the agent treats it the same as any other substitution and declines to bring the channel up. This is what stops a network-positioned party from reading or injecting commands, or pushing a malicious update, on the one channel where that would matter most.

The exemption is deliberately narrow. Only this single command channel is pinned. Everything else the agent sends, enrollment, inventory and telemetry uploads, update downloads, and log collection, goes to control.tridentstack.com over ordinary HTTPS and continues to pass through your inspection and proxy stack as usual. Exempting gateway.tridentstack.com therefore removes only one known vendor endpoint from inspection, not the bulk of the agent's traffic. The integrity of anything the agent downloads and installs is verified independently of the transport, so the exemption does not create a way to tamper with what the agent runs. In practice this is the same kind of single-hostname bypass most endpoint protection and management agents require for their own management channels.

Enrollment tokens

Each tenant has an enrollment token that is automatically created when your account is provisioned. The token is pre-filled into the quick install commands on the Agent Installers page, so in most cases you do not need to copy it manually.

To view or regenerate your token:

1. Log in to TridentStack Control.
2. Navigate to Settings in the left sidebar.
3. Select the Agent Installers tab.
4. Your enrollment token and ready-to-use install commands are displayed on the page.

warning

Treat your enrollment token like a password. Anyone with the token can register agents to your tenant. If you suspect a token has been compromised, regenerate it from the Agent Installers page.

Download a pre-filled install script

If you would rather review the install script before running it, or you are installing on a machine where piping a command straight into a shell is not an option, use the Download Script button on each platform's card. The downloaded script comes pre-filled with your enrollment token, so you can copy it to the endpoint, run it, and the agent installs and registers automatically without passing the token by hand.

Enrollment flow

The following diagram shows what happens when you install and start an agent:

Windows installation

Quick install (recommended)

The fastest way to install the agent is the PowerShell one-liner shown on the Agent Installers page. Open PowerShell as Administrator and run the command displayed there. It downloads the MSI, installs silently with your enrollment token, and cleans up.

The command is pre-filled with your enrollment token, so no manual token entry is needed.

tip

The quick install command is ready to copy from Settings > Agent Installers. Just click the copy button next to the PowerShell command.

note

Installing on Windows Server 2016, Windows Server 2012 R2, or Windows 8.1? Turn on the Older Windows toggle next to the Quick Install command first. Those systems need an extra step to connect securely, and the toggle adds it for you. Without it, the command fails with "Could not create SSL/TLS secure channel."

MSI installer (scripted or GPO)

For SCCM, Intune, Group Policy, or other management tools, download the MSI from the Agent Installers page and deploy with msiexec:

msiexec /i TridentStack-Control.msi ENROLLMENT_TOKEN="<your-token>" /qn /norestart

The /qn flag runs the installer silently with no UI. The /norestart flag prevents automatic reboots.

warning

If you regenerate your enrollment token, any previously distributed install commands using the old token will fail to enroll new agents. Update your deployment scripts with the new token after regeneration. Existing agents already enrolled are not affected.

Linux installation

Run the following one-liner as root (or with sudo):

curl -fsSL https://control.tridentstack.com/api/agent-packages/installer/linux/install | sudo bash -s -- --key <your-token>

This script will:

1. Detect your distribution and architecture.
2. Download the appropriate .deb package.
3. Install the TridentStack Control agent as a systemd service.
4. Configure the agent with your enrollment token.
5. Start the service immediately.

tip

Agents automatically update to the latest version. No manual updates are needed after initial enrollment.

macOS installation

note

macOS support requires macOS 14.0 (Sonoma) or later. Both Apple Silicon (M-series) and Intel Macs are supported via a universal binary.

Run the following one-liner with sudo:

curl -fsSL https://control.tridentstack.com/api/agent-packages/installer/macos/install | sudo bash -s -- --key <your-token>

This script will:

1. Download the latest macOS agent package.
2. Verify the download's SHA256 hash before installing.
3. Configure the agent with your enrollment token.
4. Install the agent using macOS's standard installer (.pkg format).
5. Register the agent with TridentStack Control automatically.

tip

Agents automatically update to the latest version. No manual updates are needed after initial enrollment.

The macOS package is signed and notarized, so Gatekeeper installs it without warnings or manual approval steps.

Enabling macOS update installation (Apple Silicon)

On Apple Silicon Macs, Apple requires authentication by a local administrator account before the system will install macOS updates or OS upgrades. The TridentStack Control agent passes these credentials to Apple's installer when it runs a macOS update on your behalf. Without them, macOS update and upgrade installations fail immediately with a message that installer credentials are not configured.

To enable macOS update installation, add a local administrator account to the agent configuration file at /Library/Application Support/TridentStack/agent.json. Add these two keys to the existing JSON (do not replace the file):

{
  "installerAdminUser": "localadmin",
  "installerAdminPassword": "account-password"
}

Then restart the agent so it picks up the change:

sudo launchctl kickstart -k system/com.tridentstack.agent

A few notes on this configuration:

• The account must be a local administrator on the Mac. On Apple Silicon this account authorizes the update at the firmware level, so it must be a regular local admin (accounts created during macOS setup qualify), not a network-only account.
• agent.json is owned by root with 0600 permissions, so the credentials are readable only by root.
• The password is automatically redacted from any diagnostic logs collected through TridentStack Control.
• Intel Macs do not require these credentials; setting them there is harmless.

Verifying the agent is running

After installation, confirm the agent service is active:

sudo launchctl list | grep tridentstack

You can also follow the live agent log:

tail -f /var/log/tridentstack/agent.log

Uninstalling

To remove the agent from a macOS endpoint, run:

curl -fsSL https://control.tridentstack.com/api/agent-packages/installer/macos/install | sudo bash -s -- --uninstall

Verifying enrollment

After installation, the agent should appear in TridentStack Control within 60 seconds:

1. Navigate to Agents > Endpoints in the left sidebar.
2. Look for the new endpoint by hostname.
3. Confirm the Status column shows Online.

Once online, the agent begins its first telemetry refresh, reporting system information, installed software, and applicable updates. This initial data collection typically completes within a few minutes.

Troubleshooting

Agent does not appear in Endpoints

If the agent does not show up after 60 seconds, work through these checks in order:

1. Verify the agent service is running.

On Windows:

Get-Service 'TridentStack-ControlService'

The service status should be Running.

On Linux:

sudo systemctl status tridentstack-agent

The service should show active (running).

On macOS:

sudo launchctl list | grep tridentstack

The entry should be present with a PID (not a dash) in the first column.

2. Check network connectivity.

Confirm the endpoint can reach the TridentStack Control gateway on port 443. Test with:

curl -v https://gateway.tridentstack.com

If the connection times out or is refused, check your firewall rules and proxy configuration.

If the endpoint enrolled and appears in the console but stays in the Onboarding state and never comes Online, the command channel to gateway.tridentstack.com is being blocked or intercepted while regular API traffic still works. This is almost always HTTPS/SSL inspection or a forced proxy on that connection: see the TLS inspection note under Network requirements. Check the endpoint's detail page first: when TridentStack Control can determine the cause, it shows a banner naming the specific reason and the fix. To confirm manually, open https://gateway.tridentstack.com in a browser on the endpoint and check the certificate issuer; anything other than Let's Encrypt means the connection is being intercepted and needs an inspection exemption.

3. Verify the enrollment token.

An expired or invalid token will prevent registration. Go to Settings > Agent Installers and confirm the token you used matches the one displayed. If in doubt, regenerate the token and reinstall the agent with the new value.

4. Check agent logs.

On Windows, logs are located at:

C:\ProgramData\TridentStack Control\logs\

On Linux, use journalctl:

sudo journalctl -u tridentstack-agent --no-pager -n 50

On macOS, logs are located at:

tail -n 50 /var/log/tridentstack/agent.log

Look for connection errors, authentication failures, or TLS handshake issues.

Agent shows as Offline

If an agent previously appeared but now shows Offline:

• The endpoint may be powered off or disconnected from the network.
• A firewall change may be blocking outbound traffic on port 443.
• The agent service may have stopped. Restart it and check logs for errors.