Telemetry

Agent Swarm sends usage telemetry to the maintainers to help them understand usage patterns and improve the product. Telemetry is on by default and you can turn it off at any time (see How to opt out). Setup does not ask you to opt in, and it has no telemetry toggle.

This page lists every field that leaves your install.

What is collected

Telemetry tracks lifecycle and operational events. It does not include task descriptions, prompts, outputs, agent names, email addresses, user names, or error messages. The only free-text values it carries are ones you set yourself, such as SWARM_ORG_NAME, and the email domain of your admin (see Identity context).

IDs below (taskId, agentId, workflowId) are random UUIDs generated by your install.

The table below is generated from the event catalog that the telemetry endpoint enforces (src/telemetry-contract). An event or property that is not listed here is rejected by the endpoint, and a build that emits one fails to compile. Events with the ui emitter are sent by the dashboard through the API, as described under Dashboard events. Of those, page.viewed, feature.used and ui.session_started are reserved and not sent by this release, and so are skill.invoked and session.steered.

Every event the ingest accepts with schema_version: 2. A v2 event that is not listed here, or that sends a property not listed for it, is rejected with a typed 400. Emitter is the envelope source.

trigger_surface

Surface that started a chain of work: agent-swarm's AgentTaskSourceSchema values plus other.

Values: slack, ui, api, mcp, github, gitlab, linear, jira, agentmail, schedule, workflow, system, other.

agent-swarm

Common properties, allowed on every event of this product:

Fields on every event

Each event is a JSON envelope with these top-level fields:

• schema_version — always 2
• product — always agent-swarm
• event — the event name from the table above
• occurred_at — timestamp
• source — the emitter (api-server or worker)
• actor_mode — always anonymous
• actor_anonymous_id — the installation ID (see Identifiers)
• context — the identity block described under Identity context

Every event also adds these to properties. They are the same facts context carries, kept under their older names while existing dashboards move over:

• swarmVersion — the Agent Swarm version
• is_cloud — boolean, whether the event came from a cloud-hosted swarm or a self-hosted install. True when MCP_BASE_URL points at a host we operate or SWARM_CLOUD is set. The hostname itself is never sent.
• is_e2b — boolean, whether the process runs inside an E2B sandbox
• has_embedding_key — boolean, whether an embedding-capable key (EMBEDDING_API_KEY or OPENAI_API_KEY) is configured, i.e. whether semantic memory search is likely enabled
• has_slack_channel / has_email_channel / has_notification_channel — booleans indicating whether an outbound notification channel (Slack, AgentMail email, or either) is configured. Presence only — never a token, channel ID, or address.
• install_method — enum: onboard_interactive, onboard_noninteractive, e2b, or manual. Which entry point produced this install.

And these to metadata:

• transport (always https) and environment (development for git checkouts, test for NODE_ENV=test, otherwise production; override with DESPLEGA_TELEMETRY_ENV)
• is_cloud — boolean, from SWARM_CLOUD
• organization_id (optional) — your SWARM_ORG_ID, when set
• organization_name (optional) — your SWARM_ORG_NAME, when set
• install_preset (optional) — the onboard wizard preset used (dev, content, research, solo, or custom), when the install went through the wizard. Allow-listed against the wizard's known preset IDs — any other value (including free text accidentally placed in INSTALL_PRESET) is omitted rather than forwarded.
• install_created_at (optional) — ISO timestamp of when this install's identity was first minted, persisted once alongside the installation ID. Only set when this process genuinely mints a new installation ID; an existing installation ID with no stored anchor emits this field as absent, not back-filled with the current time — absence means "pre-existing install, anchor unknown". Use min(occurred_at) per installation_id in ClickHouse as the real anchor for that population.

Identity context

context says which organization and which person an event belongs to, without carrying anything that identifies them directly.

Workers receive company profile settings through the resolved configuration at boot and during reload. They read telemetry_org_domain through the API. Workers do not query users for job functions. The API resolves those functions for events with user actors.

What is never sent: email addresses (only the domain of one address), user names, raw user IDs, task content, prompts or outputs.

Which surface started the work

