Telemetry

peek records operational telemetry by default, so failures can be traced from the CLI through the helper and the backend. It never records what anyone said, showed, asked or answered. Any one of the opt-outs below turns it off, and an explicit opt-out always wins.

Turn it off#

The helper and environment opt-outs#

The helper (peekd) keeps working for a home after a command returns: it delivers answers, plays speech and uploads drawings. It does not share the CLI's environment, so it decides per home from that home's config.json and from what the CLI last told it with config.sync:

• peek config telemetry off (or set, unset) pushes the home's effective setting. When the file allows telemetry but the CLI's environment opts out, the CLI sends telemetry: false and marks it as an environment opt-out.
• Every command that talks to the helper for its home under an environment opt-out ends by forwarding it the same way. This includes send, status, register, ask, history and login.
• While the opt-out is forwarded, the helper records no events about that home and sends X-Peek-Telemetry: off on every backend call it makes for it.
• The opt-out stays until a command of that home runs without it and hands the helper its telemetry, or until peek config … syncs without it. An opt-out in config.json is never lifted this way.
• --no-telemetry covers only its own process and is not forwarded.

The IAM SDK inside peek's backend has its own process-wide switch, PEEK_IAM_SDK_TELEMETRY, which follows PEEK_TELEMETRY unless an operator sets it. It records no content either.

Where it goes#

peek uses Space Station, the TOS event store, with four tables in org tos:

Table keys exist only on the backend. They are never in the CLI, the helper, the app, the website bundle or a release artifact. Everything else sends events to the backend's gateway (POST /api/web/telemetry, below), which forwards them.

• The CLI hands its event to the helper and returns immediately. With no helper (Linux, Windows, no GUI session) it posts directly with a 300 ms timeout and drops the event on failure. Telemetry never slows a command down.
• The helper keeps at most 1,000 unsent events in its database (oldest dropped first) and sends batches of up to 40 every 10 seconds.
• Peek.app sends its events to the helper; it has no network access of its own.
• The website uses @teamofsilicons/space-station-web through the same-origin /api/web/telemetry route.

The gateway#

POST /api/web/telemetry takes the body @teamofsilicons/space-station-web sends, {"table","events":[…]}, and answers 204:

• No Idempotency-Key is needed (browsers never send one). Space Station deduplicates events by their id, so a retried batch is harmless.
• Tables: only peekclidaemon, peekfrontendanalytics and peekfrontendevents. Any other table gets 403 telemetry_table_unavailable; peekbackend is written by the backend alone.
• Origin: a request that carries an Origin header must come from an origin in the backend's PEEK_WEB_ORIGINS (in production, https://peek.teamofsilicons.com, which reaches it through the same-origin /api rewrite); anything else gets 403 origin_not_allowed. The CLI and the helper send no Origin.
• Size and rate: 1–40 events and at most 64 KiB per request (invalid_input, payload_too_large), and 6,000 events per minute in total (429 rate_limited with Retry-After).
• Silent drops, still 204: when the table has no key configured on the backend, when the request carries X-Peek-Telemetry: off, when it comes from a testing environment (X-Testing-Environment-Key), and when the backend's PEEK_TELEMETRY is off. Nothing is forwarded in those cases, and the sender cannot tell, by design.

What is recorded#

Every event is self-contained:

{"schema_version":1,"app":"peek","service":"peek-backend|peek-cli|peek-daemon|peek-mac|peek-web",
 "source":"backend|cli|daemon|mac|web","version":"0.1.0","environment":"production|testing|development",
 "instance_id":"<uuidv7 per process>","trace_id":"<uuidv7 created by the CLI and carried in X-Peek-Trace-Id>",
 "step":"send.validate","event":"send.displayed","progress":1,"outcome":"ok|error|skipped|timeout",
 "duration_ms":412,"error_code":null,"isi":"deliberate",
 "actor":{"kind":"silicon","hash":"<first 16 hex of sha256('tos:si:dj')>"},
 "client":{"os":"macos","os_version":"27.0","arch":"aarch64","locale":"en_IN"},
 "context":{ /* allowlisted keys only */ }}

• Actors are hashed. actor.hash is the first 16 hex characters of sha256("<org>:<actor>"). Raw ids such as si:dj are never recorded.
• context accepts only these keys: slot, mode, appearance, speak_chars, show_elements, show_kinds, ask_type, options_count, drawing_bytes, drawing_sha256, answer_latency_ms, gesture, input, shortcut, ting_status, attempt, http_route (a route template, never a concrete URL), method, status, update_from, update_to, command, tts_model, tts_ttfb_ms, stt_ms, stt_language, matched, dg_request_id, key_source.

Events by source:

What is never recorded#

• the text of any --speak, show element, caption, question, option, answer, message or transcript;
• audio, image bytes, image paths, drawing source;
• SLTs, access or refresh tokens, app secrets, Deepgram keys or tokens;
• raw Silicon or Carbon ids, and search queries typed on the website (only the number of results).

Counts and lengths (for example speak_chars, options_count) are recorded because they explain latency and failures without revealing content.

Testing contexts#

Events from a testing environment are tagged environment:"testing" and are never written to the production tables; the gateway drops them or keeps them local, bounded at 1,000. Tests of peek itself inject a fake event sink and never reach Space Station.

Verify (operators)#

With a Space Station session for org tos:

spacestation --org tos query "SELECT record.source::String s, record.event::String e, count() n FROM peekclidaemon GROUP BY s,e ORDER BY n DESC"
spacestation --org tos query "SELECT record.source::String s, record.event::String e, count() n FROM peekbackend GROUP BY s,e ORDER BY n DESC"
spacestation --org tos query "SELECT record.source::String s, record.event::String e, count() n FROM peekfrontendanalytics GROUP BY s,e ORDER BY n DESC"
spacestation --org tos query "SELECT record.source::String s, record.event::String e, count() n FROM peekfrontendevents GROUP BY s,e ORDER BY n DESC"

To confirm an opt-out, count the CLI's completion events, run a few commands with PEEK_TELEMETRY=off (for example PEEK_TELEMETRY=off peek iam --json), wait a minute, and count again. The number must not change:

spacestation --org tos query "SELECT count() n FROM peekclidaemon WHERE record.event::String = 'command.finished'"

Next#

• Privacy: what data leaves the Mac, apart from telemetry.