# Open-source Telemetry

CopilotKit uses metadata-only product telemetry to learn how to improve the
open-source packages.

- We do not collect prompts, messages, agent state, tool data, or other application content.
- We do not sell or share telemetry data with third parties.
- We do not use cookies or trackers for open-source telemetry.

## How to opt out of open-source telemetry [#how-to-opt-out-of-open-source-telemetry]

Set `COPILOTKIT_TELEMETRY_DISABLED=true` in your runtime environment. This
disables telemetry for both the CopilotRuntime and Inspector. We also respect
[Do Not Track (DNT)](https://consoledonottrack.com/).

## Telemetry identity [#telemetry-identity]

Runtime uses the first nonblank telemetry identity that is valid in an HTTP
header, in this order: explicit `telemetryId`, `CPK_TELEMETRY_ID`, then the
identity carried by `COPILOTKIT_LICENSE_TOKEN`.

`CPK_TELEMETRY_ID` is optional and non-secret. When CLI telemetry is on and you
select a cloud-hosted project, the CopilotKit CLI writes `CPK_TELEMETRY_ID` to
`.env`. A value that you choose yourself does not link Runtime events to a CLI
scaffold event. Setting it does not enable
telemetry, grant product access, or replace the project's Intelligence API key.

Cloud-hosted Intelligence starters use `CPK_INTELLIGENCE_API_KEY` for platform access.
The project API key is not a telemetry identity.

Cloud-hosted setup does not issue `COPILOTKIT_LICENSE_TOKEN`. That token is
only for offline or self-hosted licensing, so a cloud-hosted starter carries no
license-token identity. When a self-hosted deployment sets the token, it
supplies the fallback identity. With none of these identities, Runtime sends
anonymous telemetry.

The Inspector stores a random browser ID in local storage and sends it directly
with feature-use events. CopilotKit signup links can carry that ID so we can
measure the path from Inspector use to signup. Inspector delivery does not
depend on `CPK_TELEMETRY_ID`.

## Inspector metadata events [#inspector-metadata-events]

The Inspector sends coarse events when trusted project-context modules become
visible and when a user follows a plan action:

| Event                                   | Feature-specific properties                                                                      |
| --------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `oss.inspector.metadata_module_viewed`  | `module`, `license_bucket`, and `action_kind` when the visible module is an action               |
| `oss.inspector.metadata_action_clicked` | `module: "action"`, `action_kind`, and `license_bucket` for **Manage plan** and **Renew** clicks |

`module` is `identity`, `plan`, or `action`. `action_kind` is `manage_plan`,
`renew`, or `enable_intelligence`. `license_bucket` is `valid`, `none`,
`expired`, or `unknown`.

An **Enable Intelligence** click sends
`oss.inspector.threads_intelligence_signup_clicked`. It does not send
`oss.inspector.metadata_action_clicked`.

The feature-specific payload never includes:

- Organization, project, account, or user names.
- Account, organization, project, user, thread, run, or message IDs.
- Action or runtime URLs.
- Usage values, limits, or counts.
- Conversation or tool content.

Metadata usage impressions are not sent. The standard anonymous
telemetry envelope includes package identity, anonymous distinct IDs, and an
event timestamp.

## Agent framework event [#agent-framework-event]

The first time each agent runs, Runtime sends
`oss.runtime.agent_identified` for that agent. It sends the event once per
agent for each server process, so a restart or a new serverless instance
sends it again. It tells us which agent frameworks people use, so we know
which integrations to keep current.

| Property          | Value                                                                                  |
| ----------------- | -------------------------------------------------------------------------------------- |
| `framework`       | The framework the agent's adapter declares, such as `mastra` or `langgraph`. A value we do not list is sent as `other`. An agent that declares nothing is sent as `undeclared`. |
| `adapter_version` | The version of the adapter package, when the adapter declares one.                     |
| `via_http_agent`  | `true` when the agent is a generic AG-UI `HttpAgent`.                                  |
| `source`          | Always `declared`.                                                                     |

The event never includes agent names, descriptions, URLs, or any other text
that you write.

## Get in touch [#get-in-touch]

Send telemetry questions to [hello@copilotkit.ai](mailto:hello@copilotkit.ai).