Task and session events carry trigger_surface: the surface that started the whole chain of work (slack, ui, api, mcp, github, gitlab, linear, jira, agentmail, schedule, workflow, system, or other). It is the source of the root task. A Slack request that the lead splits into five worker tasks counts as six Slack tasks, and every task.* and session.* event of the chain reports slack. Tasks the swarm creates for itself, such as the heartbeat checklist and boot triage, are system. task_source keeps the raw source of each task on its own, for debugging delegation.

Daily organization snapshot

Once a day each install sends one org.snapshot event from the API server. It carries counts only: active and suspended users, admins, users who can log in, users with a linked Slack, GitHub, GitLab, Linear, Jira or other identity, users who requested a task in the last seven days, and registered agents. It carries no names, email addresses or IDs. The send time is stored as telemetry_last_snapshot_at, so a restart does not send a second one the same day.

Dashboard events

The dashboard never sends telemetry to Desplega itself. It posts each event to its own API (POST /api/telemetry/ui-event), and the API sends it like any server event, with the same context. The API accepts only the catalogued dashboard events, checks their properties against the catalog, and drops them when telemetry is off. The dashboard also holds them back until GET /status has loaded and reports telemetry on.

telemetry.enabled (via: banner, settings, benchmark or env) is sent by the API server once per opt-in: on the first boot of an install with telemetry on, or when someone turns telemetry back on from the dashboard banner, the Home benchmark card, or the Configuration page. Turning it on that way applies without a restart.

While telemetry is off, admins see a dashboard banner that explains what turning it on sends. It cannot report that it was shown, since telemetry is off. After "Dismiss" it never comes back.

Fleet benchmark

With telemetry on and an organization name set, Home compares this swarm with other swarms over the last 30 days. It compares tasks per week and task success rate. The API reads fleet percentiles from GET https://proxy.desplega.sh/v1/fleet/benchmarks at most once a day.

When the swarm stores a website, team size, and use case, the API sends team_size and use_case to the proxy. The proxy compares against that peer group only when it meets the same minimum of 20 installs as the whole fleet. Otherwise, it uses the whole fleet. Within the selected fleet, comparisons use the same agent-count bucket when at least 20 installs qualify, otherwise all qualifying installs.

The request carries no installation ID or organization name. The response contains aggregates over at least 20 installs with 10 or more finished tasks. With telemetry off, the API never makes the request. The API computes the comparison locally, so this swarm's own numbers never leave it for the benchmark.

GET /api/fleet-benchmark adds level and peerGroup to its existing response. Level is full when website, team size, and use case are set. Otherwise, level is basic. Full requests include team_size and use_case query parameters. The fleet cache key includes these peer filters.

peerGroup contains {teamSize, useCase, orgs} when the proxy returns a matching group. It is null when the proxy returns the whole fleet or omits peer_group. With telemetry off, local contains DB counts for the last 30 days, without a proxy request or ingest requirement. Existing comparisons still require a known proxy ingest date.

Public ranking

agent-swarm.dev/ranking ranks installs by tokens used, like OpenRouter's app rankings. It is off by default (PUBLIC_RANKING_ENABLED=false). Opting in is all it takes: no PR and no approval step. An install is listed when all of these hold:

• Telemetry is on.
• The organization name (SWARM_ORG_NAME) and company website (SWARM_ORG_WEBSITE) are set. The placeholders Swarm and Your Swarm do not count as a name.
• An admin clicked Get ranked in Settings → Configuration → Branding.
• The install sent telemetry in the last 7 days and used tokens in the period shown.

The install shows at the proxy's next hourly refresh. If two installs list the same website, the one that opted in first holds the entry. Desplega can hide a domain that abuses the ranking.

Exactly these fields leave the install for the ranking:

Token totals are public and exact. The page shows your total tokens per day, week and month, and tokens per model, the same as OpenRouter.

To leave, turn the setting off, turn telemetry off, or clear the organization name or website. Changing the website also opts out; click Get ranked again to list the new domain. The entry disappears at the proxy's next hourly refresh.

