--- title: Privacy and telemetry description: "relate, the embedded Cypher graph database (relatedb.ai): The anonymous usage events the relate CLI sends and how to turn them off, the surfaces that never send anything, and what the relatedb.ai site loads and logs." type: reference surfaces: - cli - python - node - browser - bolt - http - mcp - agents status: stable verified: 0.1.2 verified_by: - cli canonical_url: https://relatedb.ai/docs/reference/privacy-and-telemetry/ prerequisites: [] related: - reference/security - reference/project - reference/cli/flags - guides/agents/run-in-a-sandbox - concepts/security-and-trust last_updated: 2026-11-10 --- # Privacy and telemetry The anonymous usage events the relate CLI sends and how to turn them off, the surfaces that never send anything, and what the relatedb.ai site loads and logs. > Verified against relate 0.1.2. If your `relate --version` is newer, read https://relatedb.ai/docs/reference/changelog/#since-0.1.2 The `relate` CLI binary sends anonymous usage metrics to Mixpanel. They are on by default, and `DO_NOT_TRACK=1`, `RELATE_TELEMETRY=0`, or `relate telemetry off` turns them off. The events carry command shapes and a random install ID; query text, [store](https://relatedb.ai/docs/reference/glossary/#store) paths, and [parameter](https://relatedb.ai/docs/reference/glossary/#parameter) values are never collected, because the code that builds an event has no field to hold them. The client libraries, the WebAssembly build, the C library, and the served [surfaces](https://relatedb.ai/docs/reference/glossary/#surface) never send usage metrics. Today the docs, cookbook, and playground pages load nothing from a third party with the page. One recipe downloads an embedding model from Hugging Face, and only when the reader presses the button that states its size. ## Synopsis | Surface | Sends usage metrics | Network access it starts on its own | | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `relate` CLI (release binary) | Yes, unless turned off | Only the usage metrics. `relate upgrade`, `relate extension install`, `--load `, `--fetch-params`, `pull`, and `push` reach the addresses they are given or document, and only when run | | `relate serve` (HTTP, [MCP](https://relatedb.ai/docs/reference/glossary/#mcp), Bolt) | One `RELATE-CLI_COMMAND` event when the server exits; statements it serves send nothing | Only that one usage metrics event, unless turned off | | Python, Node.js, Java, Go, Swift, and Rust clients, and the C library | Never | None | | WebAssembly (WASM) build | Never | None | | `agent` and `minimal` CLI builds, from source | Never; the usage metrics code is not compiled in | `agent`: only `pull`, `push`, `--fetch-params`, `--load `, and `extension install`, when run. `minimal`: none | ## The first-run notice The first statement run with usage metrics on, whether a one-shot statement, piped stdin, or the REPL, prints one line to stderr, whether or not stdin is a terminal: ```text relate collects anonymous usage metrics; disable anytime: relate telemetry off ``` It prints once per install: a `notice_shown` flag in `state.json` stops it repeating. `--version`, `--help`, and the commands (`serve`, `skill`, `upgrade`, `telemetry`, `extension`, `run`, and the rest) never print it, and they send their events whether or not it has been shown. So a first command on a new install, such as `relate --version`, sends an event before any notice has appeared. A run with usage metrics turned off never prints it and sends nothing. ## Events The CLI sends four events. This table is the disclosure: | Event | Event-specific properties | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `RELATE-CLI_STARTUP` | `kind`: `oneshot`, `stdin`, `repl`, `version` or `help` | | `RELATE-CLI_QUERY` | `success` (true or false); `source`: `oneshot`, `stdin` or `repl`; `storage`: `memory` or `persistent`; `output_mode`: `table`, `csv`, `json`, `jsonl`, `toon`, `markdown` or `cypher`, the mode actually used (`--mode envelope` and `--mode speedscope` report `json`) | | `RELATE-CLI_COMMAND` | `command`: the command word, such as `skill`, `upgrade`, `telemetry`, `pull`, `serve` or `run`; `action`: the sub-action, such as `install` (`run` reports `extension`, never the extension's name; left out for a command with no action); `success` (true or false) | | `RELATE-CLI_HELP` | None beyond the base properties | Every event also carries these properties: | Property | Meaning | | ------------- | ------------------------------------------------------------------------------------------------------------------------ | | `token` | The Mixpanel project token compiled into the binary | | `time` | The event time, in milliseconds since the Unix epoch | | `distinct_id` | The random install ID | | `$insert_id` | A random UUID per event, to drop duplicates | | `$os` | The operating system | | `arch` | The CPU architecture | | `version` | The CLI version | | `uptime` | Seconds since the CLI started | | `invoker` | `agent` when a known agent-harness environment variable is set, else `ci` when `CI` is set to a true value, else `human` | | Topic | Behavior | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Never collected | Query text, store paths, and parameter values. The event types have no fields for them, so adding one would be a compile error, not a policy change. | | Install ID | A random UUID, generated once and kept in `state.json` in the config directory. No hardware or operating-system identifier is read. | | Files | `state.json` (the install ID and the notice flag), `config.json` (the setting `relate telemetry` writes) and the spool, one `telemetry-spool-.jsonl` file per run that recorded events, all mode `0600` on Unix, in `$XDG_CONFIG_HOME/relate/` when that is set to an absolute path, else `~/.config/relate/`; on Windows, `%APPDATA%\relate`, else `%USERPROFILE%\.config\relate` | | Delivery | A run sends nothing while it works. At exit it appends its events to its own spool file, a local write with no network wait. The next run with usage metrics on sends the spooled files in the background, as `POST https://api.mixpanel.com/track` with a 2-second HTTP timeout, and deletes each file once delivered; a file that fails stays for a later run. The spool is bounded: past its limits, events and files are dropped. | | Failure | Every [telemetry](https://relatedb.ai/docs/reference/glossary/#telemetry) error is ignored: nothing is printed, and exit codes do not change. | | Recipient | A Mixpanel project shared with another command-line tool; its operator is to be named here at launch. The `RELATE-CLI_` prefix keeps relate's events apart. The CLI does not set Mixpanel's `ip` parameter, so Mixpanel's own handling of the request's IP address applies. | ## Turning usage metrics off Usage metrics are on unless a layer turns them off. The first layer that matches decides: | Order | Layer | Off | On | | ----- | -------------------------------------------------------------------------- | ---------------------- | -------------------- | | 1 | `DO_NOT_TRACK` | `1` or `true` | — | | 2 | `RELATE_TELEMETRY` | `0`, `false`, or `off` | `1`, `true`, or `on` | | 3 | `"telemetry"` in `config.json`, written by `relate telemetry off` and `on` | `false` | `true` | | 4 | Default | — | On | `relate telemetry status` prints the effective state and the layer that decided it: `default`, `config file`, `RELATE_TELEMETRY`, or `DO_NOT_TRACK`. `relate telemetry off` and `on` write the setting and print the file they wrote; `off` also deletes the spool, so events recorded before it are never sent. The commands exit 0 on success, 1 when no config directory resolves or the write fails, and 2 for a missing action, an unknown action, or an extra argument. The commands on this page run with `DO_NOT_TRACK=1` set, so `status` names that layer. `off` writes the config file, and `DO_NOT_TRACK` still decides: ```bash verify relate telemetry status relate telemetry off relate telemetry status ``` The home directory is shown as ``: ```text disabled (DO_NOT_TRACK) telemetry disabled (/.config/relate/config.json) disabled (DO_NOT_TRACK) ``` The environment variables that control usage metrics, including the ones for development and testing: | Variable | Effect | Default | Used by | | --- | --- | --- | --- | | `DO_NOT_TRACK` | `1`/`true` disables anonymous usage metrics; beats every other layer. | — | usage metrics | | `RELATE_TELEMETRY` | `0`/`false`/`off` disables, `1`/`true`/`on` enables anonymous usage metrics. | — | usage metrics | | `RELATE_MIXPANEL_ENDPOINT` | Overrides the Mixpanel /track URL (development and testing); https:// for any host, http:// only for a loopback host; a rejected value turns usage metrics off for the run, with one stderr warning. | `https://api.mixpanel.com/track` | usage metrics | | `RELATE_MIXPANEL_TOKEN` | Overrides the compiled-in Mixpanel project token (development and testing). | — | usage metrics | | `XDG_CONFIG_HOME` | When set, non-empty and absolute, the config directory is `$XDG_CONFIG_HOME/relate/`. | — | usage metrics, `relate extension`, `relate skill` | | `HOME` | The fallback config directory `~/.config/relate/`, and the base of the agent directories `relate skill install` writes to. | — | usage metrics, `relate extension`, `relate skill` | | `CI` | A value other than empty, `0` or `false` reports the usage-metrics invoker as `ci`. | — | usage metrics | `RELATE_MIXPANEL_ENDPOINT` accepts an `https://` URL, or an `http://` URL on a loopback host; any other value turns usage metrics off for that run, with one warning on stderr. Unset, the endpoint is `https://api.mixpanel.com/track`. ## What never phones home | Surface | Why | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The embedded engine, as used by the Python, Node.js, Java, Go, Swift, and Rust clients | Usage metrics live in the CLI binary only | | The C library (`relate-ffi`) | Same | | The WASM build (`@relate/relate-wasm`, and the engine on these pages) | Same | | Statements served by `relate serve` over HTTP, MCP, or Bolt | The server process sends one `RELATE-CLI_COMMAND` event when it exits, unless usage metrics are off; no event is sent per connection or statement | | `agent` and `minimal` CLI builds | Built without the usage metrics code: no events, no notice, no telemetry config or state files. The `agent` build still reaches the network when `pull`, `push`, `--fetch-params`, `--load `, or `extension install` is run; `minimal` has none of these | ## What the relatedb.ai site loads | Page | What the browser fetches | | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Docs, cookbook, and playground pages | Files from `relatedb.ai` only: the pages, self-hosted fonts, the search index, the engine from `/wasm/` (on the first Run of a cell, never with the page), and the graph view (when a graph result comes into view) | | The home page | The same, plus the console's graph view: the first time the console draws a graph, it loads the Neo4j Visualization Library (NVL) 2.0.0 from `esm.sh`, a third-party CDN, with NVL's telemetry turned off | | The [Query the relate docs](https://relatedb.ai/cookbook/query-the-relate-docs/#ask-your-own-question) recipe, after its "Download the model" button is pressed | The cookbook page's files, plus the embedding model bge-small-en-v1.5 at a pinned revision from `huggingface.co`: its half-precision weights (66.7 MB) and its tokenizer (0.7 MB). Hugging Face redirects the weights to its content delivery network, a host under `hf.co`. The requests carry no cookies and no referrer, so Hugging Face sees the reader's IP address and the browser's user agent, as with any download. Each file is checked against its pinned SHA-256 before it is used. The ONNX runtime that runs the model (14.2 MB) comes from `relatedb.ai`. The question typed into the recipe is embedded in the tab and never sent anywhere. Nothing is fetched before the press | NVL, the graph view, includes a telemetry module. The cookbook and docs pages replace it with an empty module at build time (`astro.config.mjs` aliases `@segment/analytics-next`), so none of its code ships. The playground and the home page run NVL with `disableTelemetry: true`. Today the site's own code sets no cookies and runs no analytics script, and it downloads a model only on that recipe's button press. It writes the model to no browser storage; the browser's own HTTP cache may keep the files, as it keeps any download. It stores two values in the browser's `localStorage`: the light or dark theme (`theme`) and the docs tab choice (`docs-tab`), so a tab picked on one page stays picked on the next. ## Hosting and logs | Item | Status | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Host | Decided: Cloudflare Pages serves `relatedb.ai`. It is not deployed yet; until then a preview of the site is served by GitHub Pages. | | Docs page analytics | Decided, not deployed: Cloudflare Web Analytics on the docs pages, with no cookies and no script beyond Cloudflare's own | | Agent-path hits | Decided, not deployed: one log line per request for a `.md` twin, a data file a twin links, `llms.txt`, a page asked for with `Accept: text/markdown` or `?section=`, or the skill, with the path, the status and the user agent; no query string | | What Cloudflare logs, and for how long | Not published yet; to be published on this page at launch, when the Cloudflare account exists | ## See also - [Security](https://relatedb.ai/docs/reference/security/): release signing, verification and the served surfaces' defaults - [Run relate in a sandbox](https://relatedb.ai/docs/guides/agents/run-in-a-sandbox/): running relate for an agent with usage metrics off - [CLI flags](https://relatedb.ai/docs/reference/cli/flags/): the flags and environment variables the CLI reads - [Project](https://relatedb.ai/docs/reference/project/): license, versioning and how releases are cut ## Terms used on this page - **store**: A relate database: a directory, a single `.rl` file, or `:memory:`, opened with `--database`. - **parameter**: A named value a statement refers to as `$name` and the caller binds separately, such as with `--param name=value` on the CLI. - **surface**: Any front door to the relate engine: the CLI, a language client, the C ABI, the WebAssembly build, or a server that `relate serve` hosts. - **MCP**: The Model Context Protocol, which agent hosts use to call tools; `relate serve --mcp` exposes a store as `read_cypher`, `get_schema` and `write_cypher`. - **telemetry**: The anonymous usage metrics the `relate` CLI sends: on by default, off with `DO_NOT_TRACK=1`, `RELATE_TELEMETRY=0` or `relate telemetry off`.