Installation manuals / Agent

Agent Installation

Install PortGuard Agent on each endpoint managed by your Console. Choose the endpoint's operating system below.

Before installing

Have a running Console and its Server URL, for example http://192.168.1.10. Use the address that opens Console in your browser (port 80); backend port 8100 is internal. See the Console installation manual if the server is not installed yet.

Agent and Console have separate packages and version numbers. Use the release notes supplied with your Agent package.

Agent installers by platform

Endpoint OSAvailabilityInstallation
Windows x64Agent 0.1.17 · TestingWindows instructions
Linux x86-64 / ARM640.1.7 Stable · 0.1.8 TestingInstall with curl
macOS 14+ · Apple Silicon / Intel0.1.16 Testing · hardware acceptance pendingTerminal installer

PortGuard supports mixed Windows, Linux and macOS fleets through one Console. Platform releases can differ in feature coverage and device-control behavior. Central log forwarding is configured in Console and includes Agent activity received by it; see the Console log-server guide. The current Testing Console release is required for RFC 5424 forwarding.

Windows Agent Testing

Run the complete block in PowerShell. Downloads are stored in your user Downloads folder, so the current directory can be System32 or any other directory. Download directly from PowerShell using curl.exe, verify the checksum, then run the installer. Windows x64 and administrator access are required. The package includes its .NET runtime. This Testing package is unsigned; confirm its official URL and checksum.

PowerShell · accepts the administrator prompt
$ErrorActionPreference = 'Stop'
$base = 'https://portguard.kamindo.co/downloads/agent/windows/0.1.17'
$file = 'PortGuardAgent-0.1.17-windows-x64.exe'
$folder = Join-Path $env:USERPROFILE 'Downloads\PortGuard'
New-Item -ItemType Directory -Path $folder -Force | Out-Null
$installer = Join-Path $folder $file
$checksum = "$installer.sha256"
curl.exe --fail --location --retry 3 --output "$installer" "$base/$file"
if ($LASTEXITCODE -ne 0) { throw 'Installer download failed' }
curl.exe --fail --location --retry 3 --output "$checksum" "$base/$file.sha256"
if ($LASTEXITCODE -ne 0) { throw 'Checksum download failed' }
$expected = ((Get-Content -LiteralPath $checksum -Raw).Trim() -split '\s+')[0]
if ($expected -notmatch '^[a-fA-F0-9]{64}$') { throw 'Invalid checksum file' }
if ((Get-FileHash -LiteralPath $installer -Algorithm SHA256).Hash -ne $expected) { throw 'Checksum mismatch' }
Write-Host 'Download verified. Complete the installer wizard and click Finish.'
$process = Start-Process -FilePath $installer -WorkingDirectory $folder -Verb RunAs -Wait -PassThru
if ($process.ExitCode -ne 0) { throw "Installer exit $($process.ExitCode). Check $env:TEMP\PortGuard-install.log and PortGuard-install-error.txt" }
$service = Get-Service -Name PortGuardAgent -ErrorAction Stop
Write-Host "Installer completed. Agent service: $($service.Status). Approve the endpoint in Console."

Enter the Console address in the wizard. For an IP/HTTP installation, explicitly select Allow HTTP on a trusted network. The Agent connects outbound; no Agent inbound port or manual enrollment JSON transfer is required. A Console supporting administrator approval is required.

Open Console → Endpoints → Connected agents, compare the installation UUID shown in the tray, and approve the device. A pending device occupies no license seat. Approval allocates one seat; its accepted heartbeat then marks it online. Verification and lifecycle instructions.

Installer window, tray and troubleshooting

A 100% download bar confirms only that the file arrived. Accept the Windows administrator prompt, complete the installer window (check the taskbar or Alt+Tab if it is behind PowerShell), and click Finish. PowerShell waits until installation completes, then displays the service status. Do not include Markdown backslashes or the PS>/>> prompts when copying.

The tray is registered for every sign-in and startup is requested immediately in the signed-in desktop session, without restarting Windows. Windows may put the icon under the notification-area arrow. Open Start → PortGuard Agent to show its status window. On unattended machines without a signed-in desktop, the tray appears at the next sign-in; the Agent service runs independently.

If installation reports an error, keep %TEMP%\PortGuard-install.log and %TEMP%\PortGuard-install-error.txt for troubleshooting. A direct EXE download is also available. Native Windows installation, tray startup and sign-in acceptance for this release must be completed by the testing team.

Windows Agent lifecycle

Install or upgrade

Use the terminal download commands in the Windows tab. Rerun the new installer with the same Console address to upgrade. The installer stops the service and tray before replacing binaries; installation ID, enrolled Agent ID, token, heartbeat sequence, policy and command journal are retained in ProgramData. Do not copy enrolled state into a golden image.

The service starts automatically. The tray starts at sign-in, or open C:\Program Files\PortGuard\PortGuardAgentTray.exe. It shows connection state, installation UUID, last accepted heartbeat and USB policy. Configuration changes require administrator access. HTTP traffic is not encrypted; choose HTTPS only when your Console has valid TLS configured.

Verify the Agent

PowerShell · Administrator
Get-Service PortGuardAgent
Get-Content "$env:ProgramData\PortGuard\agent-status.json"
& "$env:ProgramFiles\PortGuard\PortGuardAgent.exe" status

Before approval, expect pending_approval. After approval, check online and the heartbeat timestamp. Heartbeat, command/result handling and disk collection run independently. Disk capacity refreshes about once per minute and includes internal mounted volumes. Temporary network/authentication failures preserve identity; revoked credentials require administrator recovery, not automatic reenrollment.

USB control and limits

Only USB storage identified through USBSTOR or a verified USB parent chain is targeted. Block, Allow and Status report native PnP evidence. A mounted drive can be blocked: Windows performs its normal PnP removal checks. If Windows rejects the operation, close files and applications using that drive and retry. The Agent never forces device removal or automatically reboots. A restart-required response remains unverified until Windows confirms the target state. Hotplug enforcement uses a periodic scan, so this is not a kernel-level guarantee that no access occurs before blocking. USBSTOR flash storage is tested on Windows 10. UASP follows the same verified USB-parent selection and Block/Allow path; physical UASP hardware acceptance is still pending. Internal NVMe/SATA and USB keyboards are excluded.

Change Console address or rotate credentials

Open the tray as administrator and save the new Console origin. An enrolled device checks the pinned Console before accepting an address change. A different Console database needs a deliberate migration; do not delete state to bypass the identity check. To request credential rotation from an elevated terminal:

PowerShell · Administrator
& "$env:ProgramFiles\PortGuard\PortGuardAgent.exe" rotate-token

Check the service status after rotation. The old/new recovery pair remains private until the new token has been verified. Never share ProgramData\PortGuard\private.

Uninstall and reinstall

Use Windows Apps & Features → PortGuard Agent → Uninstall, or run the installed uninstall.exe as administrator. Uninstall first restores USB storage and stops if restoration cannot be verified. Identity is retained for reinstall. Retire the endpoint in Console separately when it should release its seat; uninstall alone does not release it.

Agent support

Include your Agent package version, endpoint OS, Console Server URL and error message when reporting a problem. Keep passwords and tokens out of shared logs. For server installation or GUI updates, use the Console manual.