Control-plane setup

The end-to-end self-serve sequence: sign in from the CLI, create or pick a workspace, get a key, register an agent, wire an SDK, and confirm your first trace. A clean run reaches a first trace in a few minutes.

1. Sign in from the CLI

Install the Trefur CLI, then sign in. One command creates (or joins) a workspace and provisions a key. It opens a browser for a single approval; on a machine with no browser — CI, a remote shell — it falls back to a device-code flow you approve from any browser.

# 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. Then sign in:

A Homebrew tap is on the way. Until it lands, use the one-line installer above or the prebuilt archive — both give you the same trefur binary.
trefur init --bootstrap --email=you@example.com --workspace="My Workspace"
The approval screen confirms the workspace before it is created — the CLI never creates an account silently. Add --no-browser to force the device-code path, or --api-url <url> to target a non-production deployment.

2. Your provisioning key is stored for you

On success the CLI writes the key to ~/.trefur/config.yaml (readable only by you). It is an Observe key — the trf_obs_ prefix — scoped to register agents and read your workspace's own traces. Treat it as a secret: read it from an environment variable in your code, never commit it.

This Observe key is distinct from a self-hosted collector's ingest key (the trf_coll_ prefix). If you run the collector as a long-lived service, mint a dedicated collector key in the dashboard rather than reusing the CLI key.

3. Register an agent

An agent registers automatically the first time the SDK sends telemetry under its agent name. Set the name once via the TREFUR_AGENT_NAME environment variable (or in the SDK config). List what is registered at any time:

trefur agent list

4. Wire an SDK

Install the SDK for your language and initialise it with the key — or let the CLI detect your framework and inject the wiring for you:

trefur instrument

Prefer to do it by hand? The per-language one-liners live in the Quickstart. For example, 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());

5. Confirm your first trace

Run your agent so it makes at least one LLM or tool call, then list runs to confirm the trace arrived:

trefur observe runs

You can also open app.trefur.com to see the run in the UI. 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.

A note on keys

Trefur uses purpose-specific keys. The CLI provisions an Observe ingest key (trf_obs_) used by the SDKs to send telemetry. The CLI's own usage telemetry — opt-in, off by default — is unrelated to your ingest key and carries no payloads. The two never mix.

What's next?