Installation guide

Learn how to install the Alpacon agent (Alpamon) on your servers and connect them to your workspace.

Prerequisites

Before installing Alpacon, ensure you have:

• Alpacon workspace: Sign up at alpacon.io if you don’t have one
• Server requirements:
  • Supported OS (see supported platforms)
  • Root or sudo access for installation
  • Outbound HTTPS connectivity (port 443)
  • 150MB free disk space
  • 128MB available RAM

Supported platforms

Alpamon ships official builds for Linux, macOS, and Windows.

Feature scope per platform

Linux and macOS expose Alpacon’s full feature set, including user and group management and Unix-style permission changes (chmod / chown). Windows servers support terminal sessions (Websh) and file transfer (WebFTP); user/group management and Unix permission controls are not applicable and the corresponding UI is disabled for Windows servers.

See Windows servers for the full Windows feature matrix, the SYSTEM permission model, upgrades, and troubleshooting.

Note: Ubuntu 25.10 and later (including 26.04) ship sudo-rs as the default sudo. Alpacon supports it for sudo with MFA, which requires the alpamon-pam package version 1.1.2 or later. See Compatibility with sudo-rs, and PAM and sudo issues for troubleshooting.

Coming soon

• Container environments: Docker, Kubernetes support in development

Quick installation

The recommended way to install and register Alpamon:

Step 1: Prepare server registration in workspace

1. Log in to your Alpacon workspace
2. Go to Servers → Register Server and choose Registration with token
3. Select the Platform, optionally set a Server name, and pick a registration token. Access groups are inherited from the token, not set on this form.

See Register a server for the full registration flow (including Ansible).

Step 2: Install using the generated command

Copy the command your workspace generates and run it on the server. The workspace tailors it to the platform you selected.

Linux / macOS—paste into a terminal:

# The command will look similar to this:
curl https://your-workspace.us1.alpacon.io/api/servers/installers/YOUR_UNIQUE_ID/ | sudo -EH bash

Windows—paste into an elevated PowerShell (Run as Administrator). The generated command downloads the agent from GitHub Releases, verifies its checksum, and runs alpamon.exe register. See Windows for the equivalent manual steps.

In either case, the command will:

1. Install the Alpamon agent
2. Register the server with your workspace
3. Start the agent as a service

Note: On Linux and macOS, sudo -EH preserves your environment variables (such as proxy settings) and sets HOME for the install.

Step 3: Verify installation

In your workspace, verify the server shows as Connected in the server list. You can now access it via terminal.

Manual installation (advanced)

Note: For most users, we recommend using the workspace-generated install command (see Quick installation). Manual installation requires separate registration.

Linux packages are hosted on packagecloud.io. macOS uses a Homebrew tap. Windows uses release archives published on GitHub Releases.

Linux

Method 1: Repository installation (recommended)

This method allows automatic updates through your system’s package manager.

Step 1: Get environment variables from Alpacon

Before installation, you need to obtain registration credentials from your Alpacon workspace.

Option A: Via Alpacon Web UI

1. Log in to your Alpacon workspace
2. Navigate to Servers → Register Server
3. Create a new server entry
4. Copy the environment variables from the installation instructions: ALPACON_URL, PLUGIN_ID, PLUGIN_KEY

Option B: Via Alpacon CLI

# Create server via CLI (interactive prompts)
alpacon server create
 
# After creation, you'll see installation instructions including environment variables
# Copy the ALPACON_URL, PLUGIN_ID, and PLUGIN_KEY values

Step 2: Set environment variables

Export the credentials on your target server:

export ALPACON_URL="https://your-workspace.us1.alpacon.io"
export PLUGIN_ID="your-plugin-id"
export PLUGIN_KEY="your-plugin-key"

Important: Use export to ensure these variables are available during installation. The -EH flags in sudo -EH preserve your environment variables and set HOME for the install.

Step 3: Install Alpamon

DEB-based systems (Ubuntu/Debian):

# Add repository and GPG key (preserves environment variables)
curl -s https://packagecloud.io/install/repositories/alpacax/alpamon/script.deb.sh?any=true | sudo -EH bash
 
# Install Alpamon (uses environment variables for auto-registration)
sudo -EH apt-get install -y alpamon
 
# Start and enable the service
sudo systemctl start alpamon
sudo systemctl enable alpamon

RPM-based systems (RHEL/Rocky/Alma/Fedora):

