HYPHAby S33D
Documentation › Install the agent

Agent configuration reference

One main file, additions in conf.d, and a command that checks it all before a restart.

Where the configuration lives

SystemMain fileAdditions
Linux/etc/hypha/hypha.yaml (600)/etc/hypha/conf.d/*.yaml
WindowsC:\ProgramData\Hypha\hypha.yamlC:\ProgramData\Hypha\conf.d\*.yaml
Docker/etc/hypha/hypha.yaml in the containermounted /etc/hypha/conf.d/

Reading rules:

Before every restart:

sudo hypha-agent check-config

The command shows the merged configuration, secrets masked, and names the source file of each error.

General keys

KeyDefaultPurpose
api_key(required)ingestion key, hph_ followed by 40 characters
urlhttps://hypha.s33d.frintake server; your own address when self-hosting
hostnamesystem namehost name in HYPHA
tags{}tags added to everything the agent sends; keys a-z 0-9 _ . - /
interval15smetric and check interval (1 s minimum)
tls_skip_verifyfalseonly disable certificate checks for a self-hosted server with an internal certificate
proxy(empty)HTTP proxy; empty = HTTPS_PROXY and NO_PROXY variables
buffer.dir, buffer.max_mb/var/lib/hypha/buffer, 256disk buffer for failed sends; the oldest go beyond the limit

Logs

logs:
  enabled: true
  journald: true                       # Linux: systemd journal
  windows_eventlog: [System, Application]
  files:
    - {path: /var/log/nginx/*.log, service: nginx, source: nginx}
    - {path: /srv/app/logs/*.json, service: shop}
  exclude_patterns: ["GET /health"]    # regular expressions, lines never sent

A JSON line is decoded: message or msg becomes the message, level or severity the status, the rest goes into attributes. A message is truncated at 32 KiB. To reduce volume on the server side, see also exclusion filters.

Processes, network, containers

processes:
  enabled: true
  include: ["^java", "gunicorn"]   # always collected, on top of the top 30 by CPU and by memory
network:
  enabled: true
  # exclude_interfaces: [lo, "docker*", "veth*", "br-*", "virbr*", "cali*", "flannel*", "cni*"]
containers:
  enabled: auto                     # auto = if /var/run/docker.sock exists

Checks

checks:
  systemd_units: [nginx.service]    # followed; a failed unit is ALWAYS reported
  windows_services: [W3SVC]         # followed; a stopped automatic service is reported
  windows_services_exclude: ["^Veeam"]
  windows_auto_services: auto       # auto, always, never
  http:
    - {name: site, url: "https://example.com/", expect_status: 200, timeout: 5s}
  tcp:
    - {name: db, address: "192.0.2.5:5432", timeout: 3s}
  processes:
    - {name: nginx}
    - {name: gunicorn, match: contains, min: 2}
    - {name: "^php-fpm[0-9.]*$", match: regex, min: 1, max: 1}

HTTP and TCP checks start from the host: they see internal addresses. For scheduled tests with history and assertions, see synthetic tests.

Integrations

Each integration turns itself on when its software is detected (enabled: auto), or is forced (true) or turned off (false). Its state shows in Settings › Agents: ok, absent, disabled, or the error met. Each one is described on the Integrations, Databases, SNMP, Clouds, Virtualization, Kubernetes, AI and GPU and Generic collection pages (integrations.openmetrics, integrations.nagios: lists, which also add up across conf.d files).

Several instances

To read several targets of one integration (ovhcloud, mysql, redis, memcached, rabbitmq, mongodb, opensearch, kubernetes, libvirt, proxmox, aws, scaleway, azure, gcp, ollama, phpfpm, varnish, squid, lighttpd, supervisord, pgbouncer, proxysql, clickhouse, couchdb, couchbase, zookeeper, ceph, openldap, powerdns, powerdns_recursor, keycloak, nexus, harbor, fluentd, wazuh, suricata), give an instances list. Each entry has a name (lowercase letters, digits, - and _), starts from the integration's defaults, and adds up across conf.d files. Its data carries the instance_name tag.

integrations:
  redis:
    instances:
      - {name: sessions, address: "127.0.0.1:6379"}
      - {name: queue, address: "127.0.0.1:6380", password: "…"}

Application metrics and traces

statsd:
  enabled: true
  listen: 127.0.0.1:8125     # DogStatsD format: name:value|g|c|ms|h|s|#tag:value
otlp:
  enabled: false
  listen: 127.0.0.1:4318     # OTLP/HTTP: the agent relays to HYPHA, adding the key

Listening outside the loopback triggers a warning: it opens the port to the network.

Syslog reception (syslog:, off by default) is described in Generic collection.

Control channel, updates, actions

control:
  enabled: true
  interval: 30s            # the agent polls the server; no port open on the host
auto_update: false         # follow the target version set in Settings › Agents
actions:
  enabled: false
  allow: [restart_service, start_service, stop_service]   # also: run_script, update_agent
  services: ["*"]
  deny_services: ["sshd*", "ssh*", "hypha-agent*", "systemd-*"]
  scripts:
    clear-cache: /etc/hypha/scripts/clear-cache.sh
  timeout: 120s
synthetics:
  enabled: false           # private synthetic test location
  max_concurrent: 4
inventory:
  enabled: true
  interval: 6h
  packages: true

Actions are off by default. The agent's own service is never touched, whatever the list. A named script must have an absolute path, belong to root and be writable neither by the group nor by others; it runs without arguments and its output is capped at 64 KiB. See Explain and repair and Fleet and updates.

SNMP

snmp:
  enabled: true
  interval: 60s
  devices:
    - {name: rack-1-switch, address: 192.0.2.10, version: 2c, community: readonly, tags: {role: switch}}
  traps: {enabled: false, listen: "0.0.0.0:162", community: public}

Versions, profiles and SNMPv3 settings are on the SNMP page. SNMP secrets stay in the agent's configuration: they never go to the server.

Updated: 20 November 2026