A notification card that asks for your email, and the feedback dialog, are different. Those send what you type to the feedback endpoint (https://proxy.desplega.sh/v1/feedback, overridable with the feedback_endpoint config key), and only when you submit them. They are not telemetry, so the opt-out does not block them.

The feedback card asks self-hosted admins one 0-10 question. It shows once after a completed workflow run, after 10 completed tasks on an install at least 3 days old, or in the session after the one that first saw a failed task, and then at most once a quarter. A tap on a score sends it; a follow-up question and contact details are optional. With telemetry off, the card still works, but it sends no installation ID, and sends the organization name only when you tick "Include my organization name".

Identifiers

• Installation ID. Each installation generates a random, opaque identifier (e.g. install_a1b2c3d4e5f6g7h8), stored in the swarm_config table. It is not derived from your hostname, domain, or account, and it stays the same across restarts so events from one install link together.
• Organization identity. The installation ID is random, but events are not anonymous to your organization. Every event carries an organization ID (org_id), the organization name when you set SWARM_ORG_NAME, the company website when you set SWARM_ORG_WEBSITE (org_website), and the email domain of your admin (org_domain), so they are attributable to your organization. Cloud deployments set SWARM_ORG_ID. The setup wizard's "name your swarm" step and the dashboard's organization-name prompt set SWARM_ORG_NAME. Leave SWARM_ORG_NAME unset, or opt out, if you do not want to share an organization name.
• People. Events caused by a person carry a pseudonymous user_ref, never an email address or a name. See Identity context.
• No IPs logged. The telemetry endpoint (proxy.desplega.sh) does not store client IP addresses.
• No auth required. Events are sent in anonymous actor mode with no authentication headers.

Installation ID mechanism

On first startup, the telemetry module checks swarm_config for a telemetry_installation_id key:

1. If found, it reuses the existing ID for consistent tracking across restarts.
2. If not found, it generates a new random ID (install_ + 16 hex characters) and persists it.
3. If config access fails (e.g. worker without DB access), an ephemeral ID (ephemeral_ prefix) is generated for that session only.

Workers access the installation ID via HTTP (respecting the DB boundary invariant), while the API server reads it directly from the database.

The API server also stores the organization ID as telemetry_org_id (and the admin's email domain as telemetry_org_domain) next to the installation ID. Workers read both through the same HTTP config call, so events from workers and from the server carry the same organization.

A telemetry_installed_at timestamp is minted alongside the installation ID, but only when this process genuinely mints a new installation ID — it anchors "when this install came into being" independent of server restarts. An existing installation ID with no stored anchor (an install that predates this field) leaves it unset, and the field is omitted from events rather than back-filled with the current time; use min(occurred_at) per installation_id in ClickHouse as the real anchor for that population.

How to opt out

Set the ANONYMIZED_TELEMETRY environment variable to false:

ANONYMIZED_TELEMETRY=false

For Docker workers, also add it to .env.docker:

ANONYMIZED_TELEMETRY=false

You can also set it in the dashboard under Settings → Configuration → Telemetry & observability. A value stored there takes precedence over the deployment environment.

Two things reach Desplega with telemetry off, because each is an explicit action: feedback you submit, and the "Show our logo on agent-swarm.dev" consent, which sends your organization name and website when you change it. A company website also points the dashboard logo at https://proxy.desplega.sh/v1/logo, so browsers that show the dashboard load the logo from Desplega's proxy; set your own SWARM_ORG_LOGO_URL to avoid that.

When disabled:

• No events are sent
• No installation ID is generated or stored
• The telemetry module initializes as a no-op
• The dashboard stops sending notification events. GET /status reports the effective state as telemetry.enabled, which the dashboard reads. A server that predates that field is treated as enabled.

Technical details

• Endpoint: POST https://proxy.desplega.sh/v1/events
• Timeout: 5 seconds per request
• Failure mode: Fire-and-forget — telemetry never throws exceptions or blocks operations
• Module: src/telemetry.ts (importable from both API server and workers)

Related

• Environment Variables — Full reference for ANONYMIZED_TELEMETRY and all configuration options
• Deployment Guide — How to set environment variables in production Docker deployments
• Architecture Overview — How the API server and workers fit together in the overall system