Collector quickstart

Install + run telemetry in 30 seconds.

macOS / Linux (Homebrew)

brew install trefur-ai/tap/trefur-collector
export TREFUR_API_KEY=trf_coll_live_...
trefur collect --auto

What --auto does

trefur collect --auto is a zero-config bootstrap. It picks safe defaults so you can be streaming telemetry without writing a single line of YAML.

  • Observe-only. No MITM, no blocking, no traffic rewrites. The collector only records what it sees and ships it to Trefur.
  • No CA install. The HTTP and LLM proxies stay in plain observe-mode — they emit a step per request without decrypting response bodies. Nothing on your machine has to trust a new certificate.
  • Sane port allocation. Standard OTLP ports (4317 gRPC, 4318 HTTP) plus health on :8888. If a port is already in use, the collector falls back to the next free one and logs which it picked.
  • OTel receivers + SDK proxy enabled. Any OpenTelemetry producer or Trefur SDK pointed at localhost immediately starts shipping.
  • Default redaction on. Passwords, tokens, API keys, and Authorization headers are stripped from shell-hook + proxy events before they leave your network.

Docker

docker run --rm \
  -e TREFUR_API_KEY=trf_coll_live_... \
  -p 4317:4317 -p 4318:4318 \
  ghcr.io/trefur-ai/trefur-collector:latest collect --auto

Other platforms (download a release binary)

Pre-built binaries for Linux, macOS, and Windows (amd64 + arm64) are attached to every GitHub release as a .tar.gz (Linux / macOS) or .zip (Windows). Extract it and put the trefur binary on your PATH.

# Linux / macOS — replace VERSION, OS, ARCH for your platform
curl -fsSL -o trefur-collector.tar.gz \
  https://github.com/trefur-ai/trefur-collector/releases/latest/download/trefur-collector_VERSION_OS_ARCH.tar.gz
tar -xzf trefur-collector.tar.gz

export TREFUR_API_KEY=trf_coll_live_...
./trefur collect --auto

Verify it's working

Open app.trefur.com/observe/coverage — within 60 seconds your collector shows up as alive and the coverage tiles light up for every input that received traffic.

If nothing lands within 90 seconds, check:

  • TREFUR_API_KEY is exported in the same shell as trefur collect --auto. The collector key must start with trf_coll_live_ (or trf_coll_test_).
  • The terminal running the collector shows no errors. Common ones are port-bind failures (already-in-use) or a network egress block on api.trefur.com:443.
  • Your firewall allows outbound HTTPS to api.trefur.com. Telemetry is push-only — no inbound ports need to be opened on your machine.

When to graduate to a real config

--auto is great for first-run and single-machine installs. Move to an explicit config when any of the following apply.

You want…What to do
Production fleets across multiple machinesSee Fleet management.
Opt-in blocking / enforcement (deny LLM calls, drop egress)Generate a config with trefur init and set policy fields explicitly.
MITM mode (full request + response bodies)Enable inputs.http_proxy.mitm: true and install the per-tenant CA — see Inputs reference.
Custom redaction patterns, drop rules, or routingUse the cloud-authored pipeline DSL (rules edited in the dashboard, pulled to the collector every 60s) or hand-edit ~/.trefur/collector.yaml.
Non-default ports / TLS termination at the collectorHand-edit the config — see Configuration reference.

Next