HYPHAby S33D
Documentation › Install the agent

Run the agent in a Docker container

The agent image watches the host that runs it, its processes, its network and its containers.

Run

docker run -d --name hypha-agent --restart unless-stopped --network host --pid host \
  --cap-add SYS_PTRACE --security-opt apparmor=unconfined \
  -v /proc:/host/proc:ro -v /sys:/host/sys:ro -v /:/host/root:ro \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v hypha-agent:/var/lib/hypha \
  -e HYPHA_API_KEY=hph_your_key -e HYPHA_URL=https://hypha.s33d.fr \
  registre-vm.s33d.fr/hypha/agent-docker:0.4.21

The Docker tab of Settings › Install the agent gives the command with the current published version.

OptionWhy
--network host, --pid hostsee the host's network and processes, not the container's
--cap-add SYS_PTRACE, apparmor=unconfinedlink each connection to its process
/proc, /sys, / read-onlyhost system and disk metrics
docker.sock read-onlycontainer list and metrics
hypha-agent volumeagent identity and send buffer, kept across restarts

Follow log files

The image does not read the host's systemd journal: for that, install the agent on the host (Linux). To follow files, mount them, then mount a configuration that declares them:

-v /var/log/nginx:/host/log/nginx:ro \
-v /etc/hypha/hypha.yaml:/etc/hypha/hypha.yaml:ro
logs:
  enabled: true
  journald: false
  files:
    - {path: /host/log/nginx/*.log, service: nginx, source: nginx}

HYPHA_API_KEY and HYPHA_URL passed with -e take precedence over the file.

What changes in a container

OpenTelemetry and StatsD relay

With --network host, the host's applications reach the agent's OTLP relay on 127.0.0.1:4318 and StatsD on 127.0.0.1:8125/udp. Enable otlp.enabled: true in the mounted configuration. See Traces.

Updated: 19 November 2026