Quickstart
Three steps: create a key, set the exporter, read the score. No account, no card.
1. Create a key
Section titled “1. Create a key”With a webhook URL for alerts (https only). Kyde posts to it on every band change:
curl -s https://score.kyde.com/score/v0/keys \ -H 'content-type: application/json' \ -d '{"webhook_url": "https://your.app/hooks/kyde"}'Or poll-only, without a body:
curl -s -X POST https://score.kyde.com/score/v0/keysBoth return {"key": "kyde_…", "method_version": "…", "webhook": …}. Store the key like a password. It cannot be shown again; if you lose it, create a new one.
Attach a human to the key (claim)
Section titled “Attach a human to the key (claim)”Right after creating the key, the agent asks its human once for an email address for the dashboard. This question is required: the agent always asks it before it reports setup as done. Saying yes is optional.
- Yes: the agent passes the address with the
claim_keytool (orPOST /score/v0/keys/claim). Kyde sends a confirmation link, and nothing changes until the human clicks it. The claimed key gets the dashboard for all agents under it, and resetting a baseline, changing the webhook and deleting the key become human-only actions. - No, or no answer: setup continues without it. Everything else keeps working, just without the human control layer.
The agent never guesses or invents an address. Product updates are a separate question and stay off unless the human says yes to them explicitly. Details in the skill.
2. Point the exporter at Kyde
Section titled “2. Point the exporter at Kyde”Give every agent its own OTEL_SERVICE_NAME. That name is what Kyde scores.
Codex, OpenCode, LangChain, your own code: these four variables are the whole integration.
export OTEL_EXPORTER_OTLP_ENDPOINT=https://score.kyde.comexport OTEL_EXPORTER_OTLP_PROTOCOL=http/protobufexport OTEL_EXPORTER_OTLP_HEADERS="x-kyde-key=<KEY>"export OTEL_SERVICE_NAME=invoice-agentKyde accepts OTLP/HTTP as protobuf or JSON. http/protobuf works from every SDK; http/json exists only in the JavaScript ones. Framework agents need a GenAI instrumentation that emits gen_ai tool spans; other spans are ignored. Metrics are accepted but not scored.
Split the variables by how they vary.
Global, once per machine: endpoint, protocol, key header and the two telemetry flags. Put them in the env block of your user-level ~/.claude/settings.json (covers terminal, IDE and desktop app) or in your shell profile. They are the same for every agent on the machine.
export CLAUDE_CODE_ENABLE_TELEMETRY=1export OTEL_LOGS_EXPORTER=otlpexport OTEL_EXPORTER_OTLP_PROTOCOL=http/jsonexport OTEL_EXPORTER_OTLP_ENDPOINT=https://score.kyde.comexport OTEL_EXPORTER_OTLP_HEADERS="x-kyde-key=<KEY>"Per agent, at launch: OTEL_SERVICE_NAME only. Set it in the command that starts the agent, in a wrapper script (export it, then exec claude "$@"), or in the workflow or service unit that launches the agent.
env OTEL_SERVICE_NAME=invoice-agent claudeNever put OTEL_SERVICE_NAME into ~/.claude/settings.json. The settings env block overrides the launch environment, so one global name silently merges every agent on the machine into a single baseline, and per-launch names lose without any error. Leaving the name unset is the same trap: Claude Code then reports as claude-code, and all agents merge under that default. If you followed these docs before November 10, 2026, remove OTEL_SERVICE_NAME from your settings first.
Claude Code ignores OTel exporter variables in a project’s .claude/settings.json and .claude/settings.local.json.
Grok CLI needs its own opt-in. Its exporter sends protobuf only:
export GROK_EXTERNAL_OTEL=1export OTEL_LOGS_EXPORTER=otlpexport OTEL_EXPORTER_OTLP_PROTOCOL=http/protobufexport OTEL_EXPORTER_OTLP_ENDPOINT=https://score.kyde.comexport OTEL_EXPORTER_OTLP_HEADERS="x-kyde-key=<KEY>"Grok CLI always reports service.name as grok-cli and ignores OTEL_SERVICE_NAME, so all Grok CLI agents under one key score as one agent.
Recommended when telemetry has to be scrubbed before it leaves your network. Add an exporter:
exporters: otlphttp/kyde: endpoint: https://score.kyde.com encoding: json headers: x-kyde-key: <KEY>You can delete or hash attributes in the Collector first. Kyde still scores.
3. Read the score
Section titled “3. Read the score”Run the agent once, then:
curl -s https://score.kyde.com/score/v0/scores -H "x-kyde-key: <KEY>"The agent shows up with "status": "learning" and a runs_seen count. After 30 runs over at least 3 days it switches to "status": "scored" with a score and a band. There is nothing to configure for that.
The integration is done when both are true: your agent’s own service.name appears here with runs_seen of at least 1, and the human was asked once for an email address for the dashboard (a no counts as asked). A created key, a claim or an active dashboard alone is setup, not an integration. Never install a different agent product as a substitute to get telemetry.
Nothing listed? Check that the protocol is http/json or http/protobuf and the header is spelled x-kyde-key. The skill has a curl smoke test that sends one record under a throwaway service name, so it never enters a real agent’s baseline.
degraded in the response? Records were dropped because of a limit. See Limits.
- API: all endpoints, the webhook, deleting a key
- For agents: the MCP server, so an agent can check its own score