# Add repository (preserves environment variables)
curl -s https://packagecloud.io/install/repositories/alpacax/alpamon/script.rpm.sh?any=true | sudo -EH bash
 
# Install Alpamon (uses environment variables for auto-registration)
sudo -EH yum install -y alpamon
 
# Start and enable the service
sudo systemctl start alpamon
sudo systemctl enable alpamon

Note: If your workspace has sudo with MFA enabled, also install the PAM module by adding alpamon-pam to the install command—for example sudo -EH apt-get install -y alpamon alpamon-pam (or yum on RHEL-based systems). The workspace-generated command adds this automatically.

Method 2: Direct package download

Download and install a specific package version directly. This method also requires environment variables for auto-registration.

Step 1: Get and set environment variables

Follow the same steps as Method 1 to obtain and export ALPACON_URL, PLUGIN_ID, and PLUGIN_KEY.

export ALPACON_URL="https://your-workspace.us1.alpacon.io"
export PLUGIN_ID="your-plugin-id"
export PLUGIN_KEY="your-plugin-key"

Step 2: Download and install

DEB-based systems (Ubuntu/Debian):

# Download the package. Filenames follow alpamon_<version>_linux_<arch>.deb —
# check the exact filename on the package page: https://packagecloud.io/alpacax/alpamon
wget "https://packagecloud.io/alpacax/alpamon/packages/ubuntu/focal/alpamon_<version>_linux_amd64.deb/download.deb" -O alpamon.deb
 
# Install the package (preserves environment variables)
sudo -EH dpkg -i alpamon.deb
 
# Install any missing dependencies
sudo -EH apt-get install -f -y
 
# Start the service
sudo systemctl start alpamon
sudo systemctl enable alpamon

RPM-based systems (RHEL/Rocky/Alma/Fedora):

# Download the package. Filenames follow alpamon-<version>-1.linux.<arch>.rpm —
# check the exact filename on the package page: https://packagecloud.io/alpacax/alpamon
wget "https://packagecloud.io/alpacax/alpamon/packages/el/8/alpamon-<version>-1.linux.x86_64.rpm/download.rpm" -O alpamon.rpm
 
# Install the package (preserves environment variables)
sudo -EH rpm -i alpamon.rpm
 
# Start the service
sudo systemctl start alpamon
sudo systemctl enable alpamon

Browse all packages: Visit packagecloud.io/alpacax/alpamon to view all available packages for different OS versions and architectures.

Note: If environment variables are set correctly during installation, the agent will auto-register. Otherwise, proceed to manual registration.

macOS

Install Alpamon with Homebrew, then run alpamon register to write the config and start the launchd service. The $(brew --prefix) form below works on both Apple Silicon (/opt/homebrew/bin) and Intel (/usr/local/bin) Macs. Use the full path because sudo may not find Homebrew-installed binaries on Apple Silicon.

brew tap alpacax/alpacon
brew install alpamon
sudo "$(brew --prefix)/bin/alpamon" register \
  --url https://your-workspace.us1.alpacon.io \
  --token YOUR_API_TOKEN

brew install is safe to re-run, but alpamon register itself fails on a host that is already registered—it reports config file already exists. To re-register or recover, run alpamon register --force (or alpamon unregister then alpamon register) on the server itself. See registration recovery.

Windows

Open an elevated PowerShell (Run as Administrator) and choose one of the methods below. In both cases, alpamon.exe register installs the agent under C:\Program Files\alpamon\, registers it as a Windows service that starts automatically on boot, and starts the service. The install.ps1 script is safe to re-run, but alpamon.exe register itself fails on a host that is already registered (config file already exists). To re-register or recover, run alpamon.exe register --force (or alpamon.exe unregister then alpamon.exe register) from the server, not over Websh. See registration recovery.

Method 1: Manual install

1. Download alpamon-X.Y.Z-windows-amd64.zip from GitHub Releases. The binary is not signed, so Windows may block it (SmartScreen). Unblock the ZIP before extracting: Unblock-File .\alpamon-X.Y.Z-windows-amd64.zip. Then extract the archive.
2. From an elevated PowerShell in the extracted folder:

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

Method 2: Automated install with install.ps1

Recommended for cloud-init, EC2 UserData, Packer, and Azure Custom Script Extension. The script downloads the release archive, verifies the download integrity using the checksums published with the release, extracts it, and runs alpamon register.

Download-then-run (preferred—keeps the installer on disk for audit):

