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

# Anonymous usage data

> Exactly what Upsolve Local sends about how it is used once you turn it on, what it never sends, and how to turn it on and off.

Upsolve Local can send a small set of **anonymous usage events**, so we can see which parts of the product get used: how many installs start, how many connect a database, how many get as far as a first chat. It is **off until you turn it on**, and any "off" wins over any "on" (see [Turning it on and off](#turning-it-on-and-off)).

Upsolve Cloud sends none of these events. This page is the complete list: an event or a property that is not here is not sent.

<Tip>
  A new install sends nothing at all, not even the one-time `installed` event, until you turn events on:

  ```bash theme={null}
  npx @upsolve-labs/analytics telemetry on
  ```

  That works before the first start too. `installed` is sent the first time events are on, once per install.
</Tip>

## What is sent

One HTTPS request per event, from the Upsolve app process on your Mac to PostHog's capture endpoint. Each request carries the event name, a timestamp, an install id and the properties below, and nothing else.

| Event | When | Properties |
| - | - | - |
| `installed` | Once per install, the first time events are on | None |
| `started` | Every time Upsolve starts | `app_version` (the release number), `os` (for example `darwin`), `arch` (`arm64` or `x64`) |
| `provider_configured` | When an AI provider is saved (the first-run screen, and Organization settings → AI provider) | `provider_type`: `anthropic`, `openai`, `openrouter` or `openai_compatible` |
| `database_connected` | When a database connection is created | `db_type`: the kind of database, such as `Postgres` or `MySQL`, from the fixed list Upsolve supports |
| `workspace_created` | When a workspace is prepared | None |
| `first_chat` | Once per install, when the first chat answer completes | None |
| `canvas_created` | When a canvas is created | None |
| `upgrade_clicked` | When an upgrade to Upsolve Cloud starts (you confirmed, and nothing blocks it) | None |
| `upgrade_completed` | When an upgrade has handed everything to Upsolve Cloud (not when it fails) | None |

The two upgrade events are a start and a finish, with no properties. They say nothing about which cloud account, project or workspace the upgrade went to, and the cloud side of an upgrade sends nothing.

Every event also carries four fixed values, which are instructions to PostHog rather than data about you:

| Property | Meaning |
| - | - |
| `$ip: null` | Record no IP address on the event |
| `$geoip_disable: true` | Do not look the connecting IP up to attach a city or a country |
| `$process_person_profile: false` | Anonymous event: PostHog builds no person profile for the install id |
| `$lib: "upsolve-local"` | Which sender this is |

### The install id

The id on every event is a random UUID generated on the first start and stored in your own database. It is not derived from your machine, your user name or anything else about you, and it is not your user, organization or project id. It exists only so that "started" and "first chat" from one install can be counted as one install.

## What is never sent

* **Your data.** No query results, rows, values or files.
* **SQL, prompts, chat messages or model answers.**
* **Schema.** No database, schema, table or column names, and no connection names.
* **Names of anything you create:** workspaces, canvases, favorites or skills.
* **Identity.** No email, user name, organization name, hostname, IP address, file path, API key or credential.
* **Free text of any kind.** Every property value is an enum, a release number, a boolean or a count. The app checks each event against a fixed allowlist before sending it: an unknown event is dropped, an unknown property is removed, and a value that is not one of the allowed ones drops the whole event.

The web app inside Upsolve Local has its own analytics switched off, and the agent is started with its own telemetry disabled, so the one process on your Mac that sends anything is the Upsolve app, and only the events above.

## IP addresses

A request necessarily reaches PostHog from your public IP address. Each event asks PostHog not to keep it (`$ip: null`) and not to geolocate it (`$geoip_disable: true`).

## Turning it on and off

Events are off until you turn them on: run `npx @upsolve-labs/analytics telemetry on`, or start Upsolve with `UPSOLVE_TELEMETRY=1`. Any one of the switches below turns every event off, and any "off" wins over any "on".

<Steps>
  <Step title="The command line">
    ```bash theme={null}
    npx @upsolve-labs/analytics telemetry off
    ```

    Stored in `~/.upsolve/config.json` (`telemetryEnabled: false`), and applies from the next start. `telemetry on` turns events on again, unless they are turned off in the app.
  </Step>

  <Step title="An environment variable">
    Start Upsolve with `UPSOLVE_TELEMETRY=0` (`false`, `off` and `no` work too) in the environment:

    ```bash theme={null}
    UPSOLVE_TELEMETRY=0 npx @upsolve-labs/analytics
    ```
  </Step>

  <Step title="DO_NOT_TRACK">
    `DO_NOT_TRACK=1`, the convention several developer tools share, has the same effect.
  </Step>

  <Step title="In the app">
    The **Share anonymous usage stats** switch on the first-run screen (below the AI provider form) is off until you turn it on. If you change it, your choice is saved when you press **Continue**; if you leave it alone, nothing is recorded, so `telemetry on` still decides. It takes effect for the very next event, without a restart, and turning it off keeps events off even after `telemetry on`. You can change it any time in **Organization settings → Usage stats**, where the switch saves as soon as you click it. If the environment has turned events off for this run (`DO_NOT_TRACK`, `UPSOLVE_TELEMETRY=0` or `telemetry off`), both screens say so: the switch is off and cannot override it until that is removed. If they were turned on from the command line (`telemetry on` or `UPSOLVE_TELEMETRY=1`), switching off in Settings still stops them.
  </Step>
</Steps>

To check what a start will do, run `npx @upsolve-labs/analytics telemetry status`. It says whether events are sent and what turned them off. While Upsolve is running it reports what the running instance was started with, because the app reads the switch only when it starts; if what a new start would do differs, it says so. After `telemetry on` or `telemetry off`, stop Upsolve and start it again for the change to apply.

The first time you run `start`, Upsolve prints a short notice saying what is collected and how to turn it off. It does not delay anything.

## When sending fails

You never see it. Each event is sent in the background with a 2-second timeout and is never retried. Offline, behind a firewall or proxy, or with PostHog down, the event is simply dropped. Sending never slows down or fails anything you do.


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