Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
63 commits
Select commit Hold shift + click to select a range
a001ece
fix: suppress all usage telemetry when opted out
anandgupta42 Nov 21, 2026
ef0d8d8
fix: close remaining telemetry opt-out gaps
anandgupta42 Nov 21, 2026
6ee41c4
test: check the shared telemetry opt-out gate
anandgupta42 Nov 21, 2026
8e5dfa1
fix: treat account lookup failures as unresolved telemetry config
anandgupta42 Nov 21, 2026
ff9b6fd
fix: retry telemetry initialization after config becomes available
anandgupta42 Nov 21, 2026
e43aaa5
fix: hold telemetry until opt-out state resolves
anandgupta42 Nov 21, 2026
827026b
test: follow the shared telemetry config resolver
anandgupta42 Nov 21, 2026
a5be807
fix: retry cached telemetry config load failures
anandgupta42 Nov 21, 2026
6c9a01f
fix: preserve released telemetry opt-out compatibility
anandgupta42 Nov 21, 2026
547a063
fix: scope telemetry backoff to stale remote results
anandgupta42 Nov 21, 2026
515f5ff
fix: back off malformed remote telemetry config retries
anandgupta42 Nov 21, 2026
0f296c5
fix: classify invalid organization telemetry config
anandgupta42 Nov 21, 2026
74a5310
fix: recheck unresolved local telemetry sources before refetching
anandgupta42 Nov 21, 2026
f7d043d
fix: type the legacy config parser result
anandgupta42 Nov 21, 2026
6af5b01
fix: keep held telemetry scoped to its project
anandgupta42 Nov 21, 2026
f8e31ac
fix: gate identity refresh on project telemetry permission
anandgupta42 Nov 21, 2026
79f5440
fix: preserve telemetry scope on overflow and cwd failure
anandgupta42 Nov 21, 2026
bfbc815
fix: bound scoped telemetry handoffs and overflow accounting
anandgupta42 Nov 21, 2026
d026eda
fix: retain timed-out telemetry batches for their scope
anandgupta42 Nov 21, 2026
3866ab0
test: observe identity lookup before transport starts
anandgupta42 Nov 21, 2026
7f119a9
test: use the scoped config fixture for telemetry recovery
anandgupta42 Nov 21, 2026
4fcf5c0
docs: clarify lifetime of retained telemetry batches
anandgupta42 Nov 21, 2026
0abc0bf
refactor: replace per-project telemetry scopes with one process gate
anandgupta42 Nov 21, 2026
5f07817
fix: let the TUI main thread adopt the worker telemetry opt-out
anandgupta42 Nov 21, 2026
9971ca7
fix: keep telemetry opt-out retries off the session path
anandgupta42 Nov 21, 2026
03a8d67
fix: read closed account databases and stop telemetry config reloads
anandgupta42 Nov 21, 2026
44a0c43
fix: let a later telemetry opt-out stop a running lifecycle
anandgupta42 Nov 21, 2026
e9bbfcd
fix: scope the telemetry retry throttle to instance-less reads
anandgupta42 Nov 21, 2026
15a3c30
fix: drop an unresolved project's held telemetry at its shutdown
anandgupta42 Nov 21, 2026
aff7683
fix: settle a pending telemetry opt-out when a command loads its project
anandgupta42 Nov 21, 2026
2ae0dd3
fix: close the remaining telemetry opt-out review gaps
anandgupta42 Nov 21, 2026
3855c10
fix: settle a pending telemetry opt-out in effectCmd commands too
anandgupta42 Nov 21, 2026
2992168
fix: keep a throwing opt-out listener from stopping telemetry
anandgupta42 Nov 21, 2026
7e84253
fix: treat a global config that failed to load as an unresolved opt-out
anandgupta42 Nov 21, 2026
9f4a61b
fix: address bot review findings on the telemetry opt-out
anandgupta42 Nov 21, 2026
9721718
fix: keep old opt-out markers and pin the mid-flush abort test
anandgupta42 Nov 21, 2026
42bed3a
fix: keep an enabled telemetry decision across reads that cannot see it
anandgupta42 Nov 21, 2026
52a0466
fix: throttle the shutdown re-init and narrow the auth mark
anandgupta42 Nov 21, 2026
921baac
test: make the outside-project read unreadable in the enabled-reuse test
anandgupta42 Nov 21, 2026
78be48c
fix: treat an in-memory account database as an unknown organization s…
anandgupta42 Nov 21, 2026
bda0166
fix: close the last telemetry opt-out review notes
anandgupta42 Nov 21, 2026
b55ee9b
fix: let a file opt-out win even when an organization is selected
anandgupta42 Nov 21, 2026
1ada8a7
fix: ask SQLite for URI parsing when reading a closed account database
anandgupta42 Nov 21, 2026
9729433
test: cover the remaining telemetry opt-out guards
anandgupta42 Nov 21, 2026
d38ebd4
fix: let a readable telemetry opt-out stand when another config sourc…
anandgupta42 Nov 21, 2026
cfff9f8
fix: count raw well-known auth entries again so the probe fails closed
anandgupta42 Nov 21, 2026
1186d36
fix: mark a config loaded while the auth store was unreadable
anandgupta42 Nov 21, 2026
afb0a5c
fix: record an unreadable auth store where Auth.all reads it
anandgupta42 Nov 21, 2026
516aa1c
refactor: stat the auth file instead of re-reading it after a failed …
anandgupta42 Nov 21, 2026
1e73f2a
fix: let the config load decide auth readability inside a project
anandgupta42 Nov 21, 2026
7028f9c
docs: describe how an organization config interacts with a file opt-out
anandgupta42 Nov 21, 2026
b0856f8
fix: honour another project's file opt-out in a workspace handoff
anandgupta42 Nov 21, 2026
6a579e1
fix: compare the handoff project canonically with the Instance
anandgupta42 Nov 21, 2026
8f80f8b
test: make the handoff test fail if the canonical comparison is reverted
anandgupta42 Nov 21, 2026
404087b
fix: address cubic and local-review notes on auth-store and docs
anandgupta42 Nov 21, 2026
194c8c5
test: pin whitespace-only auth stores and share the auth-store fixture
anandgupta42 Nov 21, 2026
20ef32c
fix: close the exit race in an adopted enabled answer and other revie…
anandgupta42 Nov 21, 2026
61aeea5
fix: stamp held events on a copy and guard the invalid-global-config …
anandgupta42 Nov 21, 2026
784dca8
fix: read non-object inline auth as Auth does, and document per-proje…
anandgupta42 Nov 21, 2026
0c392b7
fix: address bot and local-review P3s on the opt-out gate
anandgupta42 Nov 21, 2026
4c261ce
fix: treat any non-object auth store as unreadable at startup
anandgupta42 Nov 21, 2026
fc0bcf1
test: pin local-over-well-known precedence; name all opt-out variable…
anandgupta42 Nov 21, 2026
37dbb3a
docs: a legacy TOML hold lifts on config reload; note the loose well-…
anandgupta42 Nov 21, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 3 additions & 4 deletions docs/docs/reference/security-faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -166,9 +166,9 @@ export ALTIMATE_TELEMETRY_DISABLED=true

