Skip to main content
Ask your AI

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:

StateMeaning
field absentYou have not made a choice yet. Default: nothing is collected, no installation UUID is written.
trueYou opted in via walkeros telemetry enable. The first opt-in generates the installation UUID; a later one reuses it. The emitter is active.
falseYou 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:

EventWhen
mcp startMCP server starts up and completes the initialize handshake
cmd invokeA CLI command or MCP tool is invoked
error throwAn 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 start whether 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/cli or @walkeros/mcp version.
  • MCP only: a client field with the name the MCP client reports in its handshake (some sessions send unknown instead), 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 enable on 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.

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)