Collector fleet management

Three options. Pick by fleet size + how often config changes.

1. Per-instance config (default)

trefur init writes a config to ~/.trefur/collector.yaml (mode 0600). Edit it locally, restart the collector to pick up changes.

trefur init
$EDITOR ~/.trefur/collector.yaml
trefur collect

Best for single-machine installs, dev laptops, and one-off audits. Painful past 3 or 4 instances because every change is manual SSH.

2. Config management (Ansible / Puppet / Chef)

Treat collector.yaml as a checked-in artefact. Your existing config-management tool ships it to every host alongside the collector binary.

Minimal Ansible playbook:

---
- hosts: ai_agents
  become: true
  tasks:
    - name: Install trefur-collector (release binary)
      unarchive:
        # Replace <VERSION> with a release tag from the releases page.
        src: https://github.com/trefur-ai/trefur-collector/releases/latest/download/trefur-collector_<VERSION>_linux_amd64.tar.gz
        dest: /usr/local/bin
        remote_src: true
        mode: '0755'

    - name: Push canonical config
      copy:
        src: files/trefur-collector.yaml
        dest: /etc/trefur/collector.yaml
        mode: '0640'
        owner: trefur
      notify: restart trefur-collector

    - name: Ensure collector is enabled + running
      systemd:
        name: trefur-collector
        state: started
        enabled: true

  handlers:
    - name: restart trefur-collector
      systemd:
        name: trefur-collector
        state: restarted

Pin the config-file version with a hash (Ansible checksum: / Puppet content => file() with a known SHA-256). Trefur surfaces a drift alert when an instance reports a config hash that doesn't match the others in the fleet — which is how you catch a one-off manual edit on production.

Best for 4–50 instances and orgs that already standardise on Ansible / Puppet / Chef.

3. Remote-config (Trefur SaaS-side fleet manager)

Set one environment variable. The collector pulls its config from Trefur on startup and then every 5 minutes, hot-reloading on change. No restart needed.

export TREFUR_API_KEY=trf_coll_live_...
export TREFUR_REMOTE_CONFIG_URL="https://observe.trefur.com/api/v1/observe/collector/config/edge-fleet"
trefur collect

The edge-fleet at the end of the URL is the config name — multiple machines pointing at the same name share the same config. Edit it once in the web UI at /settings/observe/collector-config?name=edge-fleet and the change reaches every alive collector within 5 minutes.

Different fleets can pull different configs by using different names in the URL — e.g. edge-fleet for production hosts, dev-laptops for developer machines, with separate redaction or input settings on each.

Best for 50+ instances or any fleet where config changes more than once a week. See live fleet status at /observe/collectors.

Comparison

	Per-instance	Config-mgmt (Ansible / Puppet / Chef)	Remote-config
Recommended scale	1–3 instances	4–50 instances	50+ instances
Time to ship a config change	SSH + restart per host	Playbook run time	≤5 min, no restart (hot reload)
Change history — who changed what	None (manual)	Your VCS / playbook history	Built-in — every edit logged + diffed in the web UI
Drift detection	None	Hash-pinned (you set it up)	Built-in — collectors report config hash on every heartbeat
Works offline	Yes	Yes (between playbook runs)	Yes — last-known config is cached locally on every pull
Extra ops surface	None	Your config-mgmt cluster	None (handled SaaS-side)

Monitoring fleet health

Every collector heartbeats to Trefur every minute. The fleet view at /observe/collectors groups instances into three states.

Badge	Meaning	Typical cause
Alive	Heartbeat received within the last 5 minutes.	Normal operation.
Stale	Last heartbeat 5–30 minutes ago.	Transient network blip, host suspended (laptop closed), or the collector was sent a SIGSTOP.
Dead	No heartbeat for more than 30 minutes.	Host shut down, collector crashed without restart, API key revoked, or egress to `api.trefur.com` blocked.

Coverage telemetry (which inputs are actually receiving traffic on each instance) is at /observe/coverage — useful to spot a collector that's alive but receiving nothing because a feature flag turned off its only input.

Collector quickstart — install + run in 30 seconds with trefur collect --auto.
Configuration reference — every YAML field you can author in a fleet config.
Environment variables — every TREFUR_* the collector understands, including TREFUR_REMOTE_CONFIG_URL.