Trefur collector

Single binary for AI agent telemetry. Multiple ingest paths in one process, with a cloud-authored pipeline DSL and an encrypted on-disk buffer for offline durability.

Install

The collector's installer, release archives and container image are available at launch. The commands below are what you will run; until then they are shown commented out.

One-line installer (macOS / Linux)

# Available at launch. Not published yet, so this is commented out and does nothing if pasted.
# curl -fsSL https://raw.githubusercontent.com/trefur-ai/trefur-collector/main/scripts/install.sh | bash

Detects your platform via uname and writes the binary to ~/.trefur/bin/trefur. Pin a specific version with ... | bash -s -- <VERSION>, using a release tag from the releases page (available at launch). A Homebrew tap is not published yet; the installer and the release archives below install the same trefur binary.

Docker

# Available at launch. Not published yet, so this is commented out and does nothing if pasted.
# docker run -d \
#   -e TREFUR_API_KEY=trf_coll_live_${YOUR_KEY_HERE} \
#   -p 4317:4317 -p 4318:4318 -p 9090:9090 -p 8888:8888 \
#   -v /path/to/config.yaml:/etc/trefur/trefur-collector.yaml \
#   ghcr.io/trefur-ai/trefur-collector:latest

Publishing 9090 only helps if the SDK proxy leaves loopback: in the mounted config set inputs.sdk_proxy.addr: "0.0.0.0:9090" and allow_non_loopback: true. By default it binds 127.0.0.1 and refuses anything else at boot.

Manual download

Each GitHub release carries pre-built archives for darwin, linux and windows, each for amd64 and arm64. SHA-256 checksums are signed alongside; verify before extracting. Archive names carry no version, so these URLs always fetch the newest release; to pin one, use /releases/download/<tag>/ in place of /releases/latest/download/.

# Available at launch. Not published yet, so this is commented out and does nothing if pasted.
# curl -fsSLO "https://github.com/trefur-ai/trefur-collector/releases/latest/download/trefur-collector_darwin_arm64.tar.gz"
# curl -fsSLO "https://github.com/trefur-ai/trefur-collector/releases/latest/download/checksums.txt"
# shasum -a 256 -c checksums.txt --ignore-missing

Quickstart

# 1. Get a collector API key from the dashboard.
# 2. Generate a config (writes to ~/.trefur/collector.yaml, mode 0600):
trefur init

# 3. Export the API key. The YAML uses ${TREFUR_API_KEY} interpolation —
#    the literal secret never lands on disk.
export TREFUR_API_KEY=trf_coll_live_${YOUR_KEY_HERE}

# 4. (Recommended) validate the config — exits 0 on success, 1 on failure.
trefur validate

# 5. Run.
trefur collect

Config-file lookup order

  1. --config <path> flag
  2. $TREFUR_COLLECTOR_CONFIG env var
  3. $XDG_CONFIG_HOME/trefur/collector.yaml
  4. ~/.trefur/collector.yaml (default target for trefur init)
  5. ./trefur-collector.yaml (cwd fallback)

Default port allocation

PortPurposeOverride
4317OTel gRPC receiverinputs.otel.grpc_addr
4318OTel HTTP receiverinputs.otel.http_addr
8888Health + Prometheus metricshealth.listen_addr (auto-fallback :8889..:8897, skipping any port already bound by another input such as the shell hook)
8889Shell hook + exec wrapperinputs.shell_hook.addr
8890HTTP forward proxyinputs.http_proxy.addr
9090SDK proxy (loopback by default; set allow_non_loopback: true to publish it)inputs.sdk_proxy.addr
9091LLM proxyinputs.llm_proxy.addr
9092MCP proxyinputs.mcp_proxy.addr

These are the defaults used by trefur collect --auto and a minimal hand-written config. If you generated your config with trefur init, the wizard writes explicit addr values into ~/.trefur/collector.yaml — use the addresses in that file (e.g. when pointing an SDK at the SDK proxy) rather than assuming the defaults above.

Resource footprint

MetricIdle~50 evt/s~1000 evt/s
Resident memory (RSS)~50 MB~80 MB~150 MB
CPU (1 core)<1%2–4%15–25%
Network egress~1 KB/min~50 KB/min~1 MB/min (gzip)

Next