Docs / Install the agent

Install the agent

One binary, no inbound ports. Linux and FreeBSD packages, a container image, and a static build for everything else.

1. Install

# Debian / Ubuntu
curl -fsSL https://pkg.pingform.org/gpg | sudo tee /usr/share/keyrings/pingform.asc >/dev/null
echo "deb [signed-by=/usr/share/keyrings/pingform.asc] https://pkg.pingform.org/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/pingform.list
sudo apt update && sudo apt install pingform-agent

# Container
docker run -d --name pingform-agent \
  -e PINGFORM_TOKEN=pft_... \
  -v /etc/pingform:/etc/pingform:ro \
  ghcr.io/pingform/agent:2.9.4

2. Enrol

Create an agent token in the console, then run enrolment once. The token is exchanged for a client certificate stored in /var/lib/pingform/; the token itself is not kept on disk.

sudo pingform-agent enrol --token pft_7Qm2... --region eu-central

  ✓ resolved ingest endpoint   network.pingform.org:443
  ✓ negotiated transport       grpc (h2, gzip)
  ✓ workspace                  wk_8f3c91ba
  ✓ client certificate         valid until 2027-04-18
  ✓ schedule received          14 checks, 3 regions

3. Configure checks

# /etc/pingform/agent.yaml
workspace: wk_8f3c91ba
ingest:
  endpoint: network.pingform.org:443
  transport: grpc
  compression: gzip
  keepalive: 45s
  buffer:
    path: /var/lib/pingform/spool
    max_size: 256MiB
checks:
  - id: www
    type: http
    target: https://www.example.com/
    interval: 30s
    timeout: 5s
    from: [eu-central, eu-west, us-east, ap-south]
    expect: { status: 200, tls_min_days: 14 }
  - id: dns-apex
    type: dns
    target: example.com
    record: A
    interval: 60s
    from: [eu-central, us-east]

sudo systemctl enable --now pingform-agent
pingform-agent status

4. Verify connectivity

If the agent cannot reach its endpoint, run the built-in self-test. It fetches a 2 MiB fixed payload from the ingest host and reports throughput — this distinguishes a blocked connection from a slow one, and from a middlebox truncating the response.

pingform-agent selftest --endpoint network.pingform.org

  TLS handshake      ok   (TLS 1.3, X25519, 41ms)
  ALPN               h2
  payload            2097152 bytes in 0.38s  (5.5 MiB/s)
  grpc ping          ok   (18ms)

# equivalent by hand
curl -s -o /dev/null -w '%{size_download} %{time_total}\n' \
  https://network.pingform.org/_agent/v2/selftest/pf7k2m.bin

Troubleshooting