- **Signed-in users:** Events carry your Altimate user ID and tenant, so they are not anonymous. No email address, hashed or not, is sent. See [User identification](telemetry.md) for how the ID is looked up and cached.
- **Users who are not signed in:** A random UUID (`crypto.randomUUID()`) is generated on first run and stored at `~/.altimate/machine-id`. This is NOT tied to your hardware, OS, or identity — it's purely random.
- **Both identifiers** are only sent when telemetry is enabled. Disable with `ALTIMATE_TELEMETRY_DISABLED=true` or the `telemetry.disabled` config option.
- **Both identifiers** are only sent when telemetry is enabled. Disable with `ALTIMATE_TELEMETRY_DISABLED`, `ALTIMATE_CLI_DISABLE_TELEMETRY` or `OPENCODE_DISABLE_TELEMETRY` set to `1` or `true`, or the `telemetry.disabled` config option.
- **No fingerprinting:** We do not use browser fingerprinting, hardware IDs, MAC addresses, or IP-based tracking.
- **CLI auth flow:** When you sign in via `altimate auth login`, the anonymous machine ID is included in the authorization URL and associated with your account in product analytics for funnel analysis. This is suppressed when you disable telemetry — via `ALTIMATE_TELEMETRY_DISABLED=true` or the `telemetry.disabled` config option — and the machine ID is omitted from the URL entirely.
- **CLI auth flow:** When you sign in via `altimate auth login`, the anonymous machine ID is included in the authorization URL and associated with your account in product analytics for funnel analysis. The machine ID is omitted from the URL entirely when you disable telemetry (any of those three environment variables, or the `telemetry.disabled` config option), and also while that setting cannot be resolved.

### What happens on first launch?

Expand All @@ -183,8 +183,7 @@ No code, queries, file paths, or personal information is included. This event he

The install scripts (`altimate.sh/install`, `install.ps1`), the npm postinstall, and the VS Code extension's installer send nothing themselves and contact no telemetry endpoint. They only record the version and installer name to a local file that the CLI reads on its next run, so the opt-out above decides whether anything is ever transmitted.

