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

Homebrew (macOS / Linux)

brew install trefur-ai/tap/trefur-collector

Or, two-step: brew tap trefur-ai/tap then brew install trefur-collector.

Curl one-liner

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> (use a release tag from the releases page).

Docker

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

Manual download

Pre-built archives for darwin amd64 + arm64, linux amd64 + arm64, and windows amd64 are published with each GitHub release. SHA-256 checksums are signed alongside; verify before extracting:

# Replace <VERSION> with the release tag from the releases page (e.g. from
# https://github.com/trefur-ai/trefur-collector/releases/latest).
curl -fsSLO "https://github.com/trefur-ai/trefur-collector/releases/latest/download/trefur-collector_<VERSION>_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

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

Default port allocation

Port	Purpose	Override
4317	OTel gRPC receiver	`inputs.otel.grpc_addr`
4318	OTel HTTP receiver	`inputs.otel.http_addr`
8888	Health + Prometheus metrics	`health.listen_addr` (auto-fallback :8889..:8897, skipping any port already bound by another input such as the shell hook)
8889	Shell hook + exec wrapper	`inputs.shell_hook.addr`
8890	HTTP forward proxy	`inputs.http_proxy.addr`
9090	SDK proxy	`inputs.sdk_proxy.addr`
9091	LLM proxy	`inputs.llm_proxy.addr`
9092	MCP proxy	`inputs.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

Metric	Idle	~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)

Configure inputs — OTel, LLM proxy, MCP proxy, shell hook, exec wrapper, HTTP proxy.
Deep host capture (eBPF) — kernel-level process capture with zero code changes.
Ports & networking — every listener, all configurable, fail-fast on a clash.
Configuration reference — every YAML field, secrets management, TLS, buffering.
Environment variables — every TREFUR_* variable supported by the collector.