Contents
Reference

Telemetry

shadowlap can send anonymous usage counts to a collector you name. This page is the complete list of what is sent.

Nothing is sent by default, and the project collects nothing. The CLI has no default endpoint and shadowlap runs no collector. Events go out only when SHADOWLAP_TELEMETRY_URL points at one. In practice, that means a collector you host yourself to measure usage inside your own organization.

On this page

What is sent

#

One event per run, replay, test pack, ui open and pack:

FieldExampleNotes
Install id123e4567-…Random UUID stored in your config directory. In CI, a hash of the repository's numeric id, never its name
Version, OS, arch, Node version0.1.0, darwin, arm64, 22.18.0—
CI systemgithub, gitlab, other, noneFrom environment variables
Providers["anthropic"]Which provider modules received calls
SDK languages["typescript", "python"]From the user agent of what called the sidecar (an SDK, the recorded-input preload, shadowlap mcp), as one of typescript, python, mcp, other
Countscalls: 30, replayed: 28, live: 2, blocked: 1, stubbed: 0, overridden: 0—
Divergence typerequest_changed, or noneThe category only
Tokens not re-spent12000From recorded usage
Duration, exit code900 ms, 0—

What is never sent

#

Prompts, messages, tool names, tool arguments or results, file paths, hostnames, run ids, model names, repository names, or anything the agent saw.

The collector rejects any event carrying either of these:

  • A field outside its allowlist, or a value outside its closed sets, so a client bug cannot leak content.
  • A time before 2025, or more than a day ahead of its own clock, so no client can keep its events counted as recent.

Opt out

#
export SHADOWLAP_TELEMETRY=0     # or DO_NOT_TRACK=1

With a collector configured, the first run prints a one-line notice. SHADOWLAP_TELEMETRY_URL sends events to a collector of your own.

The collector

#

@shadowlap/collector is a Node service with a strict validator, a SQLite store, aggregate stats and a dashboard. The dashboard shows:

  • weekly active developers over twelve weeks;
  • replays per day, and how many were clean;
  • tokens not re-spent;
  • CI repositories;
  • why replays forked;
  • the counts by provider, SDK, OS and version.

It installs nothing but shadowlap's engine, which has no dependencies of its own. The dashboard runs no scripts. Source: packages/collector in the repository.

It ships so that a team running shadowlap can see its own numbers; whether the dashboard is public is up to whoever hosts it.

Hosting your own

#

Install the collector from npm, and start it. It needs Node 22.17 or later, not 23.

Shell
npm install -g @shadowlap/collector
shadowlap-collector

These environment variables set it up:

VariableWhat it doesDefault
PORTThe port it listens on8787
HOSTThe address it listens on0.0.0.0
COLLECTOR_DBIts SQLite file./collector.db
PUBLIC_ORIGINThe address its empty dashboard tells clients to send to—

Put it behind TLS at a hostname you control, and point the CLI at it with SHADOWLAP_TELEMETRY_URL=https://your-host/v1/events. GET /healthz is its health check.

In a container

#

Point COLLECTOR_DB at a directory the process's user can write. With a volume, create the directory and give it to that user before declaring the volume, or the collector can't create its file there:

DOCKERFILE
RUN mkdir -p /data && chown node:node /data
VOLUME /data

See also

#
  • Security: what the collector accepts, and every other check shadowlap makes.

This page on GitHub →