!!! warning "One caveat on the config-file opt-out"
The environment variables (`ALTIMATE_TELEMETRY_DISABLED`, `OPENCODE_DISABLE_TELEMETRY`) are always honoured. The `telemetry.disabled` **config key** is read from the config files at telemetry startup. If a config file cannot be read or parsed at that point, startup proceeds with telemetry enabled, so this event may still be transmitted. Use an environment variable if you need a guarantee.
The CLI sends zero usage telemetry requests when `ALTIMATE_TELEMETRY_DISABLED`, `ALTIMATE_CLI_DISABLE_TELEMETRY`, or `OPENCODE_DISABLE_TELEMETRY` is set to `1` or `true` (case-insensitive), or when `telemetry.disabled` is `true` in config. This also covers first launch and shutdown. If the opt-out setting is unresolved, the CLI holds events in memory and makes no telemetry requests. It discards them if telemetry is disabled, if the process exits before the setting resolves, or when a session ends for a project whose own config could not be read. A legacy global `config` (TOML) file that fails to import keeps the setting unresolved until it is fixed or removed and the config is reloaded (a long-running process reloads it on restart). One exception: a process that serves several projects (`serve`, an IDE) reads a project's own `telemetry.disabled` when that project's session starts, so a few of its events from before then can be sent if another, opted-in project already turned telemetry on. The environment variables are honoured process-wide from the start. A `telemetry.disabled` in your own files is normally read at CLI startup, before any project loads, so it holds for that process. A process that reads only a project's merged config (such as the TUI's worker thread) follows that config, where an organization config set by your admin is merged over your files.

## What happens when I authenticate via a well-known URL?

