Alpamon is the open-source server agent for Alpacon, the AI-native PAM that governs what humans, AI agents, and CI/CD pipelines execute on your servers.
Installed on each managed server, Alpamon establishes an outbound-only connection to the Alpacon control plane (no inbound ports, no firewall changes) and enforces server-side decisions locally: Websh terminals, file transfers, remote command execution, and sudo verification (via the optional alpamon-pam module). Every action runs inside a scoped work session and is recorded for audit—same shape whether the actor is human, AI agent, or CI/CD pipeline.
| Platform | Minimum version | Arch |
|---|---|---|
| Linux | Ubuntu 18.04+, Debian 11+, RHEL / Rocky / AlmaLinux 8+, Oracle Linux 8+, Amazon Linux 2 / 2023, Fedora (current or previous), Raspberry Pi OS (64-bit) | amd64, arm64 |
| Linux (best-effort) | openSUSE Leap 15+, SLES 15+ | amd64, arm64 |
| macOS | 11 (Big Sur) or later | amd64, arm64 (Apple Silicon) |
| Windows | Windows 10 (1803+) / Windows 11, Windows Server 2019 or later | amd64 |
System requirements: 128MB RAM, 150MB free disk, outbound HTTPS to your Alpacon workspace.
All platforms share the same second step: alpamon register writes the config, sets up the service, and starts it. Only the first step (getting the binary onto the machine) differs.
Debian / Ubuntu
curl -s https://packagecloud.io/install/repositories/alpacax/alpamon/script.deb.sh?any=true | sudo bash
sudo apt-get install alpamon
sudo alpamon register --url https://<workspace> --token <TOKEN>RHEL / Rocky / AlmaLinux / Fedora
curl -s https://packagecloud.io/install/repositories/alpacax/alpamon/script.rpm.sh?any=true | sudo bash
sudo yum install alpamon
sudo alpamon register --url https://<workspace> --token <TOKEN>openSUSE / SLES (best-effort) — see docs/opensuse.md for the sudoers prerequisite and the yum-only server operations that still fail here.
sudo zypper addrepo -f 'https://packagecloud.io/alpacax/alpamon/rpm_any/rpm_any/$basearch' alpamon
sudo zypper --gpg-auto-import-keys refresh && sudo zypper install alpamon
sudo alpamon register --url https://<workspace> --token <TOKEN># Pick the right arch for your Mac: amd64 (Intel) or arm64 (Apple Silicon)
ARCH=$(uname -m | sed 's/x86_64/amd64/')
VERSION=$(curl -s https://api.github.com/repos/alpacax/alpamon/releases/latest | grep tag_name | cut -d'"' -f4)
curl -LO "https://github.com/alpacax/alpamon/releases/download/${VERSION}/alpamon-${VERSION#v}-darwin-${ARCH}.tar.gz"
tar xzf alpamon-*.tar.gz
sudo mv alpamon /usr/local/bin/
sudo alpamon register --url https://<workspace> --token <TOKEN>See docs/windows.md for the full install / upgrade / uninstall runbook, feature compatibility matrix, and troubleshooting.
Open an elevated PowerShell (Administrator), then run one of:
Manual — download alpamon-X.Y.Z-windows-amd64.zip from Releases, extract, and run:
.\alpamon.exe register --url https://<workspace> --token <TOKEN>Automated download-then-run — preferred for cloud-init, EC2 UserData, Packer, Azure Custom Script Extension. Keeps the installer on disk for audit and avoids executing arbitrary remote content under Administrator:
$env:ALPAMON_URL = "https://<workspace>"
$env:ALPAMON_TOKEN = "<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 $installerThe install script itself verifies the release archive's SHA-256 against the checksums file published with the release before extracting or executing anything.
A terser pipe-to-iex form is also supported for quick one-liners but trades auditability for brevity:
$env:ALPAMON_URL = "https://<workspace>"
$env:ALPAMON_TOKEN = "<TOKEN>"
iwr https://raw.githubusercontent.com/alpacax/alpamon/main/scripts/install.ps1 -UseB | iexregister copies the binary to C:\Program Files\alpamon\, creates the Windows Service (StartType=Automatic (Delayed), Recovery Actions configured), and starts it. Re-running register is idempotent.
The optional alpamon-pam package provides PAM integration for Alpacon-managed sudo authentication:
- pam_alpamon.so: Verifies Alpacon users during sudo authentication
- alpacon_approval.so: Handles sudo command approval requests
# Debian / Ubuntu
sudo apt-get install alpamon-pam
# RHEL / CentOS
sudo yum install alpamon-pam
# openSUSE / SLES
sudo zypper install alpamon-pamAfter install, add to /etc/pam.d/sudo:
auth [user_unknown=ignore auth_err=die success=done default=bad] pam_alpamon.so
And to /etc/sudo.conf:
Plugin approval_plugin alpacon_approval.so
The alpamon service must be running with the socket at /var/run/alpamon/auth.sock.
Alpamon reads the first file it finds in this order:
/etc/alpamon/alpamon.conf(Linux production)/Library/Application Support/alpamon/alpamon.conf(macOS)%ProgramData%\alpamon\alpamon.conf(Windows)~/.alpamon.conf(any platform, development)
register generates this file for you. Example:
[server]
url = https://<workspace>
id = <server-id>
key = <server-key>
[ssl]
verify = true
# ca_cert = /path/to/ca.crt
[logging]
debug = falsesudo systemctl status alpamon
sudo systemctl restart alpamon
sudo journalctl -u alpamon -fThe unit sets KillMode=process, so restarting or stopping alpamon signals only the agent itself, not the whole control-group. Sessions it launched—Websh terminals and detached jobs such as tmux, screen, or nohup'd commands—keep running across a restart, the same way sshd leaves active login sessions alone. Reattach to them from a new session after the agent reconnects.
The unit also sets RestartPreventExitStatus=78. Alpamon exits with 78 (EX_CONFIG) when startup hits a condition a restart cannot clear, such as a Linux distribution it cannot classify. systemd then leaves the service in failed instead of restarting it, so systemctl status alpamon still shows the reason. Fix the underlying condition and start the service again.
sudo launchctl print system/com.alpacax.alpamon
sudo launchctl kickstart -k system/com.alpacax.alpamon
tail -f /var/log/alpamon/alpamon.logsc.exe query alpamon
Restart-Service alpamon
Get-Content "$env:ProgramData\alpamon\log\alpamon.log" -Wait -Tail 50Alpamon supports in-place self-update: from the Alpacon console, send an upgrade command, or run alpamon upgrade locally. The agent downloads the release archive from GitHub, verifies its SHA-256 checksum, validates the binary header, and swaps the running binary atomically. On Windows the running .exe is renamed to alpamon.exe.old first and cleaned up on next service start.
git clone https://github.com/alpacax/alpamon.git
cd alpamon
go build -o alpamon ./cmd/alpamon # native
GOOS=windows GOARCH=amd64 go build ./cmd/alpamon # Windows cross-compileThe Go toolchain the go directive in go.mod names is required. GOPATH/bin should be on PATH. The generated Ent code is gitignored, so run go generate ./pkg/db/ent (see below) before the first build.
The go:generate directive in pkg/db/ent/generate.go runs go tool entc, the codegen program registered as a tool directive in go.mod, with pkg/db/ent as the working directory. That is what makes the generator's relative schema and target paths resolve, so always run it through go generate as shown below rather than calling go tool entc from another directory. The generator drops the unused Atlas SQL dialects from the binary; do not invoke the ent CLI directly, which regenerates the migrate package and pulls them back in.
Building the codegen tool links ariga.io/atlas, so it stays in go.mod as an indirect dependency. It never reaches the binary: cmd/alpamon does not import it.
go generate ./pkg/db/entAtlas is only needed when modifying schemas under pkg/db/schema/. Production deployments execute the embedded SQL files in pkg/db/migration/ directly.
curl -sSf https://atlasgo.sh | sh
atlas migrate diff <migration_name> \
--dir "file://pkg/db/migration" \
--to "ent://pkg/db/schema" \
--dev-url "sqlite://alpamon.db?mode=memory"go test ./... -p 1 # whole suite
go test -v ./pkg/updater # one package-p 1 is required. The SQLite store and the system resource checks both break when packages run in parallel.
Assert with testify: require when a failed check makes the rest of the test meaningless, assert for the checks themselves. Prefer the specific helper over a hand-rolled comparison: require.NoError, assert.ErrorContains, assert.DirExists. Read what a helper accepts before reaching for it, because the shorter spelling is sometimes the weaker check. assert.NoFileExists is the example: it treats a directory at the path, and any other Lstat error, as absence, so a test that must prove a path was removed asserts os.ErrNotExist from os.Stat instead. Write every new test this way. Many older tests still call t.Errorf and t.Fatalf directly; convert one while you are already editing it rather than as a separate sweep. A bare t.Fatal stays correct where there is no error value to assert on, such as the timeout branch of a select. A test that waits on a timer belongs in a testing/synctest bubble: inside synctest.Test the clock is fake and advances only once every goroutine in the bubble is blocked, so a timeout guard fires on a real block instead of on a slow runner, and a wg.Wait the code under test can no longer satisfy surfaces as a deadlock rather than as a package timeout. Reach for a fixed time.Sleep only to hold a worker so jobs overlap. A bubble does not count network, file, or process waits as blocked, so tests backed by httptest, a PTY, or a real socket stay on the real clock.
./Dockerfiles/build.sh
docker run alpamon:ubuntu-22.04
# Custom workspace
docker run \
-e ALPACON_URL="https://<workspace>" \
-e PLUGIN_ID="<plugin_id>" \
-e PLUGIN_KEY="<plugin_key>" \
alpamon:opensuse-15Covered distros: Ubuntu 22.04/20.04, Debian 11, RHEL 8/9, openSUSE Leap 15. Legacy Dockerfiles for Ubuntu 18.04, Debian 10, and CentOS 7 also ship under Dockerfiles/ for best-effort builds against EOL platforms.
go run ./cmd/alpamon
# or
./alpamonLocal config lives at ~/.alpamon.conf; for a fresh run against a dev server:
[server]
url = http://localhost:8000
id = 7a50ea6c-2138-4d3f-9633-e50694c847c4
key = alpaca
[logging]
debug = true