Agent Reference
This page documents the TridentStack Control agent's installation paths, configuration files, service details, and supported platforms for each operating system.
Windows Agent
Supported Versions
- Windows 8.1 and later
- Windows Server 2012 R2 and later
On Windows Server 2012 R2 and older, the agent runs as a headless service without the desktop system tray UI. All management features work normally. See Desktop UI below for details.
Installation
The Windows agent is distributed as an MSI installer. Install interactively or via command line:
msiexec /i TridentStack-Control.msi ENROLLMENT_TOKEN="<token>" /qn /norestart
The /qn flag runs a silent install. The /norestart flag prevents an automatic reboot after installation.
File Locations
| Path | Contents |
|---|---|
C:\Program Files\TridentStack Control\ | Agent binaries (read-only after install) |
C:\ProgramData\TridentStack Control\ | Runtime data root |
C:\ProgramData\TridentStack Control\config\ | Configuration files |
C:\ProgramData\TridentStack Control\logs\ | Agent log files |
C:\ProgramData\TridentStack Control\downloads\ | Downloaded update files and pre-staged content |
C:\ProgramData\TridentStack Control\servicedata\ | Service runtime state |
C:\ProgramData\TridentStack Control\cache\ | Cached data |
Configuration Files
All configuration files are located in C:\ProgramData\TridentStack Control\config\:
| File | Purpose |
|---|---|
server.json | Server connection URL, gateway address |
agent.json | Agent identity and configuration |
agent_credentials.dat | Encrypted credentials (DPAPI, SYSTEM-only access) |
debug-settings.json | Debug logging levels and options |
Never manually edit agent_credentials.dat. It is encrypted using Windows DPAPI under the SYSTEM account and cannot be read or modified by user accounts.
Windows Service
| Property | Value |
|---|---|
| Service Name | TridentStack-ControlService |
| Display Name | TridentStack Control Service |
| Account | Local System (SYSTEM) |
| Start Type | Automatic |
| Recovery | Restart on failure |
Common commands:
# Check service status
Get-Service TridentStack-ControlService
# Restart the service
Restart-Service TridentStack-ControlService
# View recent service logs
Get-EventLog -LogName Application -Source "TridentStack*" -Newest 20
Binaries
| Binary | Purpose |
|---|---|
tridentstack-core.exe | Core agent daemon (runs as SYSTEM) |
TridentStack Control.exe | Desktop UI application (runs as current user) |
tridentstack-updater.exe | Self-update handler (runs as SYSTEM) |
Desktop UI (System Tray)
The TridentStack Control agent includes a desktop UI application that runs in the system tray when a user is logged in. The system tray icon provides quick access to agent status, version information, and update notifications.
The desktop UI requires the Microsoft Edge WebView2 Runtime, which is pre-installed on Windows 10 and Windows 11. On Windows Server editions, the agent installer downloads and installs WebView2 automatically during setup.
Legacy OS limitation: On Windows Server 2012 R2 and older, the desktop UI is not available. Microsoft ended WebView2 support for these operating systems in October 2023, and installing the last compatible version (v109) would introduce known security vulnerabilities. The agent installer skips WebView2 installation on these systems to avoid this risk.
The desktop UI is optional. The agent service operates with full functionality without it. All patch management, vulnerability scanning, policy enforcement, and update deployment features work identically whether or not the desktop UI is running. Server endpoints, which typically run without interactive user sessions, are unaffected by this limitation.
Windows Update Management
When the TridentStack Control agent is installed, it automatically configures the endpoint so that the platform is the primary update provider. Native Windows Update scanning and automatic installation are suppressed to prevent conflicts with managed patching.
This is the behavior of Exclusive mode, the default for the Windows Update Management client setting. If you switch that setting to Hybrid, the agent removes the configuration described below and native Windows Update resumes its normal behavior (Windows may then install updates and restart on its own schedule, outside deployment-ring controls). The change is applied live: the agent removes or re-establishes these policies within seconds of the setting being saved. See What Hybrid mode removes below for exactly what the removal does and does not undo, and the Client settings reference for the full comparison and trade-offs.
What the agent configures:
The agent applies these Windows Update policies on startup and re-verifies them every 15 minutes. If the configuration is changed or removed (for example, by a Group Policy refresh, Windows servicing, or a manual edit), the agent reapplies it automatically.
| Windows Version | Mode | Behavior |
|---|---|---|
| Windows 10 2004+, Windows 11, Server 2022+ | Driver-only | Quality, feature, and other updates are blocked from Windows Update. Driver updates are still delivered through Windows Update. All non-driver patching is managed exclusively by TridentStack Control. |
| Server 2019, Server 2016, older Windows 10 | Fully managed | All updates (including drivers) are blocked from Windows Update. TridentStack Control manages every update category. |
Registry policies applied:
All values are written under two machine-policy keys:
HKLM\SOFTWARE\Policies\Microsoft\Windows\WindowsUpdateHKLM\SOFTWARE\Policies\Microsoft\Windows\WindowsUpdate\AU
Because these are machine policies, they appear in Settings > Windows Update (under "View configured update policies" / "Policies set on your device") with a source of "Administrator" and type "Group Policy". This is expected: the agent writes them so that TridentStack Control, not native Windows Update, controls patching.
| Value (key) | Data | Purpose | Applies to |
|---|---|---|---|
WUServer (WindowsUpdate) | http://localhost:8530 | Points update scanning at an unreachable WSUS endpoint | All Windows versions |
WUStatusServer (WindowsUpdate) | http://localhost:8530 | Matching status server | All Windows versions |
UseWUServer (AU) | 1 | Enforces the configured (unreachable) WSUS source | All Windows versions |
AUOptions (AU) | 1 | Disables Automatic Updates | All Windows versions |
NoAutoRebootWithLoggedOnUsers (AU) | 1 | Prevents automatic restarts; TridentStack Control manages reboot timing | All Windows versions |
SetDisableUXWUAccess (WindowsUpdate) | 1 | Hides the "Check for updates" button so end users cannot trigger native scans that conflict with managed patching | All Windows versions |
NoAutoUpdate (AU) | 1 | Fully disables automatic update checks | Fully managed mode only (Server 2016/2019, older Windows 10) |
SetPolicyDrivenUpdateSourceForDriverUpdates (WindowsUpdate) | 0 | Routes driver updates to Windows Update (allowed through) | Driver-only mode (build 19041+) |
SetPolicyDrivenUpdateSourceForQualityUpdates (WindowsUpdate) | 1 | Routes quality updates to the unreachable WSUS (blocked) | Driver-only mode (build 19041+) |
SetPolicyDrivenUpdateSourceForFeatureUpdates (WindowsUpdate) | 1 | Routes feature updates to the unreachable WSUS (blocked) | Driver-only mode (build 19041+) |
SetPolicyDrivenUpdateSourceForOtherUpdates (WindowsUpdate) | 1 | Routes other updates to the unreachable WSUS (blocked) | Driver-only mode (build 19041+) |
UseUpdateClassPolicySource (AU) | 1 | Enables the per-category source policies above | Driver-only mode (build 19041+) |
The agent also removes any stale ScheduledInstall* values under the AU key that would conflict with the managed configuration.
What Hybrid mode removes
Before the agent writes any of the policy values above, it records the value that was already on the device (or records that the value did not exist). Switching to Hybrid undoes the Exclusive configuration by restoring that recorded state, not by blanket-deleting policies:
- Every value the agent set is returned to the exact value it had before the agent applied it. Values that did not exist before TridentStack Control are deleted.
- The agent then restarts the Windows Update service so the change takes effect.
Because Hybrid restores the device's prior state, two things follow:
- Windows Update restrictions that existed before the agent was installed come back exactly as they were. For example, if the device previously had a "notify before download" Automatic Updates policy from an older management tool, that policy is what Hybrid restores.
- Restrictions applied by other systems are never removed. Active Directory or local Group Policy, Microsoft Intune or another MDM, another management tool, or manual registry edits are outside TridentStack Control's ownership, and the agent does not touch them.
If Settings > Windows Update still shows "Some settings are managed by your organization" after switching to Hybrid, the remaining policy comes from one of those other sources, not from TridentStack Control. Common places to check: the local Group Policy editor (Computer Configuration > Administrative Templates > Windows Components > Windows Update, in particular "Configure Automatic Updates"), your MDM console, and any other management or RMM agents installed on the device.
Windows Update itself starts using the restored settings right away: the agent restarts the Windows Update service, and update scans immediately run against Microsoft's servers again. The Windows Update page in Settings is slower to catch up, because it reads a separately cached copy of policy that Windows only rebuilds when it next reprocesses policy (typically within a couple of hours). Until then the page may still show "Some settings are managed by your organization" even though the restriction is gone. Close and reopen the Settings app to see the current state once the cache refreshes.
Microsoft Update service registration: so the platform can deliver updates for other Microsoft products (not just Windows), the agent registers the endpoint with the Microsoft Update service (service ID 7971f918-a847-4430-9279-4a52d1efe18d). This is why "Get updates for other Microsoft products" appears as a managed policy.
Optional content (preview updates): if an update policy enables preview cumulative updates, the agent additionally sets SetAllowOptionalContent = 2 under the WindowsUpdate key.
Clean uninstall:
When the agent is uninstalled, all Windows Update registry changes are restored to their pre-installation values. The agent maintains a registry backup of every value it modifies, so uninstalling returns the endpoint to its original Windows Update configuration.
Administrators do not need to configure Windows Update suppression manually. The agent handles this automatically on every supported Windows version. If your organization uses Active Directory Group Policy to manage Windows Update settings, be aware that GPO may override the agent's configuration on domain-joined endpoints. In that case, configure your GPO to align with the agent's settings or exclude managed endpoints from the WU GPO.
Self-Update Process
When an update is available, the agent:
- Downloads the new MSI to
C:\ProgramData\TridentStack Control\downloads\agent-updates\ - Validates the file integrity
- Executes the MSI upgrade silently
- The service restarts automatically with the new version
Application Updates Note
Application updates (third-party software management) are supported on all Windows versions. On modern systems (Windows 10+, Server 2019+), the agent uses the native package manager when available. On legacy systems (Server 2016, Windows 8.1), the agent downloads and executes installers directly from the synced catalog.
Linux Agent
Supported Distributions
Primary support (DEB packages):
- Ubuntu 20.04 LTS and later
- Debian 12 and later
Detected and supported (package manager integration):
- RHEL 8 and later
- CentOS Stream 8 and later
- Rocky Linux 8 and later
- AlmaLinux 8 and later
- Fedora (latest stable)
- Amazon Linux 2 and later
The installer script automatically detects the distribution and package manager.
Installation
Install using the one-line installer:
curl -fsSL https://get.tridentstack.com/linux | sudo bash -s -- --key <ENROLLMENT_TOKEN>
The installer downloads the latest DEB package, installs it, configures the agent, and starts the service.
Installer options:
| Flag | Purpose |
|---|---|
--key <TOKEN> | Install with enrollment token (new installation) |
--upgrade | Upgrade an existing installation to the latest version |
--uninstall | Remove the agent and all configuration |
| (no flags) | Repair/heal an existing installation (preserves credentials) |
File Locations
| Path | Contents |
|---|---|
/opt/tridentstack/bin/ | Agent binary |
/etc/tridentstack/ | Configuration files (root-only, mode 700) |
/var/log/tridentstack/ | Agent log files |
/var/lib/tridentstack/ | Runtime state and cache (root-only, mode 700) |
Configuration Files
All configuration files are located in /etc/tridentstack/:
| File | Purpose |
|---|---|
agent.json | Agent identity and configuration |
credentials.enc | Encrypted agent credentials |
Systemd Service
| Property | Value |
|---|---|
| Service Name | tridentstack-agent |
| Binary | /opt/tridentstack/bin/tridentstack-agent daemon |
| Account | root |
| Start Type | Enabled (starts on boot) |
| Recovery | Always restart (10-second delay) |
Security hardening applied via systemd:
ProtectHome=yes(cannot access /home)PrivateTmp=yes(isolated /tmp)ProtectKernelTunables=yesProtectControlGroups=yes
Common commands:
# Check service status
sudo systemctl status tridentstack-agent
# Restart the service
sudo systemctl restart tridentstack-agent
# View recent logs
sudo journalctl -u tridentstack-agent -n 50
# Follow logs in real time
sudo journalctl -u tridentstack-agent -f
Self-Update Process
When an update is available, the agent:
- Downloads the new binary
- Replaces the binary at
/opt/tridentstack/bin/tridentstack-agent - The systemd service restarts automatically with the new version
Linux-Specific Features
- Package update detection: The agent queries apt/dnf for available package updates and reports them as pending updates, including whether each update is a security patch.
- Docker enrichment: Ports held by
docker-proxyare enriched with the associated container name and image. - Reboot detection: The agent checks for
/var/run/reboot-requiredto determine if the system needs a restart after updates.
macOS Agent
Supported Versions
- macOS 14.0 (Sonoma) and later
- Apple Silicon (M-series) and Intel, delivered as a single universal binary
Installation
Install with the one-line installer (run with sudo):
curl -fsSL https://control.tridentstack.com/api/agent-packages/installer/macos/install | sudo bash -s -- --key <ENROLLMENT_TOKEN>
The script downloads the latest macOS package, verifies its SHA256 hash, installs it with the standard macOS installer (.pkg), configures the agent with your enrollment token, and registers it automatically. The package is signed and notarized, so Gatekeeper accepts it without manual steps. See Agent Enrollment for the full install steps.
Installer options:
| Flag | Purpose |
|---|---|
--key <TOKEN> | Install with enrollment token (new installation) |
--uninstall | Remove the agent and all configuration |
File Locations
| Path | Contents |
|---|---|
/usr/local/sbin/tridentstack-agent | Agent binary |
/Library/Application Support/TridentStack/ | Configuration and credentials |
/var/lib/tridentstack/ | Runtime state and staged installs |
/var/log/tridentstack/ | Agent log files (agent.log) |
Configuration Files
Located in /Library/Application Support/TridentStack/ (owned by root:wheel, mode 0600):
| File | Purpose |
|---|---|
agent.json | Agent identity and configuration |
credentials.json | Encrypted agent credentials |
launchd Services
The macOS agent runs as two launchd jobs:
| Job | Type | Account | Purpose |
|---|---|---|---|
com.tridentstack.agent | LaunchDaemon | root | The agent daemon: telemetry, inventory, updates, and policy enforcement. Runs whether or not a user is logged in. |
com.tridentstack.ui | LaunchAgent | logged-in user | The menu bar status app. Loads in a user session and is optional; the daemon has full functionality without it. |
Common commands:
# Confirm the daemon is running (look for a PID, not a dash, in the first column)
sudo launchctl list | grep tridentstack
# Follow the agent log
tail -f /var/log/tridentstack/agent.log
Self-Update Process
When an update is available, the agent downloads the latest macOS package, verifies it, installs it with the system installer, and the daemon relaunches on the new version. No manual action is required.
macOS-Specific Features
- System telemetry and software inventory: hardware, OS version, installed applications, and update status.
- Vulnerability detection: installed software and OS version matched against CVE data, with System and Software source tabs.
- Compliance: evaluated against the CIS Apple macOS Sonoma Benchmark.
- Application updates: third-party applications are installed and kept current through the macOS package manager integration, using the same catalog and configurations as other platforms. See Application Updates.
- Microsoft Office updates: managed through Microsoft AutoUpdate (MAU). See System Updates.
- FileVault status: disk-encryption state is reported in system telemetry.
Operating-system update management for macOS (installing Apple system updates and major OS upgrades through a policy) is in active development. The current release manages Microsoft Office updates, compliance, vulnerability detection, and inventory on macOS.
Network Requirements
Windows, macOS, and Linux agents require:
| Requirement | Details |
|---|---|
| Outbound port 443 | gRPC connection to gateway.tridentstack.com (TLS encrypted) |
| No inbound ports | The agent initiates all connections. No firewall rules needed for inbound traffic. |
| Proxy support | The agent respects system proxy settings for outbound connections |
The agent maintains a persistent gRPC connection to the gateway for real-time command delivery and telemetry reporting.
Agent Version
Check the installed agent version:
# Windows
reg query "HKLM\SOFTWARE\TridentStack\Control" /v Version
# Linux
/opt/tridentstack/bin/tridentstack-agent --version
# macOS
/usr/local/sbin/tridentstack-agent --version
The agent version is also visible in the TridentStack Control console on the agent detail page under the System tab.