Register a server

Register your server with Alpacon to manage it from your browser.

What is a user server?

A user server refers to a server operated by an individual user or a group of users. Alpacon supports registration and management of both:

• Cloud-based servers (e.g., AWS, GCP, Azure)
• On-premise servers operated directly by the user

Even in hybrid environments where different types of servers coexist, Alpacon offers a consistent UI/UX to manage all servers seamlessly in one place.

Key benefits:

• Unified management interface for all server types
• Consistent experience regardless of server location
• No distinction needed between cloud and on-premise
• Centralized control and monitoring

Registration process

Server registration follows 3 steps:

1. Registration method—Choose a registration method
2. Server information—Enter server details (varies by method)
3. Installation guide—Run the generated installation script or command

Registration methods

Registration with token

Register a server using a server registration token and the generated CLI command. The same token can register a single server or many, which makes this method well suited to both one-off and bulk registration.

Step 1: Select registration method

1. Click Servers in the left sidebar
2. Click Register Server button in the top right
3. Select Registration with token

Step 2: Enter server information

• Platform (required)—Select the server OS (Debian family, Red Hat family, macOS, or Windows)
• Server name (optional)—Up to 20 characters. Used as a prefix for the server name. If not specified, the server’s hostname is used.
• Registration token (required)—Select an existing token from the dropdown, or create one on the spot

Note: Which user groups can access the registered server is determined by the registration token, not this form. The server inherits the token’s allowed groups (set when the token was created). See server registration tokens.

Step 3: Install agent

A token-based CLI installation command is generated and displayed on screen.

1. Copy the generated command
2. Run it on the target server
3. Wait for installation to complete
4. Verify the status shows Online in the server list

Ansible

Install and register the Alpamon agent across a fleet of servers with an Ansible playbook, using the alpacax.alpacon collection’s register module. This is best for bulk registration and for teams that already manage servers with Ansible. The module is idempotent, so re-running a playbook safely skips hosts that are already registered.

Before you start

• Control node: Python 3.11+ and Ansible 2.15+ (pip install ansible), with SSH key-based access to your targets.
• A server registration token. The token determines which groups can access the registered servers.
• Install the collection:

ansible-galaxy collection install alpacax.alpacon --upgrade

Step 1: Select registration method

1. Click Servers in the left sidebar
2. Click Register Server in the top right
3. Select Ansible, then choose the platform (and optionally a server name and registration token)

Alpacon generates a guide tailored to your selection, with the exact inventory and run commands ready to copy.

Step 2: Configure inventory

Create inventory.ini in your working directory:

[targets]
YOUR_IP ansible_user=YOUR_USER  # ansible_ssh_private_key_file=/path/to/YOUR_KEY.pem

Replace YOUR_IP with the target’s IP or hostname and YOUR_USER with the SSH user. For Windows targets, also add ansible_connection=ssh ansible_shell_type=powershell.

Verify connectivity before continuing—you should see SUCCESS:

ansible -i inventory.ini targets -m ping

For Windows targets, ping won’t work (it needs Python on the host)—use win_ping from the ansible.windows collection instead: ansible -i inventory.ini targets -m ansible.windows.win_ping.

Step 3: Register

Choose one of two approaches.

Option A—bundled playbook (one-off install, nothing to write):

ansible-playbook -i inventory.ini alpacax.alpacon.register \
  -e alpacon_url=https://your-workspace.us1.alpacon.io \
  -e registration_token=YOUR_REGISTRATION_TOKEN_KEY \
  -e platform=debian

Option B—custom playbook (reusable, fits existing automation). Save this as playbook.yml:

- hosts: targets
  become: true
  tasks:
    - alpacax.alpacon.register:
        alpacon_url: "https://your-workspace.us1.alpacon.io"
        registration_token: "{{ registration_token }}"
        platform: "debian"
      no_log: true

ansible-playbook -i inventory.ini playbook.yml \
  -e registration_token=YOUR_REGISTRATION_TOKEN_KEY

Security: These examples pass the token with -e registration_token=... for brevity, which can expose it in your shell history and the process list. For anything beyond a one-off run, store the token in Ansible Vault and reference it as a variable instead of passing it on the command line.

Module parameters

• alpacon_url (required)—your Alpacon workspace URL.
• registration_token (required)—the registration token key. Store it in Ansible Vault rather than in plain text.
• platform (required)—debian, rhel, darwin, or windows.
• server_name (optional)—defaults to the target’s hostname.
• package_proxy (optional)—HTTP proxy URL for package installation.
• allow_sudo_with_mfa (optional, Linux only)—also installs the alpamon-pam package for sudo with MFA.

Platform notes

• Linux (debian = Debian/Ubuntu, rhel = RHEL/CentOS/Fedora): run with become: true (the target user needs root or passwordless sudo).
• macOS (darwin): do not set become: true—Homebrew refuses to run as root. The target needs Homebrew installed (Alpamon ships through the alpacax/alpacon tap); package_proxy and allow_sudo_with_mfa don’t apply. If your control node is macOS, export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES before running ansible-playbook.
• Windows: do not set become: true—the connecting user must already be an Administrator. Requires PowerShell 5.1+, TLS 1.2, and outbound HTTPS to github.com.

AWS Cloud-Init (coming soon)

Register servers automatically using AWS Cloud-Init user data during EC2 instance provisioning.

Terraform (coming soon)

Use the Terraform provider to provision and register servers simultaneously as part of your Infrastructure as Code workflow.

Supported platforms

For the full Linux distribution matrix, see the installation guide.

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 on Windows, and the corresponding UI is disabled for Windows servers.

Requirements

Server:

• A supported operating system and architecture (see supported platforms)
• Administrative access for installation (root/sudo on Linux and macOS, elevated PowerShell on Windows)
• Internet connection

Network:

• Outbound HTTPS connections allowed (port 443)
• Access to Alpacon API servers

Troubleshooting

Connection status shows “Offline”—check agent status, restart, and inspect logs using the commands for your platform.

Linux (systemd)

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

macOS (launchd)

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

Windows (Service Control Manager)

From an elevated PowerShell:

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

Note: On Windows, it is safe to re-run alpamon register. It installs the agent under %ProgramFiles%\alpamon\ if needed, refreshes the service configuration, and starts the service.

Installation fails:

• Verify administrative privileges (sudo on Linux/macOS, elevated PowerShell on Windows)
• Check internet connection
• Confirm platform is supported

Security considerations

Agent communication:

• All communication is TLS encrypted
• Only outbound connections from server to Alpacon required
• No inbound ports need to be opened

Authentication:

• Each server uses a unique token for authentication
• Token is only used during installation and stored securely

Next steps

After registering your server:

• Connect to servers
• Control server access
• Monitor server status