Telemetry
walkerOS @walkeros/cli and @walkeros/mcp support anonymous usage
telemetry to help us improve the tools. Telemetry is off by default and
requires explicit opt-in. Nothing is sent from your machine until you run
walkeros telemetry enable.
This page describes the data contract, how to enable or disable it, and the legal basis.
Why opt-in
walkerOS is a privacy-aware data-collection product built in the EU. The
ePrivacy Directive (Article 5(3)) requires prior consent for any storing of
or access to information on a user's terminal equipment that is not strictly
necessary for the service the user asked for. Installing a persistent
installation UUID on your machine to help us improve the tools is not
strictly necessary to run walkeros bundle, so we ask first and we default
off. This is the same consent model we encourage on the web.
The three states
Your choice is stored in ~/.config/walkeros/config.json
($XDG_CONFIG_HOME/walkeros/config.json when that is set) under
telemetryEnabled:
| State | Meaning |
|---|---|
| field absent | You have not made a choice yet. Default: nothing is collected, no installation UUID is written. |
true | You opted in via walkeros telemetry enable. The first opt-in generates the installation UUID; a later one reuses it. The emitter is active. |
false | You opted out via walkeros telemetry disable. CLI commands and MCP servers started after that collect nothing. The installation UUID stays in the config file, and a later telemetry enable reuses it. The choice is read once: by a CLI command when it starts, by an MCP server when its client connects. So when telemetry was on, the telemetry disable command itself is still reported once, and an MCP server that is already running keeps sending an event per tool call, and error throw events, until it restarts. The CLI's Nothing will be sent from this machine. does not cover such a server: restart it after opting out. |
Commands
# Opt in
walkeros telemetry enable
# Opt out
walkeros telemetry disable
# Show current state
walkeros telemetry status
What we collect (after opt-in)
Every event is an entity action (the same event model the rest of walkerOS
uses). The emitted events:
| Event | When |
|---|---|
mcp start | MCP server starts up and completes the initialize handshake |
cmd invoke | A CLI command or MCP tool is invoked |
error throw | An unhandled error is thrown during a command or tool call, or the MCP server fails to start |
For each event we attach:
- Installation UUID: generated at opt-in, stored in
~/.config/walkeros/config.json, not linked to any account or user. - Environment: OS, OS version, Node.js version, language, timezone, and
on
mcp startwhether the process runs in CI, with the CI vendor's name. - Command or tool name: for example
bundle,push,flow_validate. - Outcome: success or error. Never the error message.
- Duration: how long the command or tool call took, in milliseconds.
- Client version: the installed
@walkeros/clior@walkeros/mcpversion. - MCP only: a
clientfield with the name the MCP client reports in its handshake (some sessions sendunknowninstead), and a random session UUID per MCP server process. - Event fields: a random event ID, the time, and a random ID and a counter per process run.
What we do NOT collect
- File paths, file names, or file contents
- Environment variable names or values
- Error messages, stack traces, or code snippets
- Project names, flow names, destination settings, or any flow config content
- Account identifiers, email addresses, or auth tokens
- IP addresses. The endpoint reads the address only in memory, to rate-limit requests, and stores none.
Source of truth
The full contract, with JSON Schemas for every event and every property, lives in the CLI source tree:
packages/cli/src/telemetry/flow.json
It declares the user properties and each event's data properties, with
one gap: MCP cmd invoke also carries data.client, which the contract
declares only for mcp start. The MCP tool name, which it lists under
data, travels in source.tool. The other fields are the standard
walkerOS event fields
listed above.
Headless environments
No command prompts for a choice. MCP servers, CI jobs, piped invocations and every other process read the stored choice. In practice:
- If you have opted in via
walkeros telemetry enableon the same machine, MCP and CI invocations emit telemetry normally. - If you have never opted in on the machine, those surfaces stay silent.
- An MCP server reads the choice once, when its client connects. After
walkeros telemetry disable, it keeps sending until you restart it.
There is no environment variable to force-enable telemetry on a machine that has not opted in. That is intentional: consent must be an explicit act.
Env var overrides
Two environment variables, set to 1 or true, force telemetry off
regardless of your stored choice:
export DO_NOT_TRACK=1
export WALKEROS_TELEMETRY_DISABLED=1
Use them to keep telemetry off even after an opt-in. Without an opt-in, telemetry is off already.
Debug mode
To inspect what each event carries after opt-in, set:
export WALKEROS_TELEMETRY_DEBUG=1
In debug mode the CLI and MCP print each event to stderr as JSON, after
[walkeros telemetry debug], and send nothing. The printed event lacks the
event fields the collector adds when it sends (event ID, time, run ID and
counter). While telemetry is off, debug mode prints nothing.
Where it goes
Telemetry events are sent to https://app.walkeros.io/api/telemetry, the
walkerOS app operated by elbwalker GmbH on EU infrastructure.
WALKEROS_APP_URL, or appUrl in the config file, replaces the base URL,
and /api/telemetry is appended to it. We do
not share the data with any third party and do not use it for advertising. It
exists to help us prioritize fixes and improvements to the open-source tools.