Control-plane setup

The end-to-end self-serve sequence: create a workspace, mint a key, send telemetry (SDK or collector), and confirm the first trace in the app. A clean run reaches a first trace in a few minutes. Every command below exists in the shipped trefur binary.

1. Create a workspace and mint a key

Sign up at app.trefur.com — a workspace is created for you. The onboarding setup step mints a workspace API key for you, or mint one later under Settings → Platform → API keys. It starts with trf_live_ and is shown once; copy it into an environment variable:

export TREFUR_API_KEY=trf_live_...
The key is minted in the dashboard, not by the CLI. The CLI never creates an account or a workspace.

2. Install the binary

# macOS / Linux — one-line installer
curl -fsSL https://raw.githubusercontent.com/trefur-ai/trefur-collector/main/scripts/install.sh | bash

Prefer a standalone binary? Download a prebuilt archive for your platform (Linux / macOS / Windows, amd64 + arm64) from GitHub Releases and put the trefur binary on your PATH.

3. Send telemetry

Two paths, same backend. Wire an SDK into the agent you own, or run the collector next to processes you cannot edit.

SDK — three lines in your agent

The per-language one-liners live in the Quickstart. In JavaScript:

npm install @trefur/observe
import OpenAI from 'openai';
import { TrefurObserve, patchOpenAI } from '@trefur/observe';
TrefurObserve.init({
  apiKey: process.env.TREFUR_API_KEY!,
  agent: { name: process.env.TREFUR_AGENT_NAME ?? 'my-agent' },
});
patchOpenAI(OpenAI, TrefurObserve.getInstance());

Collector — zero config

trefur collect --auto

--auto enables every input in observe-only mode (no MITM, no blocking) with a built-in default config; it reads TREFUR_API_KEY from the environment. Want a config file instead? trefur init is an interactive wizard that writes ~/.trefur/collector.yaml; trefur validate checks the resolved config; --remote-config <url> pulls a dashboard-authored config every five minutes.

Wrap a process with the edge runtime

trefur run -- python my_agent.py

run wraps a local agent process with the verify-gate enforcement runtime. --api-url targets a non-production deployment; --proxy opts in to the MITM proxy; --enforce kernel adds the Linux sandbox.

4. Register an agent

An agent registers automatically the first time telemetry arrives under its agent name. Set the name once via the TREFUR_AGENT_NAME environment variable (or in the SDK config). Registered and discovered agents are listed under Observe → Agents in the app.

5. Confirm your first trace

Run your agent so it makes at least one LLM or tool call, then open Observe → Runs: the run appears within seconds. From the CLI, trefur coverage renders the declared × observed × governed tool matrix and trefur gaps lists tool surfaces that are observed but not governed. If nothing shows up, check that the SDK is initialised before the agent's first call and that the key is set in the environment the process actually runs in.

A note on keys

Trefur uses purpose-specific keys. The workspace key (trf_live_, minted in the dashboard) is what the SDKs and the collector use to send telemetry. An agent key (trf_obs_live_, minted on an agent's Config tab) authenticates the MCP server. A collector key (trf_coll_live_) is for long-lived self-hosted collector fleets. The CLI's own usage telemetry — opt-in, off by default — is unrelated to any of them and carries no payloads.

What's next?