Privacy and telemetry

Telemetry is first-party, opt-in, and disabled by default. The control is available in Settings → General as Send Anonymous Usage Data and takes effect immediately; no restart is required.

Stackarr shows the exact payload before you opt in and lets you refresh that preview at any time.

The reported release channel is derived from the running build: alpha, beta, preview, or stable. It is not inferred from whether the installation is local or hosted. A local container running the alpha image therefore reports alpha. STACKARR_TELEMETRY_CHANNEL is empty by default and should only be set for an intentional custom test channel.

What it may include

a random, pseudonymous installation ID
Stackarr version and release channel
controller runtime operating system family and CPU architecture (the container runtime when Stackarr runs in Docker)
fresh, restore, or migration setup mode
database mode
enabled service names and management modes
backup schedule and retention shape
counts of configured and disabled services
coarse issue codes and bucketed counts for failed or unexpectedly blocked Stackarr tasks in the last 24 hours

What it never includes

hostnames, domains, IP addresses, or public routes
usernames, email addresses, API keys, tokens, or passwords
media titles, requests, torrent names, indexers, or watch history
absolute host paths
logs, database dumps, or backup archives

Agent behavior

The dashboard and an agent can preview the exact payload before telemetry is enabled. An agent must receive explicit approval before enabling it. Enabling or sending telemetry is never part of normal setup defaults, and Stackarr sends at most one heartbeat every 24 hours.

Each opted-in installation requests its own scoped, expiring collector token. The collector signing key stays on the Stackarr landing-page server and is never included in the public Docker image. Registration and ingestion enforce small request limits, strict schemas, event deduplication, and token-to-install binding. Production deployments should also rate-limit /api/telemetry/register and /api/telemetry/events at the edge.

If you prefer no product telemetry, leave it disabled. Stackarr's local dashboard, MCP server, and managed apps continue to work normally.

Collector deployment

The landing-page deployment needs these server-only values before collection is enabled:

STACKARR_TELEMETRY_COLLECTOR_ENABLED=true
STACKARR_TELEMETRY_INGEST_KEY=<at-least-32-random-characters>
DATABASE_URL=<postgres-connection-url>
DIRECT_URL=<direct-postgres-connection-url-for-migrations>
UPSTASH_REDIS_REST_URL=<upstash-redis-rest-url>
UPSTASH_REDIS_REST_TOKEN=<upstash-redis-rest-token>

Use Neon's pooled connection for DATABASE_URL and its direct connection for DIRECT_URL. Apply the @stackarr/db production migration before enabling the collector.

The collector defaults to a 16 KiB maximum event payload. NEXT_PUBLIC_STACKARR_VERSION, telemetry registration, and the payload limit have typed application defaults; override them at deployment only when intentionally testing a different release or limit. The app version and release channel come from immutable build metadata so upgrades automatically report the new values.

The ingest key signs each installation's expiring collector token, authorizes administrative ingestion, and HMAC-hashes rate-limit identifiers before they reach Upstash. Generate it with openssl rand -hex 32. Rotating it invalidates existing installation tokens; clients recover by registering again after the next rejected heartbeat. Keep it out of client settings, public environment variables, build arguments, source control, and logs.

Upstash enforces distributed sliding-window limits of 10 registration requests per source per hour and 60 ingestion requests per source per minute. Source addresses are one-way HMAC-hashed and are not written to the telemetry database. An additional Vercel firewall limit can still be used as defense in depth.

Local collector services

The docs app includes an isolated PostgreSQL 18 database, Redis 8.2, and an Upstash-compatible Redis HTTP proxy for local development. All ports bind to loopback and use disposable development credentials:

pnpm --dir apps/docs services:up
pnpm --dir apps/docs db:migrate:local
pnpm --dir apps/docs dev

Stop the services without deleting their named volumes with pnpm --dir apps/docs services:down. Hosted deployments should continue to use managed Postgres and Upstash credentials rather than the local development values.