> ## Documentation Index
> Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Telemetry: What We Collect & How to Opt Out

> What OneCLI collects, why, and how to opt out. No request bodies, credentials, or PII are ever transmitted. Fully transparent.

## Overview

OneCLI collects **anonymous install and update lifecycle events** to help us understand adoption and prioritize development. Telemetry is enabled by default and can be disabled at any time.

## What we collect

OneCLI sends exactly **two event types**, and only when the container starts:

| Event | When | Properties |
| - | - | - |
| `install_complete` | First time the container starts | `version`, `edition`, `auth_mode`, `arch` |
| `update_complete` | Container starts with a new version | `version`, `old_version`, `edition`, `auth_mode`, `arch` |

Each event includes a **random UUID** as the identifier, generated fresh every time and never stored or reused. This means we cannot track individual users across events.

### Example payload

```json theme={null}
{
  "event": "install_complete",
  "distinct_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "properties": {
    "version": "1.12.0",
    "edition": "oss",
    "auth_mode": "local",
    "arch": "aarch64"
  }
}
```

## What we do NOT collect

* No hostnames or domain names
* No usernames, emails, or personal information
* No secret values, agent names, or API endpoints
* No usage patterns, feature flags, or request counts
* No persistent identifiers (each event gets a fresh random UUID)

## How to opt out

Two ways to disable telemetry:

**1. Environment variable**

Set the widely-adopted `DO_NOT_TRACK` variable in your Docker environment or `.env` file:

```bash theme={null}
DO_NOT_TRACK=1
```

This takes the highest priority and overrides the dashboard setting.

In Docker Compose:

```yaml theme={null}
services:
  app:
    environment:
      DO_NOT_TRACK: "1"
```

**2. Dashboard toggle**

Go to **Settings → General** in the OneCLI dashboard and toggle **Anonymous Telemetry** off.

This writes a preference file to the persistent data volume (`/app/data/telemetry-preference`) that the container reads on startup.

## How it works

Telemetry runs in the container entrypoint (`docker/entrypoint.sh`), **after** database migrations and **before** the gateway and web app start:

1. Check the consent chain: `DO_NOT_TRACK` env var → preference file → default (enabled)
2. Compare the current version against a marker file (`/app/data/.onecli-version`)
3. If it's a new install or version change, send a single HTTP POST to PostHog in the background
4. The request has a 5-second timeout and runs asynchronously, so it never blocks startup

The telemetry code is fully visible in [`docker/entrypoint.sh`](https://github.com/onecli/onecli/blob/main/docker/entrypoint.sh).

## Data processor

Events are sent to [PostHog](https://posthog.com) (US region). PostHog's privacy policy is available at [posthog.com/privacy](https://posthog.com/privacy).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.