HYPHAby S33D
Documentation › Install the agent

Install the agent on Linux

A single binary with no dependency, for amd64 and arm64. It runs as a systemd service and uses less than one percent of a core.

Requirements

Install in one command

curl -fsSL https://hypha.s33d.fr/install/install.sh | sudo HYPHA_API_KEY=hph_your_key bash

The script downloads the binary for your architecture, checks its SHA-256 sum, writes /etc/hypha/hypha.yaml (mode 600), installs the hypha-agent.service unit and starts it. It asks no question and can be run again: the same version does not restart the service.

Accepted variables:

VariablePurpose
HYPHA_API_KEYingestion key, required on first installation
HYPHA_URLtarget server, https://hypha.s33d.fr by default; your own address when self-hosting
HYPHA_TAGStags added to everything the agent sends: env:prod,role:web or {"env":"prod"}
HYPHA_HOSTNAMEhost name in HYPHA (system name by default)
HYPHA_FORCE_CONF1 rewrites api_key and url in an existing configuration

HYPHA_TAGS and HYPHA_HOSTNAME only apply when the file is created: an existing configuration is never rewritten, except api_key and url with HYPHA_FORCE_CONF=1.

Install from a package

.deb and .rpm packages are published next to the binary, under hypha.s33d.fr/install/:

# Debian, Ubuntu (replace 0.4.21 with the version in version.txt)
curl -fsSLO https://hypha.s33d.fr/install/hypha-agent_0.4.21_amd64.deb
sudo apt install ./hypha-agent_0.4.21_amd64.deb

# Red Hat, Rocky, Alma, Fedora
sudo dnf install https://hypha.s33d.fr/install/hypha-agent-0.4.21-1.x86_64.rpm

The package installs the sample configuration. Set api_key in /etc/hypha/hypha.yaml, then:

sudo systemctl start hypha-agent

An agent installed from a package is updated by the package manager; the install script then refuses to replace it.

Check

sudo hypha-agent status          # collector state and last send
sudo hypha-agent check-config    # merged configuration, secrets masked, errors with their file
systemctl status hypha-agent
journalctl -u hypha-agent -n 50

The host appears in Infrastructure within a minute. Settings › Agents shows its version, the state of each collector and the last error.

What the agent collects by default

Everything is set in /etc/hypha/hypha.yaml and /etc/hypha/conf.d/*.yaml: see the configuration reference.

Privileges and footprint

Update

Uninstall

curl -fsSL https://hypha.s33d.fr/install/install.sh | sudo bash -s -- --uninstall

The configuration (/etc/hypha) and state (/var/lib/hypha) are kept. To erase everything: sudo rm -rf /etc/hypha /var/lib/hypha. An agent installed from a package is removed with apt remove hypha-agent or dnf remove hypha-agent.

Updated: 19 November 2026