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

Linux distributions (officially supported)

  • Ubuntu: 18.04, 20.04, 22.04, 24.04 LTS
  • Debian: 10 (Buster), 11 (Bullseye), 12 (Bookworm)
  • RHEL: 7, 8, 9
  • CentOS: 7, 8 Stream, 9 Stream
  • Rocky Linux: 8, 9
  • Alma Linux: 8, 9
  • Oracle Linux: 7, 8, 9
  • Fedora: 36, 37, 38, 39
  • Amazon Linux: 2, 2023
  • SUSE Linux Enterprise: 12, 15
  • Alpine Linux: 3.14+
  • Raspberry Pi OS: All recent versions

Development environments only

  • macOS: 11 (Big Sur) and later - for development and testing purposes only
    • Not recommended for production use
    • Apple Silicon (M1/M2/M3) and Intel supported

Coming soon

  • Windows: Windows Server support planned
  • 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 → Connect Server
  3. Enter server details:
    • Name: Server identifier (e.g., production-web-01)
    • Platform: Select your OS (Ubuntu, RHEL, CentOS, etc.)
    • 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 script will look similar to this:
curl https://your-workspace.us1.alpacon.io/api/servers/installers/YOUR_UNIQUE_ID/ | sudo -E bash

This script will:

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

Note: The -E flag 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.

All Alpamon packages are hosted on packagecloud.io.

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 → Connect 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 | 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 | 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.

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 → Connect Server
  3. Create a server entry and note the registration details

Register the server

Run the registration command on your server:

sudo alpamon register \
  --workspace https://alpacon.io/your-workspace/ \
  --token YOUR_REGISTRATION_TOKEN \
  --name "production-web-01"

Options:

  • --workspace: Your workspace URL
  • --token: Registration token from your workspace
  • --name: Friendly name for the server (optional)
  • --groups: Comma-separated list of groups (optional)

Verify registration

Check the agent status:

# Check service status
sudo systemctl status alpamon
 
# Check agent logs
sudo journalctl -u alpamon -f

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 main configuration file is located at:

  • Linux: /etc/alpamon/config.yaml
  • Windows: C:\ProgramData\Alpamon\config.yaml
  • macOS: /usr/local/etc/alpamon/config.yaml

Example configuration:

# Workspace configuration
workspace:
  url: https://alpacon.io/your-workspace/
  token: your-registration-token
 
# Agent settings
agent:
  name: production-web-01
  groups:
    - webservers
    - production
  labels:
    environment: production
    region: us-east-1
    team: platform
 
# Network settings
network:
  proxy: http://proxy.example.com:8080
  timeout: 30s
  retry_interval: 10s
 
# Logging
logging:
  level: info  # debug, info, warn, error
  file: /var/log/alpamon/agent.log
  max_size: 100MB
  max_backups: 5
 
# Security
security:
  allowed_users:
    - root
    - ubuntu
    - admin
  command_logging: true
  session_recording: false  # Enterprise feature

Environment variables

You can also configure Alpamon using environment variables:

export ALPAMON_WORKSPACE_URL="https://alpacon.io/your-workspace/"
export ALPAMON_TOKEN="your-registration-token"
export ALPAMON_PROXY="http://proxy.example.com:8080"
export ALPAMON_LOG_LEVEL="debug"

Proxy configuration

If your server is behind a proxy:

# Set proxy for registration
sudo alpacon agent register \
  --token YOUR_TOKEN \
  --workspace YOUR_WORKSPACE \
  --proxy http://proxy.example.com:8080
 
# Or in config file
network:
  proxy: http://proxy.example.com:8080
  no_proxy: localhost,127.0.0.1,internal.domain

Uninstallation

To remove Alpamon from your Linux server:

# 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

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:

# Check service status
sudo systemctl status alpamon
 
# View logs
sudo journalctl -u alpamon -n 50
 
# Check log file
sudo tail -f /var/log/alpamon/agent.log

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 issues

Optimize Alpamon performance:

# Adjust in /etc/alpamon/config.yaml
performance:
  max_sessions: 10
  buffer_size: 65536
  keepalive_interval: 30s
  compression: true

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?