Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
docs(telemetry): document what Switch Console collects and why it is anonymous (#490)
Louis Amaudruz0b6dea9dc895
diff --git a/README.md b/README.mdindex 8266f853c..764ba8539 100644--- a/README.md+++ b/README.md@@ -279,6 +279,46 @@ dashboard covers the rest.one up for you, on this machine or on a host you own, without you writing anyCompose or Helm configuration.+## Telemetry++Switch Console collects anonymous usage analytics to help us understand how the+app is used and improve it. Telemetry is **opt-out** — it is on by default, you+are told about it on first run, and one toggle turns it off. Switch Core (the+server) sends no telemetry at all.++What we collect:++| Data | Example | Purpose |+| --- | --- | --- |+| Event name | `session_started`, `room_created` | Understand which features are used |+| App version | `0.9.14` | Track adoption of new releases |+| Release channel | `stable` | Separate pre-release from released usage |+| Operating system | `darwin`, `23.6.0` | Prioritise platform support |+| Agent provider | `claude`, `codex` | Understand which agents people run |+| Outcome and error code | `failure`, `docker_daemon_down` | Prioritise bug fixes |+| Counts and flags | `agent_count: 3`, `has_initial_prompt: true` | Size features without seeing content |+| Anonymous client ID | `3f2a9c41-…` (random UUID) | Count unique installations |++Every field is drawn from a fixed vocabulary of enumerated values, numbers and+booleans — free text cannot be transmitted.++**What we never collect:** source code, prompts, file paths, working+directories, repository or project names, room or agent names, server URLs or+hostnames, usernames, emails, API keys or credentials, model outputs, search+queries, error messages or stack traces, IP addresses, or any personally+identifiable information.++Events are sent to a relay we operate (`telemetry.flintai.dev`), which forwards+them to our analytics providers; no vendor credentials ship in the app.++**Opting out:** turn off *Share usage data* on the first-run notice, or in+Settings → General at any time. Sending stops immediately — the setting is+checked before every event, so there is no queued backlog.++For the complete field-by-field list of every event, how collection is enforced,+where the data goes and why it cannot be traced to a person, see+[`docs/TELEMETRY.md`](docs/TELEMETRY.md).+## ContributingSwitch is being built in the open, with the people who use it. Nobody knows yetdiff --git a/console/apps/switch-console-desktop/src/main/core/settings/schema.ts b/console/apps/switch-console-desktop/src/main/core/settings/schema.tsindex 43c45b234..ed39ef3bb 100644--- a/console/apps/switch-console-desktop/src/main/core/settings/schema.ts+++ b/console/apps/switch-console-desktop/src/main/core/settings/schema.ts@@ -107,11 +107,13 @@ export const browserSettingsSchema = z* Whether the user lets the app send anonymous usage data, and when they were* asked.*- * `askedAt` is null until the user has answered the first-run prompt, and is- * what distinguishes "hasn't been asked yet" from "was asked and left it on".- * Nothing may be sent while it is null, however `enabled` reads — see+ * `enabled` defaults to on, and is the whole of the answer: see* `isTelemetryAllowed` in `@main/core/telemetry/consent`, which is the only* supported way to read this setting before emitting.+ *+ * `askedAt` is null until the user has acknowledged the first-run notice, and+ * decides only whether that notice still needs showing. It does not gate+ * sending.*/export const telemetrySettingsSchema = z.object({enabled: z.boolean(),diff --git a/console/apps/switch-console-desktop/src/main/core/settings/settings-registry.ts b/console/apps/switch-console-desktop/src/main/core/settings/settings-registry.tsindex 4dac2b8cf..e1755f1d2 100644--- a/console/apps/switch-console-desktop/src/main/core/settings/settings-registry.ts+++ b/console/apps/switch-console-desktop/src/main/core/settings/settings-registry.ts@@ -66,7 +66,7 @@ export const SETTINGS_DEFAULTS = {pr: 'flat' as const,},telemetry: {- enabled: false,+ enabled: true,askedAt: null,},} satisfies SettingsDefaultsMap;diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/consent.test.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/consent.test.tsindex da22e7192..a9e335554 100644--- a/console/apps/switch-console-desktop/src/main/core/telemetry/consent.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/consent.test.ts@@ -19,9 +19,9 @@ describe('isTelemetryAllowed', () => {await expect(isTelemetryAllowed()).resolves.toBe(true);});- it('refuses on a fresh install that has not reached the prompt yet', async () => {+ it('allows sending on a fresh install that has not reached the notice yet', async () => {vi.mocked(appSettingsService.get).mockResolvedValue({ enabled: true, askedAt: null });- await expect(isTelemetryAllowed()).resolves.toBe(false);+ await expect(isTelemetryAllowed()).resolves.toBe(true);});it('refuses once the user has turned it off', async () => {@@ -29,7 +29,7 @@ describe('isTelemetryAllowed', () => {await expect(isTelemetryAllowed()).resolves.toBe(false);});- it('refuses when the toggle is off and the prompt was never answered', async () => {+ it('refuses when the toggle is off and the notice was never answered', async () => {vi.mocked(appSettingsService.get).mockResolvedValue({ enabled: false, askedAt: null });await expect(isTelemetryAllowed()).resolves.toBe(false);});diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/consent.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/consent.tsindex ae590c793..bca34d3dd 100644--- a/console/apps/switch-console-desktop/src/main/core/telemetry/consent.ts+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/consent.ts@@ -4,22 +4,19 @@ import { appSettingsService } from '@main/core/settings/settings-service';* Whether anonymous usage data may leave this machine right now.** Nothing may be sent without calling this first and getting `true` back. It is- * the only supported way to read the consent setting at an emission point: read- * `telemetry.enabled` directly and you miss the "hasn't been asked yet" case,- * which is not the same as "said yes".+ * the only supported way to read the consent setting at an emission point, and+ * it is read before every send rather than cached, so turning the toggle off+ * stops the next event rather than the next launch.*- * It fails closed on purpose. Consent requires both that the user has seen the- * first-run prompt (`askedAt`) and that the toggle is on, so a fresh install- * that has not reached the prompt sends nothing, and a settings read that- * throws sends nothing either.+ * The toggle defaults to on, and `askedAt` deliberately plays no part here: an+ * opt-out default means sharing does not wait for the first-run notice to be+ * acknowledged. `askedAt` records only whether that notice still needs showing.*- * The toggle defaults to off: what is sent carries a random per-install id, and- * that makes the data pseudonymous rather than anonymous, which an opt-out- * default would not cover. What may be sent is constrained beyond that — see- * the payload rule in `console/AGENTS.md` and the closed event catalogue in- * `./events`.+ * It still fails closed on a settings read that throws. What may be sent is+ * constrained regardless of consent — see the payload rule in+ * `console/AGENTS.md` and the closed event catalogue in `./events`.*/export async function isTelemetryAllowed(): Promise<boolean> {const telemetry = await appSettingsService.get('telemetry');- return telemetry.askedAt !== null && telemetry.enabled;+ return telemetry.enabled;}diff --git a/console/apps/switch-console-desktop/src/renderer/features/settings/components/TelemetrySettingsCard.tsx b/console/apps/switch-console-desktop/src/renderer/features/settings/components/TelemetrySettingsCard.tsxindex 8607ee62c..583175486 100644--- a/console/apps/switch-console-desktop/src/renderer/features/settings/components/TelemetrySettingsCard.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/settings/components/TelemetrySettingsCard.tsx@@ -1,17 +1,14 @@import React, { useCallback } from 'react';import { useAppSettingsKey } from '@renderer/features/settings/use-app-settings-key';import {- TELEMETRY_NEVER_SHARED,- TELEMETRY_SHARED,+ TELEMETRY_DETAILS_LABEL,+ TELEMETRY_DETAILS_URL,TELEMETRY_SUMMARY,} from '@renderer/features/telemetry/telemetry-copy';+import { openExternalUrl } from '@renderer/lib/open-external';import { Switch } from '@renderer/lib/ui/switch';import { SettingRow } from './SettingRow';-function joinAsSentence(items: string[]): string {- return items.map((item, index) => (index === 0 ? item : item.toLowerCase())).join('; ');-}-const TelemetrySettingsCard: React.FC = () => {const {value: telemetry,@@ -20,12 +17,12 @@ const TelemetrySettingsCard: React.FC = () => {isSaving: saving,} = useAppSettingsKey('telemetry');- const enabled = telemetry?.enabled ?? false;+ const enabled = telemetry?.enabled ?? true;const toggle = useCallback((next: boolean) => {- // Answering here counts as being asked, so a user who reaches Settings- // before the prompt appears is not asked again for a choice they made.+ // Answering here counts as being told, so a user who reaches Settings+ // before the notice appears is not shown it again afterwards.update({ enabled: next, askedAt: telemetry?.askedAt ?? Date.now() });},[telemetry?.askedAt, update]@@ -37,14 +34,15 @@ const TelemetrySettingsCard: React.FC = () => {description={<><p>{TELEMETRY_SUMMARY}</p>- <p className="mt-1">- <span className="text-foreground-muted">Shared:</span>{' '}- {joinAsSentence(TELEMETRY_SHARED)}.- </p>- <p>- <span className="text-foreground-muted">Never shared:</span>{' '}- {joinAsSentence(TELEMETRY_NEVER_SHARED)}.- </p>+ <button+ type="button"+ className="mt-1 cursor-pointer text-foreground-muted underline-offset-2 transition-colors hover:text-foreground hover:underline"+ onClick={() => {+ void openExternalUrl(TELEMETRY_DETAILS_URL, 'Could not open the telemetry document');+ }}+ >+ {TELEMETRY_DETAILS_LABEL}+ </button></>}control={<Switch checked={enabled} disabled={loading || saving} onCheckedChange={toggle} />}diff --git a/console/apps/switch-console-desktop/src/renderer/features/telemetry/TelemetryConsentDialog.tsx b/console/apps/switch-console-desktop/src/renderer/features/telemetry/TelemetryConsentDialog.tsxindex 2c2a040cb..40542454b 100644--- a/console/apps/switch-console-desktop/src/renderer/features/telemetry/TelemetryConsentDialog.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/telemetry/TelemetryConsentDialog.tsx@@ -1,62 +1,34 @@-import { CheckIcon, XIcon } from 'lucide-react';+import { ExternalLink } from 'lucide-react';import React, { useCallback, useRef, useState } from 'react';import { useAppSettingsKey } from '@renderer/features/settings/use-app-settings-key';+import { openExternalUrl } from '@renderer/lib/open-external';import { Button } from '@renderer/lib/ui/button';import { Dialog, DialogContent, DialogContentArea, DialogFooter } from '@renderer/lib/ui/dialog';-import { SectionLabel } from '@renderer/lib/ui/label';import { Shortcut } from '@renderer/lib/ui/shortcut';import { Switch } from '@renderer/lib/ui/switch';import {- TELEMETRY_NEVER_SHARED,- TELEMETRY_REVERSIBLE,- TELEMETRY_SHARED,+ TELEMETRY_DETAILS_LABEL,+ TELEMETRY_DETAILS_URL,TELEMETRY_SUMMARY,} from './telemetry-copy';-function DisclosureList({- title,- items,- tone,-}: {- title: string;- items: string[];- tone: 'shared' | 'never';-}) {- const Icon = tone === 'shared' ? CheckIcon : XIcon;- return (- <div className="flex flex-col gap-1.5">- <SectionLabel className="text-foreground-tertiary-passive">{title}</SectionLabel>- <ul className="flex flex-col gap-1.5">- {items.map((item) => (- <li key={item} className="flex items-start gap-2 text-sm text-foreground-muted">- <Icon- aria-hidden- className={- tone === 'shared'- ? 'mt-0.5 size-3.5 shrink-0 text-foreground-success'- : 'mt-0.5 size-3.5 shrink-0 text-foreground-tertiary-passive'- }- />- <span>{item}</span>- </li>- ))}- </ul>- </div>- );-}-/**- * The first-run consent prompt.+ * The first-run telemetry notice.+ *+ * Rendered only when the user has never acknowledged it, and not dismissible:+ * acknowledgement is recorded by `askedAt`, so closing it without answering+ * would leave the app showing it again on every launch. The toggle starts on,+ * matching the default — sharing is opt-out — so the notice's job is to tell+ * the user it is happening and put the off switch in front of them before they+ * go any further.*- * Rendered only when the user has never answered it, and not dismissible: the- * answer is recorded by `askedAt`, so closing it without choosing would leave- * the app asking again on every launch. The toggle starts off, matching the- * default: what is sent carries a random per-install id, so sharing has to be- * something the user turns on rather than something they failed to turn off.+ * It says the data is anonymous and links to the full account rather than+ * listing fields: the itemised version runs to every event and every field, and+ * a dialog that tries to hold it gets skimmed instead of read.*/export function TelemetryConsentDialog({ onAnswered }: { onAnswered: () => void }) {const { value, updateAsync } = useAppSettingsKey('telemetry');- const [enabled, setEnabled] = useState(value?.enabled ?? false);+ const [enabled, setEnabled] = useState(value?.enabled ?? true);const [saving, setSaving] = useState(false);const popupRef = useRef<HTMLDivElement>(null);@@ -80,12 +52,12 @@ export function TelemetryConsentDialog({ onAnswered }: { onAnswered: () => voidreturn (// Controlled `open` with no `onOpenChange`: Escape and outside clicks are- // requests the parent ignores, so the prompt cannot be dismissed unanswered.+ // requests the parent ignores, so the notice cannot be dismissed unanswered.<Dialog open>{/* Focus the popup, not its first tabbable child. The default would landon the consent switch, which renders its focus ring as a highlighted- band around the toggle row — reading as a pre-selected answer to a- question the user has not answered yet. */}+ band around the toggle row — pulling the eye to the control before the+ text that explains it. */}<DialogContentref={popupRef}initialFocus={popupRef}@@ -99,13 +71,7 @@ export function TelemetryConsentDialog({ onAnswered }: { onAnswered: () => void<p className="text-sm text-foreground-muted">{TELEMETRY_SUMMARY}</p></div><DialogContentArea className="gap-4">- <DisclosureList title="What is shared" items={TELEMETRY_SHARED} tone="shared" />- <DisclosureList- title="What is never shared"- items={TELEMETRY_NEVER_SHARED}- tone="never"- />- <div className="mt-1 flex items-center justify-between gap-4 rounded-lg border border-border bg-background-1 p-3">+ <div className="flex items-center justify-between gap-4 rounded-lg border border-border bg-background-1 p-3"><label htmlFor="telemetry-consent-switch" className="text-sm text-foreground">Share usage data</label>@@ -117,7 +83,16 @@ export function TelemetryConsentDialog({ onAnswered }: { onAnswered: () => voidclassName="data-checked:bg-foreground-success [&[data-checked]:not([data-disabled]):hover]:bg-foreground-success/85"/></div>- <p className="text-xs text-foreground-tertiary-passive">{TELEMETRY_REVERSIBLE}</p>+ <button+ type="button"+ className="inline-flex w-fit cursor-pointer items-center gap-1.5 text-xs text-foreground-tertiary-passive underline-offset-2 transition-colors hover:text-foreground hover:underline"+ onClick={() => {+ void openExternalUrl(TELEMETRY_DETAILS_URL, 'Could not open the telemetry document');+ }}+ >+ {TELEMETRY_DETAILS_LABEL}+ <ExternalLink aria-hidden className="size-3" />+ </button></DialogContentArea><DialogFooter><Button disabled={saving} onClick={confirm}>diff --git a/console/apps/switch-console-desktop/src/renderer/features/telemetry/telemetry-copy.ts b/console/apps/switch-console-desktop/src/renderer/features/telemetry/telemetry-copy.tsindex b0367de1c..e6f314d5c 100644--- a/console/apps/switch-console-desktop/src/renderer/features/telemetry/telemetry-copy.ts+++ b/console/apps/switch-console-desktop/src/renderer/features/telemetry/telemetry-copy.ts@@ -1,39 +1,21 @@/**- * The disclosure shown to the user, in one place so the first-run prompt and+ * The disclosure shown to the user, in one place so the first-run notice and* the Settings row cannot drift into promising different things.*- * These lists are a promise, and what is sent is held to them by the payload- * rule in `console/AGENTS.md` and by the closed event catalogue in- * `src/main/core/telemetry/events.ts`. Widening them is a consent decision, not- * a copy edit.+ * This is a promise, and what is sent is held to it by the payload rule in+ * `console/AGENTS.md` and by the closed event catalogue in+ * `src/main/core/telemetry/events.ts`. Widening what is sent is a consent+ * decision, not a copy edit.+ *+ * The detail lives in `docs/TELEMETRY.md`, behind the link, rather than in the+ * dialog: anyone who wants the specifics wants all of them — every event, every+ * field — which no dialog can hold, and a wall of bullet points in front of the+ * toggle gets skimmed rather than read.*/export const TELEMETRY_SUMMARY =- 'Switch Console can share usage data to show which features get used and where the app runs into trouble.';--export const TELEMETRY_SHARED = [- 'Which features are used, and how often',- 'Which coding agents you use, and whether they run here or on a remote host',- 'Whether sessions end normally or fail',- 'App version and operating system',- 'A random id for this install, so one copy of the app can be told from another',-];+ 'Switch Console shares anonymous usage data to show which features get used and where the app runs into trouble.';-// The location line says what this app does — it sends no address and no-// location — rather than what the services at the far end can work out.-//-// Today they can work out nothing: events go to our own relay, which calls the-// analytics services itself, so they see its address and never the user's. That-// is a property of the relay's configuration, in another repository, and its-// own documentation describes the change that would undo it (forwarding the-// original client IP so geography becomes usable again). A promise phrased-// about their end would quietly become false the day that lands, without a line-// changing here. Phrased about ours, it stays true and stays ours to keep.-export const TELEMETRY_NEVER_SHARED = [- 'Your name, email address, or sign-in',- 'Your machine or its user account',- 'Your IP address or location — the app sends neither',- 'Your prompts, code, files, or file paths',- 'Agent, room, project, or server names',-];+export const TELEMETRY_DETAILS_LABEL = 'Read what is collected';-export const TELEMETRY_REVERSIBLE = 'You can change this at any time in Settings, under General.';+export const TELEMETRY_DETAILS_URL =+ 'https://github.com/sandbox-quantum/switch/blob/main/docs/TELEMETRY.md';diff --git a/docs/TELEMETRY.md b/docs/TELEMETRY.mdnew file mode 100644index 000000000..d8167d533--- /dev/null+++ b/docs/TELEMETRY.md@@ -0,0 +1,334 @@+# Switch Console telemetry — what we collect, where it goes, and why it cannot be traced to a person++**Audience:** InfoSec.+**Scope:** the Switch Console desktop app. Switch server-side logging is out of+scope and needs its own pass.+**Claim:** the data we transmit is anonymous. No field identifies a person, and+no combination of the fields we transmit can be resolved back to one.++Sections 1–6 describe the Console as it is today, verified against the source.+Section 7 describes the relay, which lives in a separate repository.++---++## 1. What Switch is, in two lines++Switch runs AI coding agents (Claude Code, Codex, …) and connects them to chat+channels like Slack and Mattermost so people and agents work in shared rooms.+**Switch Console** is the desktop app used to drive it: create agents, start+sessions, connect to a server, set up rooms and bridges.++Telemetry here is product-usage analytics from that desktop app — *how the app is+used*, never *what is done with it*.++---++## 2. A real event, in full++This is the complete wire payload for one event — nothing is omitted or+abbreviated:++```json+{+ "resource": {+ "service.name": "switch-console",+ "service.version": "0.9.14",+ "flint.client_id": "3f2a9c41-8d7e-4b16-9a55-c0e1d2f47b83",+ "os.type": "darwin",+ "os.version": "23.6.0"+ },+ "event.name": "session_started",+ "timeUnixNano": "1789572278158000000",+ "severityText": "INFO",+ "attributes": {+ "build": "stable",+ "agent_type": "claude",+ "location": "local",+ "outcome": "success",+ "failure_reason": "none",+ "entry_point": "command_palette",+ "start_source": "user",+ "has_initial_prompt": true,+ "connected_to_room": false+ }+}+```++Read it as: *an installation identified only by a random UUID, on macOS, started+a Claude session locally from the command palette; it had some initial prompt+text, and was not connected to a room.* Nothing in it says who, where, on what+machine, in what repository, or what the prompt said.++---++## 3. Every field we collect, with example values++### 3.1 Attached to every event++| Field | What it is | Example values |+|---|---|---|+| `service.name` | constant | `switch-console` |+| `service.version` | app version | `0.9.14`, `1.0.2` |+| `build` | release channel | `dev`, `canary`, `stable` |+| `os.type` | OS family | `darwin`, `windows`, `linux`, `other` |+| `os.version` | OS release string | `23.6.0`, `10.0.22631`, `6.1.0-53-cloud-amd64` |+| `flint.client_id` | random install UUID | `3f2a9c41-8d7e-4b16-9a55-c0e1d2f47b83` |+| `event.name` | the event | `session_started` |+| timestamp | event time | `1789572278158000000` |++That is the entire ambient set. No hostname, no username, no account, no machine+id, no IP field, no Switch identity.++### 3.2 Values shared across events++| Field | Complete set of possible values |+|---|---|+| `outcome` | `success`, `failure` (on `session_ended`: `normal`, `failed`) |+| `agent_type` | the AI provider, from a fixed registry: `claude`, `codex`, `gemini`, `cursor`, `copilot`, `opencode`, `grok`, `devin`, `qwen`, `droid`, `amp`, `goose`, `cline`, `continue`, `mistral`, `kiro`, `junie`, … and `unknown`. **Never an agent's name.** |+| `location` | `local`, `remote`, `unknown`. **Never a path, directory or project name.** |+| `server_kind` | `local`, `remote_managed`, `external`. **Never a server name or URL.** |+| `bridge_platform` | `slack`, `mattermost`, `discord`, `teams`, `telegram`, `other`, `unknown`. **Never a workspace or channel name.** |+| `entry_point` | `command_palette`, `sidebar`, `server_page`, `onboarding`, `agent_page`, `session_list`, `room_row`, `unknown` |+| `target` | `local`, `remote`, `unknown` |++### 3.3 Every event and its fields++**App lifecycle**++| Event | Fields, with example values |+|---|---|+| `app_launched` | *(no fields)* |+| `renderer_crashed` | *(no fields)* |+| `update_checked` | `trigger`: `user` / `startup` / `scheduled` · `result`: `available` / `up_to_date` / `failed` |+| `update_downloaded` | `outcome`: `success` / `failure` |+| `update_install_started` | `outcome`: `success` / `failure` |+| `telemetry_consent_changed` | `source`: `first_run` / `settings` |+| `setting_changed` | `setting_key`, one of exactly 15: `theme`, `notifications`, `terminal`, `defaultAgent`, `sessions`, `location`, `localLocation`, `openIn`, `interface`, `browser`, `browserPreview`, `changesViewMode`, `remote`, `onboarding`, `telemetry`. **The new value is never sent** — we learn that someone changed their theme, not to what. |+| `search_performed` | `status`: `ok` / `recents` / `query-too-short` / `failed` · `result_count`: `0`, `3`, `17`. **The query is never sent.** |++**Navigation and onboarding**++| Event | Fields, with example values |+|---|---|+| `view_opened` | `view_id`, one of exactly 10: `home`, `location`, `session`, `room`, `settings`, `server`, `serverAgents`, `serverRooms`, `remoteHosts`, `remoteHost` |+| `command_executed` | `command_id`, one of 28 known commands: `app.settings`, `app.newSession`, `app.addServer`, `app.toggleTheme`, `session.newTerminal`, `session.gitPush`, … · `invoked_by`: `palette` / `shortcut` |+| `deeplink_opened` | `resolved`: `true` / `false` · `cold_start`: `true` / `false`. **The URL is never sent.** |+| `onboarding_step_started` | `step_id`, one of exactly 4: `addServer`, `agentProviders`, `onboardAgents`, `createRoom` |+| `onboarding_checklist_dismissed` | *(no fields)* |+| `onboarding_completed` | *(no fields)* |+| `add_server_step` | `step`: `choose` / `local` / `remoteHost` / `external` / `signIn` / `linkAccounts` · `choice`: `none` / `local` / `remoteHost` / `external` |++**Agents and sessions**++| Event | Fields, with example values |+|---|---|+| `agent_created` | `agent_type`: `codex` · `location`: `remote` · `outcome`: `failure` · `failure_reason`: `none` / `unauthenticated` / `name_conflict` / `credentials_conflict` / `invalid_name` / `not_configured` / `agent_not_on_server` / `error` · `entry_point`: `sidebar` |+| `agent_removed` | `agent_type` · `location` · `delete_in_switch`: `true` · `trigger`: `user` / `server_teardown` · `outcome` · `failure_reason`: `none` / `not_linked_to_switch` / `gateway_unauthorized` / `gateway_http` / `gateway_network` / `error` |+| `agent_reset` | `agent_type` · `outcome` · `failure_reason`: `none` / `agent_not_found` / `not_remote` / `connect` / `error` |+| `agent_cli_action` | `agent_type` · `target`: `local` / `remote` · `install_method`: `homebrew` / `npm` / `winget` / `powershell` / `apt` / `curl` / `pip` / `cargo` / `installer-macos` / `installer-windows` / `installer-linux` / `other` / `unspecified` · `action`: `install` / `update` / `uninstall` · `outcome` · `failure_reason`: `none` / `unknown_dependency` / `no_install_command` / `no_update_strategy` / `no_uninstall_strategy` / `no_uninstall_command` / `permission_denied` / `command_failed` / `pty_open_failed` / `not_detected_after_install` / `not_detected_after_update` / `still_present` / `error` |+| `session_started` | `agent_type`: `claude` · `location`: `local` · `outcome`: `success` · `failure_reason`: `none` / `agent_not_found` / `already_exists` / `spawn_failed` · `entry_point`: `command_palette` · `start_source`: `user` / `auto` / `adopted` / `unknown` · `has_initial_prompt`: `true` (**a boolean — never the prompt**) · `connected_to_room`: `false` |+| `session_ended` | `agent_type` · `location` · `outcome`: `normal` / `failed` |+| `session_attached` | `agent_type` · `outcome` |+| `session_provision_retried` | `agent_type` · `location` · `trigger`: `auto` / `retry_button` · `outcome` |++Note the shape of `failure_reason` everywhere: a short enumerated code such as+`permission_denied` or `docker_daemon_down`. It is **never** an exception message,+a stack trace, or a command's stderr — those are mapped to `error` if they don't+match a known code.++**Connector**++| Event | Fields, with example values |+|---|---|+| `connector_installed` | `agent_type`: `claude` · `target`: `local` · `outcome`: `success` |+| `connector_updated` | `agent_type` · `target`: `remote` · `outcome` · `was_reinstall`: `false` |+| `connector_uninstalled` | `agent_type` · `target`: `local` · `outcome` |++**Servers and sign-in**++| Event | Fields, with example values |+|---|---|+| `server_added` | `server_kind`: `remote_managed` · `outcome`: `success` |+| `server_removed` | `server_kind`: `external` |+| `server_sign_in` | `auth_method`: `password` / `oidc` · `server_kind` · `outcome` · `failure_reason`: `none` / `invalid_credentials` / `cancelled` / `failed` / `unreachable` |+| `server_sign_out` | `server_kind`: `local` |+| `managed_server_action` | `action`: `start` / `stop` / `reset` · `target`: `local` / `remote` · `outcome` · `failure_reason`: `none` / `docker_not_installed` / `docker_daemon_down` / `version_downgrade` / `matrix_migration_failed` / `error` · `docker_available`: `available` / `unavailable` / `unknown` |++No server name, URL, hostname or username appears in any of these. A failed+sign-in records `invalid_credentials` — not the username tried, not the server.++**Rooms and bridges**++| Event | Fields, with example values |+|---|---|+| `bridge_connected` | `bridge_platform`: `slack` · `outcome`: `failure` · `failure_reason`: `none` / `unauthenticated` / `forbidden` / `invalid` / `error` |+| `bridge_disconnected` | `bridge_platform`: `mattermost` · `outcome` |+| `bridge_identity_claimed` | `bridge_platform` · `outcome` |+| `room_created` | `server_kind`: `local` · `bridge_platform`: `slack` · `agent_count`: `3` · `has_instructions`: `true` · `outcome` · `failure_reason`: `none` / `unauthenticated` / `bridge_unavailable` / `invalid` / `unreachable` / `error` |+| `room_deleted` | `server_kind` · `outcome` |+| `room_agents_added` | `agent_count`: `2` · `direction`: `agents_to_room` / `room_to_agents` |++A room creation tells us *"someone made a Slack-bridged room with 3 agents and it+worked"*. It does not tell us the room name, the channel, the workspace, or which+agents.++**Remote hosts**++| Event | Fields, with example values |+|---|---|+| `host_setup_step` | `step_kind`: `core-dependency` / `agent-cli` / `agent-plugin` / `unknown` · `agent_type` · `action`: `install` / `update` / `skip` · `outcome` |+| `host_onboarded` | `outcome`: `success` · `picked_from_ssh_config`: `true` (**a boolean — the SSH host is never sent**) |+| `host_removed` | `outcome` |++### 3.4 What is never sent, at all++Prompts · code · file paths · working directories · repository names · project+or location names · room names or ids · agent names or ids · server names or+URLs · hostnames · SSH hosts · usernames · emails · account or tenant ids ·+Switch user ids · IP or MAC addresses in the payload · error messages · stack+traces · log content · search queries · setting values · deeplink URLs.++---++## 4. How it is collected — why free text cannot leak++Not a policy; three independent mechanisms in the code, each of which alone+would stop a leak.++1. **The catalogue is closed at the type level.** Every event property is+ declared as a boolean, a number, or one of a fixed list of literal values —+ the lists reproduced in full above. A free-text property cannot be declared.+ A compile-time assertion fails the build if an event declares a property that+ is not on the runtime allowlist.+2. **A send-time allowlist rebuilds the payload.** At transmission, only the+ properties named for that specific event are copied across; anything else+ present on the object is dropped. A value that is not a string, finite number+ or boolean causes the whole event to be discarded rather than sent. This+ closes the "someone spread an extra object in" hole.+3. **External values are narrowed before they are ever attached.** Anything+ originating outside the app — a server response, a CLI error, a UI string — is+ mapped onto a known enum first. Unrecognised input becomes `unknown`, `other`+ or `error`; the original string is never carried through. Values arriving from+ the UI process are additionally validated against schemas at that boundary,+ and a failing value is dropped and logged *without* the value.++**The design rule behind it:** where a value would reveal content, we send a+derived flag instead. `has_initial_prompt` not the prompt; `has_instructions` not+the instructions; `agent_count` not the agents; `result_count` not the query;+`setting_key` not the value; `resolved`/`cold_start` not the link;+`picked_from_ssh_config` not the host.++**Consent.** Opt-out: telemetry is on by default. A non-dismissible notice on+first run states what is shared and what never is, and carries the off switch;+the same toggle lives in Settings → General. The setting is re-read before every+single event rather than cached, so turning it off stops transmission+immediately, with no further requests and no queued backlog. Dev builds never+transmit regardless of the setting. Opting out is itself not reported — the one+thing we do not measure is someone asking not to be measured.++---++## 5. The identifier++Exactly one identifier is attached: `flint.client_id`, e.g.+`3f2a9c41-8d7e-4b16-9a55-c0e1d2f47b83` — a random UUID generated on the machine+the first time telemetry runs, stored in the app's local database.++- **Generated randomly.** Not derived from hardware, MAC address, disk serial, OS+ account, network, email, licence, or any Switch identity.+- **No Switch identity travels with it** — no user id, agent id, room id, tenant+ id, server id.+- Deleting the app's data directory produces a **new, uncorrelated** UUID; there+ is no mechanism to relink the old one.+- Downstream it is used as the analytics `device_id` — it groups one+ installation's events together, and nothing more.++**There is no join key.** To resolve a UUID to a person you would need a second+dataset holding that UUID next to an identity. No such dataset exists: the UUID+lives only on the user's own machine and in the analytics store, and is never+sent to, or recorded by, any account, licensing, billing or support system. It is+an anonymous installation counter, not an identity.++---++## 6. Where it is sent++1. **App → our relay.** One plain HTTPS POST per event (OTLP logs format; no+ batching, no retries, 10-second timeout) to `telemetry.flintai.dev`, an+ endpoint we operate. No third-party analytics SDK runs inside the app, and no+ vendor credential is shipped in the app. Released builds cannot be pointed at+ a different endpoint — the override exists only in dev builds.+2. **Relay → destinations.** The relay forwards to **Amplitude** and **Datadog**,+ holding the vendor keys server-side.+3. **Storage and analysis** happen in those two products.++Putting a relay in the middle is deliberate: the vendors never receive a+connection from a user's machine, so nothing vendor-side observes the user's+network address, and vendor keys stay off end-user devices.++---++## 7. The client IP, and the relay's obligations++An HTTPS request necessarily reveals the client's IP address to the server+terminating it. The IP is not in the payload — it is a property of the connection+— and it is the only value anywhere in this pipeline that could re-identify a+user. The relay is therefore the single control point, and it is held to the+following requirements.++**R1 — The client IP is never persisted.** Access logging at the relay does not+record the remote address; the IP exists only in memory for the duration of the+request.++**R2 — The client IP is never forwarded.** The relay originates its own+connections to Amplitude and Datadog and does not set `X-Forwarded-For` or any+equivalent header. Amplitude's IP-based geolocation enrichment is disabled, so no+country, region or city is derived from the request and attached to the event.++**R3 — The client IP never reaches the cloud audit and security tooling.**+Request-level IP data is excluded from what is streamed to CloudTrail and Orca,+so there is no secondary copy of the address in the security estate.++**R4 — Abuse protection without retaining addresses.** The endpoint is+unauthenticated by design (shipping a credential in a desktop app protects+nothing), so it needs rate limiting — but naive rate limiting works by keeping a+table of IPs, which would undo R1. The approach is a probabilistic membership+structure: a Bloom filter / counting filter keyed on a **salted hash of the+client IP, with the salt rotated on a short window**, so the relay can throttle a+flooding source without ever storing, logging or being able to recover an address,+and the structure itself is unusable as a lookup table. Rotation bounds how long+even the hash is meaningful.++**R5 — Injection is bounded, and doesn't matter much.** An unauthenticated+endpoint can be sent junk events. Because nothing downstream is used for billing+or security decisions, the worst case is polluted product analytics; R4's rate+limiting caps the volume. Payloads that don't match the expected schema, or that+carry no client id, are rejected at the relay.++R1–R5 describe the relay, which lives outside the Console codebase; the rest of+this document is verified against the Console source directly.++---++## 8. Why this cannot be traced to a person++- **No direct identifier is transmitted.** §3.4 is exhaustive, and it is enforced+ by the three mechanisms in §4 — not by convention or code review.+- **No indirect identifier is transmitted.** The values most often used to+ re-identify — file paths, project and repository names, hostnames, usernames,+ workspace and channel names, error text — are precisely the ones replaced by+ enums, counts and booleans. §3 lists every permitted value; none of them is+ user-supplied.+- **No join key exists.** The only stable value is a locally generated random+ UUID present in no other system (§5).+- **Field entropy is very low.** Every field is drawn from a short fixed+ vocabulary — 2 to 30 possible values — so any event is one of a small number of+ shapes. Fingerprinting by field combination fails because the combinations are+ not distinctive.+- **The IP is controlled at a single point** and is neither logged, forwarded,+ nor used for enrichment (§7).+- **The user is told on first run, and one toggle stops it** — with effect on the+ very next event, since consent is checked per event rather than cached.++Because the payload identifies nobody, the opt-out default changes how many+installations are counted, not what is knowable about any of them.