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

# Telemetry

> The anonymous daily counts Orchestra sends, every other request it makes, and how to turn each one off

Orchestra Local keeps your sessions and memories on your computer. To know how
many people use it, and which parts of it, the CLI and the desktop app send a
small, anonymous count each day. This page lists everything in it.

The count is not all a Local install sends: it also checks
`get.orchestrahq.ai` for new versions and downloads them, and it reaches your
own model provider and your own git remote. [Every request Orchestra
makes](#every-request-orchestra-makes) lists them all, with the switch for each.

## What is sent

The first time each of these happens on a given day, Orchestra sends one
request to `api.orchestrahq.ai`:

* an agent session is saved (by the capture hook or the background capture)
* an agent session is dispatched or resumed
* the terminal app opens
* the desktop app opens
* your agent calls one of Orchestra's MCP tools

"A given day" is your computer's date, and one more request goes out if the
date in UTC changes while it is still the same day for you, so each UTC day
is counted too. That is at most six requests a day, and usually one or two.
Each one contains only these fields:

| Field | Example | What it is |
| - | - | - |
| `installId` | `3f0c…` | A random id made on your computer the first time a count is sent, kept in `~/.orchestra/install-id`. It is not made from anything about you or your machine. |
| `day` | `2026-11-06` | Your computer's date. |
| `utcDay`, `at` | `2026-11-07`, `2026-11-07T01:12:09Z` | The same moment in UTC: the date, and the time. A count that could not be sent at once keeps its own time. |
| `source` | `capture` | Which of the five above happened: `capture`, `dispatch`, `tui`, `desktop` or `mcp`. |
| `client` | `cli` | `cli` or `desktop`. |
| `version` | `0.1.22` | The version you run. |
| `os`, `arch` | `darwin`, `arm64` | Your operating system and processor family. |
| `agent` | `claude-code` | For a saved session or an MCP tool call: which agent. Always one of `claude-code`, `codex`, `gemini-cli`, `cursor`, `opencode`, `vscode`, `windsurf`, `zed`, `cline`, `claude-desktop` or `other`; a name your MCP client reports that is not on this list is sent as `other`. |
| `activeDay` | `true` | Only on the first count of each UTC day. |
| `firstRun`, `installedAt` | `true`, `2026-11-05T18:02:11Z` | Only until the first count is received: this is a new install, made at that time. |
| `mode` | `local` | `local` when your sessions are kept by Orchestra Local on your computer, `hosted` when you are signed in to a hosted workspace. |
| `orgId` | `org_3Lx…` | Only when you are signed in to a team on Orchestra Local: your team's workspace id, so we can count active teams. |
| `internal`, `internalReason` | `true`, `scratch-home` | Only on Orchestra's own team's machines, so our own use is left out of the count, with the name of the reason (never what was checked). See [How our own use is left out](#how-our-own-use-is-left-out). |
| `machineId` | `9c1e…` | A one-way hash of your computer's hardware id (see [Counting people, not installs](#counting-people-not-installs)), so a reinstall is not counted as a new computer. |
| `personId` | `4b7a…` | When you are signed in, which every user is: a one-way hash of your Orchestra account id, so one person on two computers counts once. |

Never sent: code, file or folder paths, repository names, prompts, session
ids or content, your name, your email, or your git identity. The API passes on
only the fields in the table: a field it does not know (from a newer version
of Orchestra, say) is dropped, and only that field's name is written to our
server log, never its value. If the API refuses a count, Orchestra keeps it on
your computer and sends it again the next day, for up to a week.

Orchestra's API removes your IP address before passing the count on to our
analytics tool (PostHog), so it cannot be used to place you on a map. It
passes on only counts from versions published at `get.orchestrahq.ai`, and
adds which channel the version came from (`release_channel`). Our server
logs keep a short, one-way tag of the install id, not the id itself.

Builds made from source never send it. Only the released CLI and the
installed desktop app do.

If a count cannot be sent (you are offline, or our API does not answer), it
is kept in `~/.orchestra/usage-outbox.json` with the time it happened and
sent the next time Orchestra sends one, for up to a week. Each install's
count for a day is recorded once however many times it is sent.

### How our own use is left out

The CLI and the desktop app decide on your computer whether it is one of
Orchestra's own. They send `internal: true` when any of these holds:

* a `user.email` in your git config ends in `orchestrahq.ai` or `orchestrahq.io`
* the repository you are working in has its `origin` under
  `github.com/Orchestra-Technologies-Inc`
* the copy of Orchestra was not built by our release process
* your home folder is a temporary folder (a test run)
* another home folder on the same computer was already found to be one of
  ours (Orchestra keeps that answer, and nothing else, in
  `/Users/Shared/.orchestra-internal` on a Mac, `/var/tmp/.orchestra-internal`
  on Linux and `%PROGRAMDATA%\Orchestra\internal` on Windows)

On a CI machine, in a test run, or in one of our release checks (any of the
variables under [Turn it off](#turn-it-off)), nothing is sent at all.

To check the first two, Orchestra reads your git config files and the current
repository's `.git/config` on your computer. It does not run `git`. Only the
answer, `true`, is sent. Your email and your remotes are never sent, logged
or stored. Once the answer is `true`, it is saved in
`~/.orchestra/telemetry.json` and stays. `orchestra telemetry external`
removes it, and the check then leaves that choice alone.

### Counting people, not installs

Both ids are 32 characters made with a keyed one-way hash (HMAC-SHA256, with
a key only Orchestra uses). The same input always gives the same id, which is
what lets us count, but the input cannot be worked out from the id, and
another product hashing the same input gets a different value, so our ids
cannot be matched with theirs.

| Id | Made from | Read from |
| - | - | - |
| `installId` | Nothing: a random id. | `~/.orchestra/install-id`. The CLI and the desktop app on one computer share it. `~/.orchestra/install.json` remembers which computer (by `machineId`) it was made on, so a home folder copied to another computer gets a new id there. |
| `machineId` | Your computer's hardware id. | macOS: `IOPlatformUUID` from `ioreg`. Linux: `/etc/machine-id`. Windows: the `MachineGuid` registry value. Never from the keychain, and never the serial number. |
| `personId` | The id of the Orchestra account you signed in with. | `~/.orchestra/local/relay-device.json` when you are on a team, else the account id saved with your sign-in in `~/.orchestra/credentials.json`. The token in it is never read or sent. |

The hardware id and your account id never leave your computer; only their
hashes do.

## The day's totals

Once a day is over, the next day's first request is followed by one more with
that day's totals, as numbers:

| Field | Example | What it is |
| - | - | - |
| `sessionsSaved` | `14` | How many agent sessions were saved that day. |
| `memoriesWritten` | `5` | How many memories Orchestra Local wrote from those sessions. |
| `teamContextDelivered` | `9` | How many sessions started with your teammates' context added. |
| `tools` | `{ "recall": 12, "remember": 3 }` | How many times your agents called each of Orchestra's MCP tools, by the tool's name. |
| `features` | `{ "steersSent": 4 }` | How many times each of these happened that day, leaving out the ones that did not: `sessionsJoined` (live sessions you joined), `steersSent` (messages you sent into a running agent session), `forks`, `gitPublishesOk` (shares to your repository's git remote that went out), `teammateSessionsOpened`, `recallsAnswered` (recalls that found something), `memoriesInjected` (memories added to an agent's context when its session started). |
| `failures` | `{ "hook": 1 }` | How many times each kind of failure happened that day, as a number only, never a message, path or stack: `daemonRestart` (Orchestra's background service had to start again after it stopped), `storeFenced` (another process held your local store), `storeDied` (your local store failed to open or crashed), `relayDisconnect` (the connection to Orchestra's relay dropped), `gitPublish` (a share to your git remote failed), `update` (an update failed), `hook` (an agent hook failed). |

It also carries the `installId`, `day`, `client`, `version`, `os`, `arch`,
`internal`, `machineId` and `personId` fields above. Never which session, memory, file or teammate: the
totals are counted on your computer in `~/.orchestra/usage-counts.log`, which
keeps a one-way tag for each session (so a session saved twice counts once)
and never its id, and the file is cleared as each day is sent. Totals older
than a week that could not be sent are dropped.

## On your phone

The Orchestra iPhone app sends the same count only if you said yes to
analytics in the app. Once a day, the first time the app opens that UTC day,
it sends: a random install id made by the app, the date and time,
`source: mobile`, `client: mobile`, the app's version, your phone's operating
system, `mode: hosted`, the one-way hash of your Orchestra account id
(`personId`, as above) and your workspace id. Deleting the app deletes its
install id.

## In a hosted workspace

When you are signed in, Orchestra's API counts the actions you take through
it, such as creating an issue, opening a session, searching, or an agent
calling one of Orchestra's MCP tools. Each count is the action's name (and the
tool's name), the app and version you used, how many times, your account, and
your workspace. Never what you typed, what was saved, or what came back. We
use these counts to see which parts of Orchestra teams use. They are part of
running the hosted service, so `orchestra telemetry off` does not change them.

Each time an agent starts in Orchestra's cloud, the API also counts that run:
which agent (such as Codex), whether it was new or resumed, whether it waited
for a free sandbox, the app you started it from, your account, and your
workspace. Never the prompt, the repository, or anything the agent did. The
minutes a cloud run uses are billed to your workspace and are not sent here.

The same goes for Orchestra Local signed in to a workspace on a paid plan.
Once a day your laptop tells the API how many sessions you captured on it and
how many minutes your agents ran, for counting the seats your workspace pays
for. We also count those numbers per person and workspace, to see how teams
use Orchestra. Never which sessions, repositories or files. Each report
carries a random id made on the laptop for this count, so that two laptops are
not counted as one; it is not made from anything about the machine.
`orchestra logout` stops it.

To count how many people use a hosted workspace each day, Orchestra's own
servers also read, once an hour, which signed-in people did something in a
workspace that day (anything they did, not what it was), and record one
"active that day" count per person and workspace with the same one-way hash
of the account id used above.

## Turn it off

Any one of these stops it:

```bash theme={null}
orchestra telemetry off
```

* Set `ORCHESTRA_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` in your environment.
* On a CI machine (where `CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, `BUILDKITE`,
  `CIRCLECI`, `JENKINS_URL`, `TF_BUILD`, `TEAMCITY_VERSION`,
  `BITBUCKET_BUILD_NUMBER` or `CODEBUILD_BUILD_ID` is set) it is always off.
* In a test run (`VITEST`, `JEST_WORKER_ID`, `NODE_ENV=test`, or any
  `ORCHESTRA_E2E` variable) and in our release checks
  (`ORCHESTRA_RELEASE_CHECK`) it is always off.

`orchestra telemetry` shows whether it is on, why, and your install id.
`orchestra telemetry on` turns it back on. While it is off, no count is sent,
nothing is counted, and no install id is made. The desktop app follows the same setting,
and its Setup screen says what is sent, with a Turn off button for the same switch.

To start over with a new id, delete `~/.orchestra/install-id` and
`~/.orchestra/install.json`.

Turning telemetry off does not stop the version check or update downloads
below. They carry no install id and nothing about you or your work, and
`ORCHESTRA_NO_UPDATE_CHECK=1` stops them.

## Every request Orchestra makes

This is every request an Orchestra Local install can make, from the CLI, its
background service and the desktop app. Nothing else leaves your computer.

| Request | Sent to | What is sent | When | Turn it off |
| - | - | - | - | - |
| Daily count | `api.orchestrahq.ai` (`/v1/usage/active`, `/v1/usage/daily`) | The fields listed above, nothing more. | The first time each of the five things above happens in a day, then the day's totals once. | `orchestra telemetry off`, `ORCHESTRA_NO_TELEMETRY=1` or `DO_NOT_TRACK=1`; always off on CI machines, in test runs and in our release checks. |
| Version check | `get.orchestrahq.ai/cli/latest.json` | A plain request for that file: no install id, no version, nothing about your work. | When an agent session starts, the terminal app opens, an agent starts Orchestra's MCP tools, or you run `orchestra status`, `doctor` or `enable`: at most once every 4 hours. A copy that does not update itself asks at most once a day, when the terminal app opens. | `ORCHESTRA_NO_UPDATE_CHECK=1`. |
| Update download | `get.orchestrahq.ai/cli/` | A request for the new version's archive and its SHA-256 checksum. The file names say the version and your platform (for example `darwin-arm64`). | Only when the version check finds a newer version, and only for a copy the install script put in a folder it can write. | `ORCHESTRA_AUTO_UPDATE=false`, `"autoUpdate": false` in `~/.orchestra/settings.json`, or `ORCHESTRA_NO_UPDATE_CHECK=1`. `orchestra update` still updates when you run it. |
| Desktop app updates | `get.orchestrahq.ai/desktop` | A request for the update feed, then the new build when there is one. | When the app opens, then every 4 hours. | `ORCHESTRA_DISABLE_UPDATES=1`. |
| Crash report | `bun.report`, run by the makers of Bun, the runtime the CLI is built on | Nothing unless you turn it on. Then, only if the CLI itself crashes: a short coded trace with the Bun version, your operating system and processor, which runtime features were in use, and code addresses. Bun's team describes it as redacted. | Never by default: the CLI turns Bun's crash reports off. With `BUN_ENABLE_CRASH_REPORTING=1`, after a crash. | Off already. `BUN_ENABLE_CRASH_REPORTING=1` turns it on. |
| Writing memories | Your own model provider: `api.anthropic.com` or `api.openai.com` with your key, or Claude Code or Codex on your subscription, which send to their own vendor | The text of the sessions being read. With a key, also one request to check the key when you add it. | Shortly after a session ends. | Remove the key, or `orchestra enable --local --subscription no`. Without a writer, memories wait and nothing is sent. |
| Sharing through git | Your repository's own git remote | The sessions and memories you share, and fetches of your teammates'. They are stored there with secrets and personal details removed, not encrypted, so anyone who can read the repository can read them. Before each share, one anonymous request (no credentials) to check that the repository is not public. | Only on the Team plan, in repositories where you said yes to sharing. | `orchestra enable --local --share no`. `orchestra team shared` lists everything shared in a repository, and `orchestra team shared remove --yes` takes it off the remote. |
| Push notice | `api.orchestrahq.ai` | After a share is pushed: the repository's remote address, the name of the git ref that was pushed and its commit id, so that teammates' computers fetch promptly. Nothing of what was shared. | After each share push, only when you are signed in. | `orchestra logout`. |
| Local database | `github.com` (the `theseus-rs/postgresql-binaries` releases) | A plain download of a public file, the database Orchestra Local runs on your computer, checked against a fixed SHA-256. Nothing about you or your computer is sent. | Once, when a store is first created on a Mac with Apple silicon. | None: without it there is no local store. |
| Issues on Orchestra Local | Your repository's own git remote, and nowhere else | The issues you and your agents write (encrypted with your team key), and fetches of your teammates'. Issues never go to Orchestra's servers: not to the API, and not through the relay. When you push new issues, the relay carries one short "fetch now" signal to your teammates' laptops that are online. It names the repository by a scrambled id and says nothing about the issues. | After an agent writes an issue, when a teammate's laptop signals that it pushed new ones, when issues are read and the last fetch is more than five minutes old, and on `orchestra issue sync`. Only on the Team plan, in repositories where you said yes to sharing. | `orchestra enable --local --share no` stops publishing; `orchestra issue leave --yes` takes back what you shared. |
| GitHub | `api.github.com`, as you, with the GitHub CLI's (`gh`) sign-in | Requests for the repositories, pull requests and commits of the GitHub repositories you work in. Nothing from your sessions. | Every few minutes, while `gh` is signed in. | `orchestra disconnect github`. |
| Linear | `api.linear.app`, with your own key | Requests for your teams' issues, and the issue updates you make. | Only after `orchestra connect linear`. | `orchestra disconnect linear`. |
| Signed in | `api.orchestrahq.ai` and Orchestra's relay | Your sign-in, this laptop's device key, and reads of your plan and team. On a paid plan, once a day, how many sessions you captured on this laptop and how many minutes your agents ran (see [In a hosted workspace](#in-a-hosted-workspace)). On the Team plan, the relay carries what the team features show your teammates, such as which sessions are live. Your sessions and memories still stay on your computer. | Only after `orchestra login`. | `orchestra logout`. |

The install script downloads from `get.orchestrahq.ai` too, and sends nothing
else. The on-device search model comes inside the CLI, so nothing is
downloaded for it. Requests to `get.orchestrahq.ai` are logged with the
address they came from for 14 days, which is how we count downloads and the
installs too old to send the daily count. So that one computer fetching the
installer on several days counts once, we keep a salted one-way hash of each
address (never the address) for at most 30 days.


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