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.

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. Navigate to Servers → Register Server
3. Enter server details:
   • Name: Server identifier (e.g., production-web-01)
   • Platform: Select your OS (Debian-based, Red Hat-based, macOS, or Windows)
   • User Groups (optional): Groups that can access this server
4. Click Save

Step 2: Install using the generated script

Copy the generated setup script from your workspace and run it on your server. The workspace tailors the script to the platform you selected—a shell command for Linux and macOS, or a PowerShell command for Windows.

Linux / macOS—paste into a terminal:

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

Windows—paste into an elevated PowerShell (Run as Administrator):

# The script will look similar to this:
$env:ALPAMON_URL   = "https://your-workspace.us1.alpacon.io"
$env:ALPAMON_TOKEN = "YOUR_TOKEN"
iwr https://raw.githubusercontent.com/alpacax/alpamon/main/scripts/install.ps1 -UseB | iex

In either case, the script will:

1. Detect your OS and architecture
2. Download the appropriate Alpamon package
3. Install and configure the agent
4. Register the server with your workspace automatically
5. Start the Alpamon service

Note: On Linux and macOS, the -E flag in sudo -E preserves your environment variables (useful for proxy configuration).

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 setup script (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 -E flag in sudo -E preserves environment variables.

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 -E bash
 
# Install Alpamon (uses environment variables for auto-registration)
sudo -E apt-get install alpamon
 
# Start and enable the service
sudo systemctl start alpamon
sudo systemctl enable alpamon

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

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

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 latest package
wget https://packagecloud.io/alpacax/alpamon/packages/ubuntu/focal/alpamon_amd64.deb/download.deb?distro_version_id=210 -O alpamon_amd64.deb
 
# Install the package (preserves environment variables)
sudo -E dpkg -i alpamon_amd64.deb
 
# Install any missing dependencies
sudo apt-get install -f
 
# Start the service
sudo systemctl start alpamon
sudo systemctl enable alpamon

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

# Download the latest package
wget https://packagecloud.io/alpacax/alpamon/packages/el/8/alpamon-x86_64.rpm/download.rpm -O alpamon.x86_64.rpm
 
# Install the package (preserves environment variables)
sudo -E rpm -i alpamon.x86_64.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

It is safe to re-run alpamon register later—it refreshes the configuration file and restarts the service.

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. It is safe to re-run register later—it refreshes the configuration and restarts the service.

Method 1: Manual install

1. Download alpamon-X.Y.Z-windows-amd64.zip from GitHub Releases and extract it.
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 setup script), 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"

Options:

• --url: Alpacon server URL (required)
• --token: API token with server: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)

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]
level = info    # debug, info, warning, error, fatal
debug = false
 
[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)

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 standard HTTP proxy environment variables before running the installation script or alpamon register command:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

Note: The -E flag in sudo -E preserves these variables for the installation process.

Uninstallation

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:

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

After uninstallation, remove the server from your workspace:

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. Set up monitoring - Configure alerts and dashboards
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