Agent Installation Guide
Complete instructions for installing, configuring, and troubleshooting the DeskTrust desktop agent on Windows, macOS, and Linux. The agent is the lightweight software that runs on employee computers to enable employee screen monitoring, screenshot capture, and productivity tracking.
Agent Overview
The DeskTrust agent (currently v2.8) is a lightweight background service that:
- Captures screenshots at the configured interval (5 seconds to 5 minutes).
- Tracks active applications and window titles.
- Detects idle time, screen lock, and work hour boundaries.
- Sends keepalive pings to prevent false offline status.
- Opens the native desktop portal for employee interaction.
- Auto-updates itself silently — no manual maintenance required.
Important: The agent no longer uses a system tray icon. It runs completely in the background. The native desktop portal (localhost:19847/portal via Edge --app mode) provides the employee interface.
System Requirements
Windows
- Windows 10 or Windows 11
- 4 GB RAM (minimum)
- 100 MB free disk space
- .NET Framework 4.7.2 or later
- Microsoft Edge (for desktop portal)
- Administrator privileges for installation
macOS
- macOS 12 Monterey or later
- 4 GB RAM (minimum)
- 100 MB free disk space
- Screen Recording permission
- Accessibility permission
- Admin password for installation
Linux
- Ubuntu 20.04+ or Debian 11+
- 4 GB RAM (minimum)
- 100 MB free disk space
- X11 or Wayland display server
- sudo/root access for installation
- systemd (for service management)
Windows Installation
Step 1: Download the Installer
Log in to the DeskTrust admin dashboard and navigate to Employees. Click on the employee you want to install the agent for, then click Download Agent to get DeskTrustAgent-Setup.exe. The download includes the employee Agent Key pre-configured.
Step 2: Run the Installer
Right-click the installer and select Run as administrator. Follow the installation wizard:
- Accept the license agreement.
- Confirm the installation directory (default: C:\Program Files\DeskTrust).
- Verify or enter the Server URL (your company DeskTrust URL).
- Verify or enter the Agent Key (unique per employee).
- Click Install and wait for completion.
Step 3: Verify Installation
The agent installs as a Windows service called DeskTrust Agent and starts automatically. You can verify it is running by checking Windows Services (services.msc) or looking for the employee to appear as Online in the admin dashboard.
Step 4: Desktop Portal
The native desktop portal will automatically appear as a popup window. This is the employee interface for checking status, pausing, and managing their session. The portal runs via Microsoft Edge in app mode (localhost:19847/portal) and does not require the employee to open a browser.
macOS Installation
Step 1: Download the Package
Download DeskTrustAgent.pkg from the admin dashboard for the specific employee.
Step 2: Run the Installer
Double-click the .pkg file and follow the macOS installer prompts. You will need to enter the admin password. The installer will place the agent in /Library/DeskTrust/ and register it as a launchd service.
Step 3: Grant Permissions
macOS requires explicit permissions for screen capture. After installation:
- Go to System Settings > Privacy & Security > Screen Recording.
- Enable DeskTrust Agent in the list.
- Go to Privacy & Security > Accessibility.
- Enable DeskTrust Agent there as well.
- You may need to restart the agent or reboot for permissions to take effect.
Note: On macOS, DeskTrust uses AppleScript for active window detection, which provides more accurate app tracking than other methods. The Accessibility permission is required for this.
Step 4: Configure
Edit the configuration file at /Library/DeskTrust/config.json to set the Server URL and Agent Key if they were not pre-configured in the download.
Step 5: Start the Agent
The agent starts automatically via launchd. To manually control it:
sudo launchctl load /Library/LaunchDaemons/com.desktrust.agent.plist
sudo launchctl unload /Library/LaunchDaemons/com.desktrust.agent.plist
Linux Installation
Step 1: Download the Package
Download the .deb package from the admin dashboard for the specific employee.
Step 2: Install
sudo dpkg -i desktrust-agent_2.6_amd64.deb
sudo apt-get install -f # Install any missing dependencies
Step 3: Configure
Edit the configuration file:
sudo nano /etc/desktrust/config.json
Set the following fields:
{
"serverUrl": "https://your-company.desktrust.com",
"agentKey": "your-agent-key-here",
"screenshotInterval": 10,
"workHoursStart": "09:00",
"workHoursEnd": "17:00"
}
Step 4: Start the Service
sudo systemctl enable desktrust-agent
sudo systemctl start desktrust-agent
sudo systemctl status desktrust-agent # Verify it is running
Configuration Reference
The agent configuration file (config.json) supports the following settings:
| Setting | Description | Default |
|---|---|---|
| serverUrl | Your DeskTrust server URL | Required |
| agentKey | Unique key for this employee | Required |
| screenshotInterval | Seconds between captures | 10 |
| workHoursStart | Work day start time (24h) | 09:00 |
| workHoursEnd | Work day end time (24h) | 17:00 |
| idleTimeout | Seconds before Away status | 300 |
| autoUpdate | Enable auto-update | true |
Auto-Update
The DeskTrust agent automatically checks for updates and installs them in the background. This ensures all employees are always running the latest version with bug fixes and new features.
- Updates are downloaded and installed silently — no employee action required.
- The agent restarts itself after updating with minimal interruption (a few seconds).
- Auto-update can be disabled in config.json by setting
autoUpdateto false (not recommended). - The current agent version is v2.8.
Troubleshooting
Employee shows as Offline in the dashboard
- Verify the agent service is running (Windows Services, launchd, or systemctl).
- Check that the Server URL and Agent Key are correct in config.json.
- Ensure the employee computer has internet access and can reach your DeskTrust server.
- Check if it is outside the configured work hours (agent auto-pauses).
- Look at agent logs for errors (Windows: Event Viewer; macOS/Linux: /var/log/desktrust/).
Screenshots are not being captured (macOS)
- Go to System Settings > Privacy & Security > Screen Recording and ensure DeskTrust is enabled.
- Try removing and re-adding the permission, then restart the agent.
- On macOS Ventura+, you may need to restart the computer after granting permissions.
Desktop portal does not appear
- Ensure Microsoft Edge is installed (required for the native popup).
- Try accessing localhost:19847/portal directly in any web browser as a fallback.
- Check that the agent service is running — the portal is served by the agent.
- On macOS/Linux, the employee can access their portal via the web browser at their company DeskTrust URL.
Agent not auto-updating
- Verify autoUpdate is set to true in config.json.
- Ensure the agent can reach the update server (check firewall rules).
- Manually download and reinstall the latest agent as a workaround.
High CPU or memory usage
- This is rare. Try increasing the screenshot interval to reduce capture frequency.
- Restart the agent service.
- Ensure you are running the latest agent version (v2.8).
- Contact support if the issue persists.
Uninstallation
Windows
Open Settings > Apps > Installed Apps, find DeskTrust Agent, and click Uninstall. Alternatively, run the uninstaller from C:\Program Files\DeskTrust\uninstall.exe.
macOS
Run: sudo /Library/DeskTrust/uninstall.sh
Linux
Run: sudo dpkg -r desktrust-agent
Need help with installation?
Our support team can walk you through setup or help troubleshoot any issues.
Contact Support