Agent installation (systemd / Docker)

The LAN agent is a small Python process that runs on your Linux device inside the internal network and checks services that cannot be reached from the internet (internal DNS, intranet, ERP, NAS, printers). It communicates outbound over HTTPS, so it needs no inbound ports opened into your network.

In short: Create an agent in the dashboard, copy the token and run a single install command on the target device. The whole process takes 2 to 3 minutes.

What you will need

Any Linux with root access (Debian, Ubuntu, Raspberry Pi OS, Fedora, Alma/Rocky, Arch, openSUSE, Alpine)
x86_64, aarch64 (Raspberry Pi 4/5), armv7l (Raspberry Pi 3) or armv6l (RPi Zero) architecture
Outbound HTTPS connection to epulz.io (port 443)
Python 3.8 or newer (if missing, the installer adds it from the package manager)

The agent uses about 20 MB of RAM and less than 1 % CPU when idle. It also works in an LXC container, a virtual machine (Proxmox, VMware) or a Docker container. Besides systemd it also supports OpenRC (Alpine).

Fully auditable: the whole agent is a single Python file (~600 lines, standard library only) and the installer is a public script. You can read every line before running it: epulzio-agent.py and install-agent.sh.

1. Create an agent and copy the token

Open Dashboard - LAN agents.
Enter a clear name (for example "Bratislava server room" or "RPi in the store") and click + Create agent.
The dashboard shows the agent token (epulzio_...) and ready-made install commands to copy.

The token is shown only once. Copy it right away. Do not share it publicly or publish it on GitHub. If you lose it or it leaks, revoke the agent in the dashboard and create a new one.

2. Run the install command

On the target device, in a terminal (replace the token with your own):

curl -fsSL https://epulz.io/install-agent.sh | sudo bash -s epulzio_YOUR_TOKEN

More cautious approach (recommended for the first install): download the script first and read it:

curl -fsSL https://epulz.io/install-agent.sh -o install-agent.sh
less install-agent.sh        # read what it does (1 min)
sudo bash install-agent.sh epulzio_YOUR_TOKEN

The installer automatically:

Detects the architecture and distribution (apt / dnf / apk / pacman / zypper)
Verifies the presence of Python 3.8+ and the ping tool, installing them if needed
Tests the connection to epulz.io
Downloads the agent into /opt/epulzio-agent/
Creates the epulzio-agent service (systemd, OpenRC on Alpine) and starts it
Enables automatic start on system reboot

The whole installation takes about 30 seconds.

3. Verify that the agent is running

Service status on the device:

sudo systemctl status epulzio-agent

You should see active (running).

List of LAN agents with online status in the ePulz.io dashboard — Dashboard - LAN agents: status, last contact and agent version

In Dashboard - LAN agents the status appears within 30 seconds:

online - the last heartbeat arrived less than 2 minutes ago
timestamp - the last heartbeat was 2 to 10 minutes ago
offline - the last heartbeat is older than 10 minutes (an alert is sent after just 5 minutes of silence)

Docker variant

If you do not have systemd (TrueNAS, Synology, Unraid, k3s) or prefer a container, use the command from the dashboard:

docker run -d --name epulzio-agent --restart unless-stopped \
  --network host \
  -e EPULZIO_AGENT_TOKEN=epulzio_YOUR_TOKEN \
  python:3.12-alpine sh -c "apk add -q --no-cache iputils && wget -qO /agent.py https://epulz.io/static/agent/epulzio-agent.py && python /agent.py"

The --network host flag is important - the agent must see your LAN, not just the internal Docker bridge. On each container restart the current agent version is downloaded.

macOS and Windows

For macOS (10.15+, Intel and Apple Silicon):

curl -fsSL https://epulz.io/install-agent-macos.sh -o install-agent-macos.sh
sudo bash install-agent-macos.sh epulzio_YOUR_TOKEN

For Windows (10+ / Server 2016+, PowerShell as administrator):

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force
$env:EPULZIO_AGENT_TOKEN="epulzio_YOUR_TOKEN"; iwr -useb https://epulz.io/install-agent.ps1 | iex

Troubleshooting

The installer reports "Missing agent token"

The command is missing the token. Run it with the token at the end: ... | sudo bash -s epulzio_YOUR_TOKEN.

The installer reports "must run as root"

Run it with sudo; root is only needed for the installation (systemd service, writing to /opt).

"Cannot reach epulz.io"

The device has no outbound HTTPS connection. Test it manually with curl https://epulz.io/health. If that fails, check the firewall, DNS and NAT.

"Python 3.8+ required"

A very old system. Update the distribution or install a newer Python (on Debian for example apt install python3.9 from backports).

"Neither systemd nor OpenRC detected"

A system without a supported init system. Use the Docker variant above.

The agent stays offline in the dashboard even after 2 minutes

Check the logs: sudo journalctl -u epulzio-agent -n 50.
Most common causes: an incorrectly pasted token (check that the whole token was copied including the epulzio_ prefix), HTTPS blocked on the firewall or an incorrect system clock (check it with date - SSL certificate verification requires the correct time).

Updating the agent

Run the same install command again with the same token. The installer overwrites the files in /opt/epulzio-agent/ and restarts the service; the token stays valid.

Uninstalling

sudo systemctl stop epulzio-agent
sudo systemctl disable epulzio-agent
sudo rm -rf /opt/epulzio-agent /etc/systemd/system/epulzio-agent.service
sudo systemctl daemon-reload

In the dashboard, additionally mark the agent as Revoked to invalidate its token.

Next step

Creating your first LAN monitor (ping, TCP, HTTP).

First LAN monitor