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

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 servers:register scope (required)
  • --name: Server name (optional, defaults to hostname)
  • --platform: Platform type—debian or rhel (optional, auto-detected)
  • --ssl-verify: Enable SSL certificate verification (default: true)
  • --ca-cert: CA certificate file path (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 /etc/alpamon/alpamon.conf (INI format):

[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

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

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?