$env:ALPAMON_URL   = "https://your-workspace.us1.alpacon.io"
$env:ALPAMON_TOKEN = "YOUR_API_TOKEN"
$installer = Join-Path $env:TEMP 'alpamon-install.ps1'
Invoke-WebRequest -UseBasicParsing `
    -Uri 'https://raw.githubusercontent.com/alpacax/alpamon/main/scripts/install.ps1' `
    -OutFile $installer
& powershell -ExecutionPolicy Bypass -File $installer

Pipe-to-iex (terse, trades auditability for brevity):

$env:ALPAMON_URL   = "https://your-workspace.us1.alpacon.io"
$env:ALPAMON_TOKEN = "YOUR_API_TOKEN"
iwr https://raw.githubusercontent.com/alpacax/alpamon/main/scripts/install.ps1 -UseB | iex

Advanced: manual registration

If you installed Alpamon manually (without the workspace-generated install command), you can register it separately:

Get registration information

1. Log in to your Alpacon workspace
2. Navigate to Servers → Register Server
3. Create a server entry and note the registration details

Register the server

Run the registration command on your server:

sudo alpamon register \
  --url https://your-workspace.us1.alpacon.io \
  --token YOUR_API_TOKEN \
  --name "production-web-01" \
  --tag env=prod --tag role=web

Options:

• --url: Alpacon server URL (required)
• --token: API token with servers:register scope (required)
• --name: Server name (optional, defaults to hostname)
• --platform: Platform type—debian, rhel, darwin, or windows (optional, auto-detected)
• --ssl-verify: Enable SSL certificate verification (default: true)
• --ca-cert: CA certificate file path (optional)
• --tag: Server tag in key=value format (optional, repeatable)
• --no-cloud-probe: Skip cloud provider metadata auto-detection on cloud hosts (optional)
• --force: Recover a stuck server. Registers anew, then retires the previous registration once the new one is committed (the old registration is kept until the new one succeeds). Requires alpamon v2.3.0 or later.
• --no-rollback: Leave partial state in place if registration fails instead of cleaning it up (debugging only, not for normal use). Requires alpamon v2.3.0 or later.

Verify registration

Check the agent status using the command for your platform.

Linux

sudo systemctl status alpamon
sudo journalctl -u alpamon -f

macOS

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

Windows

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

In your workspace:

1. Go to Servers page
2. Your server should appear as “Connected”
3. Click on the server to access terminal

Configuration

Configuration file

The configuration file location depends on the platform:

• Linux: /etc/alpamon/alpamon.conf
• macOS: /Library/Application Support/alpamon/alpamon.conf
• Windows: %ProgramData%\alpamon\alpamon.conf

Format (INI):

[server]
id = your-server-id
key = your-server-key
url = https://your-workspace.us1.alpacon.io
 
[ssl]
verify = true
# ca_cert = /path/to/ca.crt    # Custom CA certificate (optional)
 
[logging]
debug = false           # Enable verbose debug logging
 
[pool]
max_workers = 20        # Maximum concurrent workers
queue_size = 200        # Job queue size
default_timeout = 30    # Task timeout in seconds (0 = no timeout)
 
[editor]
idle_timeout = 60       # Code-server idle timeout in minutes (0 = disabled)
 
[file]
# max_download_bytes = 0    # Max download size in bytes for URL fetches (0 = unlimited)

Note: This file is automatically generated during installation or registration. You typically don’t need to edit it manually.

Environment variables

These environment variables are used during package installation for auto-registration:

# Required for auto-registration
export ALPACON_URL="https://your-workspace.us1.alpacon.io"
export PLUGIN_ID="your-server-id"
export PLUGIN_KEY="your-server-key"
 
# Optional
export ALPACON_SSL_VERIFY="true"      # SSL certificate verification
export ALPACON_CA_CERT="/path/to/ca.crt"  # CA certificate path
export PLUGIN_DEBUG="false"           # Enable debug logging

Proxy configuration

If your server is behind a proxy, set the HTTP proxy environment variables before running the install command or alpamon register:

export http_proxy="http://proxy.example.com:8080"
export https_proxy="http://proxy.example.com:8080"

Note: Use the lowercase form (http_proxy / https_proxy)—the workspace-generated command and the system package manager read these. The -EH flags in sudo -EH then preserve them for the installation process.

Upgrading the agent

Once a server is registered, Alpacon keeps its Alpamon agent up to date on Linux, macOS, and Windows—no manual download or reinstall needed. There are two paths:

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

