# Telemetry
Source: https://dorkos.ai/docs/self-hosting/telemetry
What the anonymous DorkOS heartbeat sends, how to turn it off, and the anonymous-by-default promise
DorkOS shares a little anonymous data by default so we can see roughly how many people run it. It is anonymous, not personal: no prompts, no code, no file paths, no session content, ever. This page shows the exact data, word for word, and every way to turn it off.
The three anonymous channels (a daily heartbeat, marketplace install counts, and a few named
feature-usage events) are on by default. DorkOS prints a first-run notice and sends nothing on
that first run. Crash reporting is separate and stays off until you turn it on. You can change any
of this anytime.
## The short version [#the-short-version]
* Three anonymous channels are on by default: a daily heartbeat, marketplace install counts, and a few named feature-usage events.
* On first run, DorkOS shows a notice and sends nothing that run. If you do nothing, sharing begins next launch.
* It is anonymous. No prompts, no code, no file paths, no session content, ever.
* Turn it off any time: `dorkos telemetry disable`, `DO_NOT_TRACK=1`, or the Privacy & Data settings tab.
* The full payload is documented here and enforced in code and tests.
* The public version of this page lives at [dorkos.ai/telemetry](https://dorkos.ai/telemetry).
## What the heartbeat sends [#what-the-heartbeat-sends]
DorkOS sends one small message to dorkos.ai about once a day. This is how we can even roughly count how many people actively run DorkOS. Here is the whole payload:
```json
{
"instanceId": "a1b2c3d4-e5f6-...",
"dorkosVersion": "0.47.0",
"os": "darwin-arm64",
"runtimesConfigured": ["claude-code", "codex"],
"tunnelEnabled": false,
"cloudLinked": false,
"counts": { "agents": 4, "tasks": 2, "relayAdapters": 1 }
}
```
| Field | What it is |
| -------------------- | ----------------------------------------------------------------------------------------------------------- |
| `instanceId` | A random id created on your machine. Marks one install so we do not double-count you. Not traceable to you. |
| `dorkosVersion` | Which version of DorkOS you are running. |
| `os` | Your platform and chip type, like `darwin-arm64`. Not your hostname. |
| `runtimesConfigured` | Which agent runtimes you have turned on, like Claude Code or Codex. |
| `tunnelEnabled` | Whether you use the tunnel to reach DorkOS from your phone. True or false only. |
| `cloudLinked` | Whether this install is linked to a DorkOS account. True or false only. |
| `counts` | Rough totals of your agents, tasks, and relay adapters. Just numbers, never their names or contents. |
## What it never sends [#what-it-never-sends]
The list above is the complete payload. It is enforced in code and in tests, so nothing sneaks in. It never includes your prompts, your code, file paths, your hostname or username, IP address, or anything from your sessions. This is what makes it anonymous rather than personal, and it is why we can turn it on by default. If we ever want to add a field, we update this page first.
## We tell you before anything sends [#we-tell-you-before-anything-sends]
The first time DorkOS starts, it prints a plain notice in its log: what it shares, a link to the payload, and how to turn it off. Nothing is sent on that first run. If you do nothing, the daily heartbeat, install counts, and feature-usage events begin on the next launch. If you turn them off first, they never start. This ordering is enforced in code (the send gate is captured before the notice is recorded), so a first-run boot never sends.
## Marketplace installs [#marketplace-installs]
The marketplace install-count channel is on by default too, and it helps rank packages and spot broken installs. It follows the same no-PII rule and is documented on the [marketplace privacy page](https://dorkos.ai/marketplace/privacy).
## Feature-usage events [#feature-usage-events]
DorkOS can send a short list of named, anonymous events so we can see which features actually get used and where people drop off. These are curated events, not a firehose: DorkOS never auto-captures your clicks or screens. Every event is defined in one place in the source (the shared event registry) and validated against a strict allowlist, so an event can only ever carry the exact fields listed below.
Two events ship today:
| Event | When it fires | What it carries |
| ----------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `app_started` | Once when the DorkOS server starts. | `os` (your platform and chip type, like `darwin-arm64`) and `runtimesConfigured` (a count of how many agent runtimes you have on). |
| `session_created` | Once when a new agent session is first run. | `runtime` (which runtime owns the session, like `claude-code`). Never the folder, the prompt, or the session id. |
Each event is wrapped in the same anonymous envelope as everything else: your random `instanceId`, a timestamp, and your DorkOS version. Like the heartbeat, it never includes your prompts, your code, file paths, your hostname or username, or anything from your sessions.
Like the heartbeat and install counts, this channel is on by default, in line with how tools like VS Code and Homebrew count usage. Two things still protect you: nothing sends until after DorkOS has shown you the first-run notice, and you can turn it off three ways, the same as every other channel:
* Flip `telemetry.usage` to `false` in `~/.dork/config.json` (or use the **Privacy & Data** tab, or `dorkos telemetry disable --channel usage`).
* Set `DO_NOT_TRACK=1` or `DORKOS_TELEMETRY_DISABLED=1` to silence this and every other channel at once.
* Preview it first with `DORKOS_TELEMETRY_DEBUG=1`, which prints the exact events to your terminal instead of sending them.
If you already answered the first-run consent prompt on an older version, an upgrade leaves this channel off for you: an explicit choice is never widened without asking again.
## Feedback (only when you press Send) [#feedback-only-when-you-press-send]
DorkOS has a **Send feedback** button in the help menu, and there is a feedback form on the website too. This is not telemetry. It is a message you write and choose to send: general feedback, a bug, or an idea. Because you are deliberately sending it, it does not follow the anonymous-telemetry rules above.
* It is sent **only when you press Send**. Nothing about feedback goes out on its own.
* It carries exactly what you typed: your message, and a contact detail if you chose to add one. It also notes which screen you were on and your DorkOS version, so we have context.
* It ignores the telemetry switches. `DO_NOT_TRACK`, `DORKOS_TELEMETRY_DISABLED`, and the Privacy & Data toggles turn off tracking, not the Send button. If you press Send, your message reaches us, because that is what you asked for. If you never press it, nothing is sent.
Prefer a public thread? The help menu also has **Report a bug on GitHub** and **Request a feature on GitHub**, which open a prefilled issue you review and edit before submitting.
## Error reporting (a separate opt-in) [#error-reporting-a-separate-opt-in]
DorkOS can also send a crash report when something breaks, so we can fix it without asking you for your log files. Unlike the anonymous heartbeat, this one is off until you turn it on:
* It goes to dorkos.ai, the same place as the heartbeat, and nowhere else. There is no third party and nothing to set up.
* It sends the error type and a cleaned-up stack trace (which function, file, and line) and nothing else. It does **not** send the error message text, because a message can contain anything your code put in it. No prompts, no code, no file paths, no session data.
Before anything leaves your machine, home directories and full file paths are stripped so no username can leak, and anything shaped like a key, token, or password is redacted. To turn it on, set `telemetry.errorReporting: true` in your config. That is the only switch. Leave it off (the default) and nothing is reported.
Want to see exactly what a crash report looks like before it sends? Set `DORKOS_TELEMETRY_DEBUG=1`
and DorkOS prints the crash payload to your terminal instead of sending it.
## Linking analytics to your account (a separate opt-in) [#linking-analytics-to-your-account-a-separate-opt-in]
When you link this install to a DorkOS account, you can also connect this install's anonymous usage counts to your account, so you can see them when you are signed in on dorkos.ai. Like crash reports, this is off until you turn it on, and it never sends anything new: it only ties the counts you already share to your account.
* It is off by default. You turn it on with a checkbox in the account-link flow, right before you link, in Settings under DorkOS account.
* It only takes effect at link time. If you link first and turn it on later, the connection happens the next time you link, not retroactively.
* The environment kill switches turn it off too: with `DO_NOT_TRACK=1` or `DORKOS_TELEMETRY_DISABLED=1` set, nothing is connected even if the checkbox is on.
* No new data is collected. It is the same anonymous usage counts described above, now visible under your account.
To undo it: turn the checkbox off (it takes effect on your next link), and remove the already-connected data from your account page on dorkos.ai. Unlinking the instance stops it from reporting further.
## AI run metadata (a separate opt-in) [#ai-run-metadata-a-separate-opt-in]
Every time an agent finishes a turn, DorkOS knows a few plain facts about it: which model ran, how many tokens it used, how long it took, and what it cost. You can choose to share a short summary of those facts with us, so we can see how the different runtimes compare. Like crash reports, this is **off until you turn it on**.
* It goes to dorkos.ai, the same place as everything else, and nowhere else.
* Each turn sends one small summary: the model, the runtime (Claude Code, Codex, or OpenCode), the input and output token counts, the turn's time, and its cost.
* It carries **no** prompt, **no** code, **no** file path, and **nothing** you or the agent said. It is counts and a model name, full stop.
This is the same AI data DorkOS can already put on your own traces (see [observability](/docs/self-hosting/observability)). That side is always yours and never reaches us. This setting is the opposite direction: it, and only it, shares those counts with DorkOS, and only when you turn it on.
To turn it on, set `telemetry.aiMetadata: true` in your config (or use the **Privacy & Data** tab). To preview it first, run with `DORKOS_TELEMETRY_DEBUG=1` and DorkOS prints each summary to your terminal instead of sending it. `DO_NOT_TRACK=1` and `DORKOS_TELEMETRY_DISABLED=1` turn it off along with everything else.
## Debug tracing (a separate, local-only flag) [#debug-tracing-a-separate-local-only-flag]
`dorkos --debug-trace` is a diagnostics tool, not part of the telemetry above, and it isn't covered by the opt-in banner: it's a per-run flag you choose to add when you're troubleshooting something, most often because we asked you to when you report a bug.
When it's on, DorkOS writes a local file recording how long things took: session turns, agent calls, relay messages, and task runs, plus counts. It never records your prompts, your code, file paths, or anything else you typed. The file is written to `~/.dork/traces/` and never leaves your machine unless you attach it to a bug report yourself; there is no network sender for it at all.
```bash
dorkos --debug-trace
```
You can also set it with an environment variable: `DORKOS_OTEL_DEBUG=true`. Either way, it's off
by default and stays off unless you turn it on for that run.
## Turn everything off from the environment [#turn-everything-off-from-the-environment]
Two environment variables force **every** channel off, no matter what your config says. They beat the config, so they are the fastest way to silence DorkOS in a shared image, a CI runner, or a locked-down machine:
* `DO_NOT_TRACK` is the universal, cross-tool convention. Set it to `1` (or `true`) and DorkOS sends nothing.
* `DORKOS_TELEMETRY_DISABLED` does the same thing but only affects DorkOS.
```bash
export DO_NOT_TRACK=1
# or
export DORKOS_TELEMETRY_DISABLED=1
```
Either one on its own is enough. When a kill switch is set, no channel sends anything even if its config flag is `true`.
## See and change it from the command line [#see-and-change-it-from-the-command-line]
`dorkos telemetry` shows and controls the same channels without opening the app:
```bash
dorkos telemetry status # show each channel and any env override
dorkos telemetry enable # turn on all channels
dorkos telemetry disable # turn off all channels
dorkos telemetry enable --channel heartbeat # turn on just one (install | heartbeat | errors | usage)
dorkos telemetry disable --channel errors # turn off just one
```
`status` tells you each channel's state, whether a kill switch is overriding it, and whether you have already made a choice. `enable` and `disable` write your choice to `~/.dork/config.json` so the first-run banner never asks again.
## Preview the exact payload before it sends [#preview-the-exact-payload-before-it-sends]
Set `DORKOS_TELEMETRY_DEBUG=1` and DorkOS prints the exact JSON payloads for the heartbeat, install, and feature-usage channels to your terminal (stderr) **instead of sending them**. Nothing goes over the network in debug mode, so you can read, word for word, what would leave your machine:
```bash
DORKOS_TELEMETRY_DEBUG=1 dorkos
```
## How to turn it off (or back on) [#how-to-turn-it-off-or-back-on]
The first time you open DorkOS, a banner discloses that it shares anonymous data and shows you the payload above, with a **Keep sharing** and a **Turn off** button. To change it later, open settings (there's a **Privacy & Data** tab with a switch for each channel), use `dorkos telemetry` above, or edit `~/.dork/config.json`:
```json
{
"telemetry": {
"heartbeat": true,
"install": true,
"errorReporting": false,
"usage": true,
"aiMetadata": false,
"userHasDecided": true
}
}
```
Set a value to `false` to turn a channel off, or `true` to turn it on. The three anonymous channels default to `true`; error reporting and AI run metadata default to `false`, and each one's flag is the only switch it needs.
Anonymous by default is the norm for developer tools, from Next.js to VS Code to Homebrew. We keep
it genuinely anonymous, show you the whole payload, and make turning it off a one-liner. Your code
and your chats with the AI never leave your machine, default or not.
## When this changes [#when-this-changes]
DorkOS moves fast. If what the heartbeat sends ever changes, we update this page and the public [dorkos.ai/telemetry](https://dorkos.ai/telemetry) page before the change ships. No quiet edits.