Expand Down
17 changes: 6 additions & 11 deletions docs/docs/reference/telemetry.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,6 @@ We collect the following categories of events:
| `gateway_auth_completed` / `gateway_auth_failed` | Gateway sign-in outcome. `reason` is `timeout`, `denied`, or `error` — never the underlying message, which can contain the instance name. An unrecognised callback state does not reject the pending attempt, so a CSRF mismatch surfaces as `timeout`. |
| `instance_connected` | Credentials received and saved. `time_to_connect_ms` runs from the start of the authorize call, so it includes the browser launch. The event names no instance itself; like every event sent after sign-in, it carries the account's `user_id` and `tenant` once they are resolved (see [User Identification](#new-user-identification)). |
| `onboarding_completed` | A model is ready and chat is live. |
| `telemetry_opted_out` | The last event from a machine that turns telemetry off, sent once (see [Disabling Telemetry](#disabling-telemetry)). Contains `opt_out_source` (`env` for an environment variable, `config` for `telemetry.disabled`), the machine ID, the CLI version and the client. It carries no account (`user_id`, `tenant`), project, session or launch ID. |
| `scan_gate_shown` / `scan_gate_choice` | The "scan your environment?" gate appeared, and what the user did — `scan`, `skip`, or `dismissed` (esc / click-away). |
| `environment_scan_completed` | A `project_scan` finished during onboarding — `has_dbt`, `has_warehouse`, `is_repo`, `connections_found`, and a bounded list of short `degraded` detection keys. No paths, hostnames, or connection details. Emitted only inside an onboarding session, and only once per session, so scans from `/discover` or a model-initiated call are excluded. |
| `sample_setup_completed` | The sample dbt project was materialised. `success`, `models`, `tables`, and `reused` — the tool is deliberately re-callable, so this is per invocation. The target path is never sent. |
Expand All @@ -88,7 +87,7 @@ We collect the following categories of events:
| `plugin_session_start` | A Claude Code session started with the Altimate Code plugin, sent by the plugin through `altimate-code tool report-event`. Its payload is the plugin version, this altimate-code's version (`altimate_code_version`), the OS as Claude Code names it (`host_os`: `macos`, `linux`, `windows`, `wsl` or `unknown`; named apart from the `os` other events carry as `process.platform`) and the plugin's anonymous install id (a random UUID the plugin makes on first run and keeps in its Claude Code plugin store). It carries no session id, machine id, project id or account (`user_id`, `tenant`), nor the per-launch `launch_id`, so it cannot be joined to the CLI's other events: beside its own fields, only `cli_version`, `client` and `source`, keyed to the install id (`ai.user.id`). It is sent in a request of its own, never in one batch with the CLI's other events. |
| `plugin_feature_used` | One of the plugin's panels or commands was opened (`lineage`, `dbt_show`, `profile_ctes`, `scan_cost`, `comments`, `sql_graph`, `health`, `runs`, `to_model`), or one of its gates held or allowed a command (`cost_gate`, `health_push_gate`). Its payload is the feature, the outcome (`opened`; `failed` when the panel could not open; `held` or `allowed` for a gate), the plugin version and the install id: no model, column, file or project names, SQL or session text. Like `plugin_session_start`, it carries no session id, machine id, project id, launch id or account: beside its own fields, only `cli_version`, `client` and `source`, keyed to the install id. |

Each event (except the plugin's `plugin_session_start` and `plugin_feature_used`, described above) includes a timestamp, session ID, a per-launch correlation ID (`launch_id` — a random value regenerated every process start, not persisted and not derived from your machine or identity; it exists only to group events from the same run), CLI version, and a machine ID (a random UUID stored in `~/.altimate/machine-id`, generated once and not derived from your hardware or identity). The final `telemetry_opted_out`, in the same table, is the other exception: it carries the timestamp, CLI version and machine ID, but no session ID, `launch_id` or account. When the machine is signed in to Altimate, each event also carries `user_id` and `tenant`, described under [User Identification](#new-user-identification).
Each event (except the plugin's `plugin_session_start` and `plugin_feature_used`, described above) includes a timestamp, session ID, a per-launch correlation ID (`launch_id` — a random value regenerated every process start, not persisted and not derived from your machine or identity; it exists only to group events from the same run), CLI version, and a machine ID when available (a random UUID stored in `~/.altimate/machine-id`, generated once and not derived from your hardware or identity). Signed-in events carry `user_id` and `tenant` once account identity resolves. See [User Identification](#new-user-identification).

### Workspace events

Expand Down Expand Up @@ -183,13 +182,9 @@ You can also set the environment variable:
export ALTIMATE_TELEMETRY_DISABLED=true
```

When telemetry is disabled, a machine with an existing machine ID sends one final `telemetry_opted_out` event, then nothing: no further events and no requests to the telemetry endpoint until telemetry is turned back on. The event carries only the machine ID, the opt-out source, the CLI version and the client — see the event table above. With it, an opted-out machine can be counted instead of looking like a client that stopped working.
`ALTIMATE_CLI_DISABLE_TELEMETRY` and its older spelling `OPENCODE_DISABLE_TELEMETRY` are also supported. Each variable accepts `1` or `true` (case-insensitive).

- The event is sent only if `~/.altimate/machine-id` already exists. A machine that never ran with telemetry on sends nothing.
- Once the telemetry endpoint accepts the event, Altimate Code writes the marker file `~/.altimate/telemetry-opted-out`, and later launches send nothing. If the endpoint cannot be reached, no marker is written and a later launch tries again.
- While the event is being sent, a short-lived `~/.altimate/telemetry-opted-out.sending` file stops a second process from sending it too.
- Turning telemetry back on removes the marker, so a later opt-out is recorded again.
- No account lookup is made while telemetry is disabled.
When any of these variables or `telemetry.disabled: true` disables telemetry, the CLI makes zero usage telemetry requests. That includes startup, sessions, error reporting, shutdown, and the account lookup used to identify telemetry events. This applies even if the CLI has sent telemetry before. Until the CLI can read the setting (for example at startup, before the project config or a configured remote source that could set the flag has loaded), it sends nothing; see [Privacy](#privacy). Once a process reads the setting as disabled, that process sends nothing more, even for another project it serves. One exception: a process that serves several projects (`serve`, an IDE) reads a project's own `telemetry.disabled` when that project's session starts, so a few of its events from before then can be sent if another, opted-in project already turned telemetry on. The environment variables are honoured process-wide from the start. A `telemetry.disabled` in your own files is normally read at CLI startup, before any project loads, so it holds for that process. A process that reads only a project's merged config (such as the TUI's worker thread) follows that config, where an organization config set by your admin is merged over your files.

### Test runs are excluded

Expand All @@ -207,7 +202,7 @@ Two escape hatches exist for reporting from a test run deliberately:
is always honoured, which is how the project's own telemetry tests work.
- Set `ALTIMATE_TELEMETRY_FORCE=true` to use the default endpoint anyway.

`ALTIMATE_TELEMETRY_DISABLED` and the config opt-out take precedence over both.
The environment opt-outs and the config opt-out take precedence over these settings.

## Privacy

Expand All @@ -232,11 +227,11 @@ What identifies the sender of an event depends on whether the machine is signed

The Claude Code plugin's `plugin_session_start` and `plugin_feature_used` are the exception: signed in or not, they carry neither the machine ID nor your account, and their `ai.user.id` is the plugin's own random install id.

These identifiers are sent only while telemetry is enabled. The final `telemetry_opted_out` event carries the machine ID and nothing that identifies your account, and no `/users/me` lookup is made while telemetry is disabled. Disable telemetry entirely with `ALTIMATE_TELEMETRY_DISABLED=true` or the config option above.
These identifiers are sent only while telemetry is enabled. While the opt-out setting is unresolved, Altimate Code holds events in a bounded in-memory buffer and skips telemetry requests, including the `/users/me` lookup. If a later initialization resolves telemetry as enabled, it sends the queued events. It discards them if it resolves as disabled, if the process exits while the setting is still unresolved, or when a session ends for a project whose own config could not be read. A legacy global `config` (TOML) file that fails to import keeps the setting unresolved until it is fixed or removed and the config is reloaded (a long-running process reloads it on restart).

### CLI Authentication Flow

When you sign in using the CLI browser auth flow (`altimate auth login`), the anonymous machine ID (a random UUID persisted at `~/.altimate/machine-id` — a device/installation identifier, reused across sessions) is included in the authorization URL and associated with your account in product analytics. This is used solely to correlate CLI install events with authenticated accounts in aggregate funnel analytics — it is not used for advertising or cross-site tracking. Your telemetry opt-out suppresses this: when you disable telemetry — via `ALTIMATE_TELEMETRY_DISABLED=true` **or** the `telemetry.disabled` config option — the machine ID is omitted from the authorization URL entirely. The machine ID is associated with your account in PostHog for this funnel analysis, separate from the Azure Application Insights pipeline used for other CLI telemetry events.
When you sign in using the CLI browser auth flow (`altimate auth login`), the anonymous machine ID (a random UUID persisted at `~/.altimate/machine-id` — a device/installation identifier, reused across sessions) is included in the authorization URL and associated with your account in product analytics. This is used solely to correlate CLI install events with authenticated accounts in aggregate funnel analytics — it is not used for advertising or cross-site tracking. Your telemetry opt-out suppresses this: when you disable telemetry — via any of the environment flags above or the `telemetry.disabled` config option — the machine ID is omitted from the authorization URL entirely. The URL also omits it while telemetry permission is unresolved. The machine ID is associated with your account in PostHog for this funnel analysis, separate from the Azure Application Insights pipeline used for other CLI telemetry events.

### Data Retention

Expand Down
13 changes: 10 additions & 3 deletions packages/opencode/src/altimate/debug/collect.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ import { Global } from "@opencode-ai/core/global"
import { InstallationVersion } from "@opencode-ai/core/installation/version"
import { resolveInstall } from "@/installation"
import { Telemetry } from "@/altimate/telemetry"
import { TelemetryConfig } from "@/altimate/telemetry/config-state"
import { AltimateApi } from "@/altimate/api/client"
import * as Registry from "@/altimate/native/connections/registry"
import { resolveConfig } from "@/altimate/native/connections/credential-store"
Expand Down Expand Up @@ -89,15 +90,21 @@ function envFlags(): string[] {
})
}

function optOutReason(state: "pending" | "enabled" | "disabled") {
if (state === "pending") return "config not readable yet"
if (state === "disabled") return "disabled in config"
return "not running in this process (no telemetry sink, or this session's config not resolved yet)"
}

/** With `network`, telemetry has been started by the CLI; its start is awaited here so the answer is not read
* before it settles. Without, it is not started (it would send), so only the environment switches are checked. */
async function telemetryFacts(network: boolean): Promise<Facts["telemetry"]> {
if (/^(1|true)$/i.test(process.env["ALTIMATE_TELEMETRY_DISABLED"] ?? "")) return { enabled: false, reason: "ALTIMATE_TELEMETRY_DISABLED is set" }
if (/^(1|true)$/i.test(process.env["OPENCODE_DISABLE_TELEMETRY"] ?? "")) return { enabled: false, reason: "OPENCODE_DISABLE_TELEMETRY is set" }
const optOut = TelemetryConfig.disablingEnvironmentVariable()
if (optOut) return { enabled: false, reason: `${optOut} is set` }
if (!network) return { enabled: false, checked: false, reason: "not started with --no-network" }
try {
await Telemetry.init()
return Telemetry.isEnabled() ? { enabled: true } : { enabled: false, reason: "disabled in config" }
return Telemetry.isEnabled() ? { enabled: true } : { enabled: false, reason: optOutReason(Telemetry.optOutState()) }
} catch {
return { enabled: false, checked: false, reason: "could not be determined" }
}
Expand Down
Loading
Loading