The agent fetches the new version and restarts automatically. The server may briefly go Offline and reconnect, and if an upgrade fails the agent keeps running the previous version. On Linux the update comes through the system package manager (apt/yum); on macOS and Windows it’s downloaded from GitHub Releases. Every server needs outbound HTTPS to api.github.com for the version check.

On Windows, the agent self-updates the same way as macOS: use the on-demand upgrade command above, or run alpamon upgrade on the server. If the self-update path is blocked, re-run the installer with the latest release.

If an upgrade doesn’t take effect, see agent upgrade issues.

Uninstallation

The recommended path is alpamon unregister, which removes the server in one step from the host: it stops and removes the OS service, deletes the local configuration (alpamon.conf), and makes a best-effort attempt to delete the workspace server record. Run it on the server itself (local console, RDP, or cloud serial console), not over Websh—stopping the service ends a Websh session before the command finishes. Requires alpamon v2.3.0 or later.

# Linux / macOS
sudo alpamon unregister --yes

# Windows (elevated PowerShell, on the server)
& "$env:ProgramFiles\alpamon\alpamon.exe" unregister --yes

unregister leaves the agent binary and the data and log directories in place. To remove those as well—or on agents older than v2.3.0, which do not have unregister—use the per-OS steps below and delete the server from the Servers page in your workspace.

Linux

# Stop the service
sudo systemctl stop alpamon
 
# Uninstall package (Debian/Ubuntu)
sudo apt-get remove --purge alpamon
 
# Uninstall package (RHEL/CentOS/Rocky/Alma)
sudo yum remove alpamon
 
# Remove configuration and data
sudo rm -rf /etc/alpamon
sudo rm -rf /var/lib/alpamon
sudo rm -rf /var/log/alpamon

macOS

brew uninstall alpamon
 
# Remove configuration, data, and logs
sudo rm -rf "/Library/Application Support/alpamon"
sudo rm -rf /var/log/alpamon

Windows

From an elevated PowerShell. Stop and delete the service before removing the folder—if the service still holds alpamon.exe, the folder removal fails with a sharing violation. If that happens, wait a few seconds and retry.

sc.exe stop alpamon
sc.exe delete alpamon
 
# Remove the binary, configuration, and logs
Remove-Item "C:\Program Files\alpamon" -Recurse -Force
Remove-Item "$env:ProgramData\alpamon" -Recurse -Force

Verify the removal:

sc.exe query alpamon                   # 1060 (service does not exist) means it is gone
Test-Path "C:\Program Files\alpamon"   # False
Test-Path "$env:ProgramData\alpamon"   # False

If you used the manual steps above rather than alpamon unregister, the workspace still has the server record—remove it:

1. Go to Servers in your workspace
2. Select the server
3. Click Delete

Troubleshooting

Agent won’t start

Check the service status and logs on the platform that applies.

Linux (systemd)

sudo systemctl status alpamon
sudo journalctl -u alpamon -n 50

macOS (launchd)

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

Windows (Service Control Manager)

From an elevated PowerShell:

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

For deeper service-start failures, also check Event Viewer → Windows Logs → Application and Applications and Services Logs.

Registration fails

Common issues:

• Invalid token: Regenerate token in workspace
• Network error: Check firewall/proxy settings
• DNS issues: Verify you can resolve alpacon.io
• Time sync: Ensure system time is correct

Connection issues

Test connectivity:

# Test HTTPS connectivity
curl -v https://alpacon.io
 
# Test with proxy
curl -v -x http://proxy:8080 https://alpacon.io
 
# Check DNS
nslookup alpacon.io
dig alpacon.io
 
# Check firewall
sudo iptables -L -n | grep 443

Performance tuning

Adjust worker pool and editor settings in /etc/alpamon/alpamon.conf:

[pool]
max_workers = 20        # Maximum concurrent workers (default: 20)
queue_size = 200        # Job queue size (default: 200)
default_timeout = 30    # Task timeout in seconds (default: 30, 0 = no timeout)
 
[editor]
idle_timeout = 60       # Code-server idle timeout in minutes (default: 60, 0 = disabled)

Next steps

After successful installation:

1. Configure access controls - Set up roles and permissions
2. Connect via Websh - Access your server through the browser
3. Review activity - Audit sessions, commands, and approval decisions
4. Integrate with CI/CD - Automate deployments

Need help?

• Check our Troubleshooting guide
• Visit the FAQ
• Join our Discord community
• Email support: support@alpacax.com