Agent issues

Troubleshooting guide for Alpamon agent issues.

Agent installation failure

Incorrect OS family selection

Selecting the wrong OS family for your server during agent installation can cause installation to fail.

The default installation script works regardless of OS type, so installation usually succeeds. However, when installing the agent manually, the installation script differs by OS family, so selecting the wrong OS will cause installation to fail.

What to do:

  1. Verify the server’s actual OS family:

    • Debian family: Ubuntu, Debian, etc.
    • Red Hat family: RHEL, CentOS, Fedora, Amazon/Rocky/Oracle Linux, etc.
    • macOS: macOS 11 or later
    • Windows: Windows Server 2019 / 2022 / 2025, Windows 10 1803+, Windows 11

  2. When registering the server on the Register a server page, select the correct OS family

  3. If using a manual installation script, install the agent using a script that matches the selected OS family:

    • Debian family: script that includes apt-get install -y alpamon
    • Red Hat family: script that includes yum install -y alpamon
    • macOS: script that includes brew install alpamon
    • Windows: PowerShell script that runs alpamon.exe register

  4. If the server was registered with the wrong OS family, delete the server and register it again with the correct OS family

Workspace migration

If you register a server from another workspace to a new workspace without removing the agent first, the agent may continue to be connected to the old workspace. In this case, server connection is not possible in the new workspace.

What to do:

  1. In old workspace, delete server with automatic agent removal enabled (removes previously installed agent from server)

  2. If cannot access old workspace, refer to Remove server and remove agent manually

  3. In new workspace, perform server registration and agent installation from scratch

Windows agent issues

Service won’t start

If the alpamon Windows Service fails to start, inspect the service state and the agent log first.

sc.exe query alpamon
Get-Content "$env:ProgramData\alpamon\log\alpamon.log" -Tail 100

For Service Control Manager errors that don’t appear in the agent log (for example, the binary is missing or unreadable), open Event Viewer and check Windows Logs → System for entries from Service Control Manager, plus Applications and Services Logs for any alpamon entries.

Access denied during alpamon register or service operations

Both alpamon register and the service control commands (sc.exe, Restart-Service) require Administrator privileges. Re-run from an elevated PowerShell (Run as Administrator). alpamon register surfaces an elevation hint when it cannot copy the binary to C:\Program Files\alpamon\.

If you see ERROR_SHARING_VIOLATION while reinstalling, the existing alpamon.exe is held open by the running service. Stop it first and retry:

sc.exe stop alpamon
.\alpamon.exe register --url https://your-workspace.us1.alpacon.io --token YOUR_API_TOKEN

Websh fails with PowerShell error 8009001d

This was a TLS-related Websh handshake error on early Windows builds and has been fixed in newer Alpamon releases. Upgrade to the latest Alpamon (alpamon upgrade or re-run the installer) and retry.

WebFTP can’t read C:\Windows\System32\... or other paths outside the user’s home

This is by design. On Windows, WebFTP limits browsing to the user’s home directory and does not expose system paths. Place files you want to transfer under the user’s home directory, or use Websh for read-only inspection of system locations.

macOS agent issues

Service won’t start

Inspect the launchd service and the agent log:

sudo launchctl print system/com.alpacax.alpamon
tail -n 100 /var/log/alpamon/alpamon.log

For launchd-level failures (for example, the executable cannot be found or the plist is invalid), filter Console.app for com.alpacax.alpamon to see launchd’s own error messages.

Restart the service

sudo launchctl kickstart -k system/com.alpacax.alpamon

Agent can’t read protected directories

macOS requires Full Disk Access for processes that touch system-protected paths (Mail, Messages, Time Machine, parts of ~/Library, etc.). If the agent reports permission errors when reading those locations, grant Full Disk Access to the alpamon binary in System Settings → Privacy & Security → Full Disk Access, then restart the service.

The binary location depends on your Mac:

  • Apple Silicon: /opt/homebrew/bin/alpamon
  • Intel: /usr/local/bin/alpamon

Agent upgrade issues

Alpacon keeps the Alpamon agent up to date in two ways:

  • Automatic: when Auto agent upgrade is enabled in workspace settings (the default), registered agents upgrade to the latest version on their own.
  • On demand: upgrade a specific server from the CLI with alpacon agent upgrade SERVER, then watch progress with alpacon events.

During an upgrade the agent fetches the new version and restarts automatically. The server may briefly show Offline and then reconnect. If the update can’t be applied, the agent keeps running the previous version. How the update is delivered depends on the platform:

  • Linux (Debian/Ubuntu, RHEL/CentOS): through the system package manager (apt/yum) from the Alpacon package repository.
  • macOS: downloaded from GitHub Releases.
  • Windows: command-based upgrade isn’t supported yet. Upgrade by re-running the installer with the latest release (see Windows installation).

Upgrade doesn’t start

  • Confirm the server shows Online. An offline agent can’t receive the upgrade request.
  • Run alpacon agent upgrade SERVER and watch alpacon events for the result.
  • If you rely on automatic upgrades, confirm Auto agent upgrade is enabled in workspace settings.

Upgrade fails or the version doesn’t change

  • Connectivity: every platform checks the latest version at api.github.com, so the server needs outbound HTTPS to api.github.com. On Linux, the upgrade then runs through apt/yum, so the server must also reach the Alpacon package repository, directly or through the workspace Package proxy setting. On macOS, the agent downloads the release from github.com directly.
  • Check the agent log for the reason, then trigger the upgrade again:
    • Linux: sudo journalctl -u alpamon -n 100
    • macOS: tail -n 100 /var/log/alpamon/alpamon.log
  • A failed upgrade leaves the agent running the previous version. Fix the cause (usually network or package-repository access) and retry.

Confirm the current version

The server detail page shows the running agent version. You can re-run the upgrade at any time; if the agent is already current, nothing changes.

Last updated: