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

Re-registration and recovery

These commands recover a host whose registration is stuck or half-finished. Run them on the server itself (local console, RDP, or cloud serial console), not over Websh, and on alpamon v2.3.0 or later. Older agents do not have register --force or unregister (plain alpamon register still exists)—uninstall the agent manually and delete the server from the Servers page, then register again.

alpamon register stops with config file already exists

The host is already registered, so alpamon register refuses to register again. Re-register in one step with alpamon register --force, which registers anew and retires the previous registration once the new one succeeds. You can also run alpamon unregister first and then alpamon register.

Registration failed partway through

If a registration attempt fails after it has already created some state, the host can be left half-registered. Run alpamon register --force to register cleanly and retire the leftover registration.

Preserving state for diagnosis

By default a failed alpamon register rolls back the state it created during that run. To keep that partial state for troubleshooting, add --no-rollback (for example, alpamon register --force --no-rollback). This is for debugging only and leaves partial state behind.

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

If the registration itself is stuck or half-finished, see Re-registration and recovery.

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 by re-running the installer with a newer release, then retry.

WebFTP shows more than the user’s home on Windows, including C:\Windows\System32\...

This is expected. On Windows, WebFTP is not confined to a single user’s home directory: it can browse, read, and write any path the agent can reach on the host, including system directories such as C:\Windows\System32. Access is governed by your Alpacon roles and permissions and by which users are allowed to connect, not by a per-user home boundary on the server. Grant WebFTP access deliberately, and use Alpacon roles to limit who can reach sensitive locations. See WebFTP permissions for how access is controlled.

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 available. Update 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. Windows has no command-based upgrade; update by re-running the installer.
  • 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: