Install Pierrr Agent

The agent is a static binary (Linux x86_64 and ARM64); the script wraps it in a systemd unit. On connecting, it tells the hub its cores, memory, disk and capabilities.

Prerequisites

A Linux server (Ubuntu 22.04+, Debian 11+, Rocky/Alma 8+, openSUSE Leap 15+).
Root or passwordless sudo access.
Outbound HTTPS (443) to install.pierrr.com, which serves the agent, and agents.pierrr.com, the address it connects to. If you filter outbound traffic, allow both addresses. A server connected before Pierrr version 0.0.49-beta keeps going through api.pierrr.com: keep it allowed as well.
Ports 80 and 443 on the server free and open to your visitors, to serve your domains and get their certificates. No port needs opening to drive the server.

Install

From Servers, "Connect a server" generates a single-use enrollment token and a ready-to-paste install command, shown only once. Run it on the machine: it is idempotent, so running it again simply updates the agent.

bash

curl -fsSL --proto '=https' https://install.pierrr.com/agent \
  | PIERRR_ENROLLMENT_TOKEN=$AGENT_LICENSE bash -s -- \
    --hub-url https://agents.pierrr.com

Verify

Confirm the systemd unit is running and watch the journal until you see a successful heartbeat.

bash

sudo systemctl status pierrr-agent
sudo journalctl -u pierrr-agent -f

Limit the machine's resources

The agent suggests recommended ceilings (one core left free, 60% of memory, a disk reserve of at least 10 GB or 10%) but never applies them on its own. With no ceiling, nothing changes. You can set them at install time with the --max-cpus, --max-mem (in MB), --reserve-disk-gb and --max-concurrent-jobs options, which makes the agent reasonable on a shared workstation or NAS. With a ceiling, a build that would take the disk below the reserve is refused, with the remaining space shown.

Environment variables

Every setting of the agent is optional and has a sensible default. To change one, for example the folders it uses or its resource ceilings, add it in a service override of the agent, then restart the unit.

bash

sudo systemctl edit pierrr-agent
# [Service]
# Environment=AGENT_MAX_CPUS=2
# Environment=AGENT_RESERVE_DISK_GB=20

Versions up to 0.48 used an older naming for these settings. If your unit or environment file still carries it, update it to the current one.

Next steps

Open your Pierrr dashboard, Servers page. The new agent appears within about thirty seconds, pending then online. See the Servers page for what comes next, then the Apps tab to deploy your first workload.

Uninstall the agent

Uninstalling removes the agent, its service, its configuration and its logs. It keeps your containers, your projects' files, their backups and their databases: a new install on the same machine finds them again. You are asked to confirm; the --yes option confirms in advance, for a script.

bash

sudo pierrr-agent uninstall

To also erase your projects' data (databases, files and backups), for good:

bash

sudo pierrr-agent uninstall --purge-data

The command lists the directories, containers and volumes it will delete, then asks for a second confirmation, which --yes never gives. An uninstall requested from the console always keeps the data.

In the console, the server stays listed: revoke or delete it from the Servers page, its projects stay attached to it with their data. After a reinstall on the same machine, the new server's page offers to take them over.