# How to Disable Telemetry Collection in Paperclip and What Data Is Collected

> Disable Paperclip telemetry collection by setting telemetry.enabled false in paperclip.yaml. Learn what data is collected and protect your privacy.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: how-to-guide
- Published: 2026-08-18

---

**Set `telemetry.enabled: false` in your [`paperclip.yaml`](https://github.com/paperclipai/paperclip/blob/main/paperclip.yaml) configuration file and restart the server to completely disable telemetry collection in Paperclip.**

Paperclip's telemetry system collects usage-related events to help the development team understand platform utilization. By default, telemetry is enabled and sends anonymized data to `https://telemetry.paperclip.ing`. This guide explains how to disable telemetry collection in Paperclip and details exactly what information is gathered when the feature remains active.

## How Telemetry Works in Paperclip

The telemetry system initializes during server startup through two critical components in the Paperclip source code:

- **[`server/src/config.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/config.ts)** — Loads the `telemetry.enabled` flag from your configuration file
- **[`server/src/telemetry.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/telemetry.ts)** — Creates the telemetry client based on this flag

In [`server/src/config.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/config.ts), the `loadConfig()` function reads the telemetry setting:

```ts
// server/src/config.ts (excerpt)
export function loadConfig(): Config {
  // ... configuration loading logic ...
  return {
    // ... other config values ...
    telemetryEnabled: fileConfig?.telemetry?.enabled ?? true,  // defaults to true
  };
}

```

When `telemetryEnabled` evaluates to `false`, the `initTelemetry()` function receives `{ enabled: false }` and instantiates a no-op telemetry client. This client silently discards all tracking calls without network transmission.

## Steps to Disable Telemetry Collection in Paperclip

Follow these steps to turn off telemetry completely:

1. **Locate your configuration file**

   Find [`paperclip.yaml`](https://github.com/paperclipai/paperclip/blob/main/paperclip.yaml) (or [`paperclip.json`](https://github.com/paperclipai/paperclip/blob/main/paperclip.json)) in your Paperclip instance directory.

2. **Add the telemetry disable flag**

   ```yaml
   # paperclip.yaml

   telemetry:
     enabled: false
   ```

3. **Restart the Paperclip server**

   The configuration change takes effect only after a full server restart. Once restarted, `initTelemetry({ enabled: false })` creates the no-op client, and no data leaves your instance.

There is **no environment variable** for this setting—configuration file modification is the only supported method to disable telemetry collection in Paperclip.

### Verifying Disabling Telemetry Collection in Paperclip

You can programmatically confirm telemetry status:

```ts
import { getTelemetryClient } from "./telemetry";

const client = getTelemetryClient();
if (client) {
  // Telemetry is enabled
  client.trackDynamic("test.event", { status: "check" });
} else {
  console.log("Telemetry is disabled – no data will be sent.");
}

```

A `null` return from `getTelemetryClient()` confirms successful disabling.

## What Data Is Collected When Telemetry Is Enabled?

When telemetry remains active, Paperclip records structured event data across eight primary categories. All events are defined in [`packages/shared/src/telemetry/generated/paperclip-telemetry.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/shared/src/telemetry/generated/paperclip-telemetry.ts) and implemented throughout the server codebase.

### Event Categories and Data Collected

| Category | Key Functions | Typical Payload Data |
|----------|---------------|---------------------|
| **Routine Execution** | `trackRoutineRun` in [`services/routines.ts`](https://github.com/paperclipai/paperclip/blob/main/services/routines.ts) | `routineId`, `companyId`, `agentId`, `durationMs`, success/failure status |
| **Project Management** | `trackProjectCreated` in [`routes/projects.ts`](https://github.com/paperclipai/paperclip/blob/main/routes/projects.ts) | `projectId`, `companyId`, creator type |
| **Goal Management** | `trackGoalCreated` in [`routes/goals.ts`](https://github.com/paperclipai/paperclip/blob/main/routes/goals.ts) | `goalId`, `companyId`, `goalLevel` |
| **Issue & Interaction** | `trackInteractionCreated`, `trackInteractionResolved` in [`services/issue-thread-interactions.ts`](https://github.com/paperclipai/paperclip/blob/main/services/issue-thread-interactions.ts) | `interactionId`, `issueId`, `companyId`, `agentId`, timestamps |
| **Agent Lifecycle** | `trackAgentCreated` in [`routes/agents.ts`](https://github.com/paperclipai/paperclip/blob/main/routes/agents.ts) | `agentId`, `companyId`, `role` |
| **Plugin Activity** | `telemetryClient.trackDynamic` in [`services/plugin-host-services.ts`](https://github.com/paperclipai/paperclip/blob/main/services/plugin-host-services.ts) | `pluginKey`, `eventName`, plugin-supplied custom dimensions |
| **Error Reporting** | `trackErrorHandlerCrash` in [`middleware/error-handler.ts`](https://github.com/paperclipai/paperclip/blob/main/middleware/error-handler.ts) | Error type, stack trace summary, request context |
| **Heartbeat** | `trackAgentFirstHeartbeat` in [`services/heartbeat.ts`](https://github.com/paperclipai/paperclip/blob/main/services/heartbeat.ts) | `agentId`, `companyId`, version information |
| **Feedback Export** | Events to `feedbackExportBackendUrl` | Feedback payloads, user-provided metadata |

### Anonymization and Data Boundaries

Paperclip's telemetry implementation deliberately excludes sensitive information. According to source code comments in [`services/workspace-git-operation-scheduler.ts`](https://github.com/paperclipai/paperclip/blob/main/services/workspace-git-operation-scheduler.ts), the telemetry client **never transmits**:

- Raw source code contents
- Configuration secrets or credentials
- Private file contents
- User passwords or API keys

All identifiers are scoped to Paperclip-specific entities (`companyId`, `agentId`, `routineId`) rather than exposing external system identifiers.

### Telemetry Backend Destination

When enabled, events transmit to the URL configured via `feedbackExportBackendUrl`, defaulting to `https://telemetry.paperclip.ing`. With telemetry disabled, this endpoint receives zero requests.

## Implementing Check for Telemetry in Custom Code

If building extensions or plugins, follow this pattern from [`services/routines.ts`](https://github.com/paperclipai/paperclip/blob/main/services/routines.ts) to conditionally track events:

```ts
import { trackRoutineRun } from "@paperclipai/shared/telemetry";
import { getTelemetryClient } from "../telemetry.js";

export async function runRoutine(routine) {
  const telemetryClient = getTelemetryClient();
  const start = Date.now();

  // ... routine execution logic ...

  const durationMs = Date.now() - start;
  if (telemetryClient) {
    trackRoutineRun(telemetryClient, {
      routineId: routine.id,
      companyId: routine.companyId,
      agentId: routine.agentId,
      durationMs,
      success: true,
    });
  }
}

```

Always guard `track*` calls with a `telemetryClient` existence check—this ensures compatibility with both enabled and disabled telemetry states.

## Summary

- **Disabling telemetry collection in Paperclip** requires setting `telemetry.enabled: false` in [`paperclip.yaml`](https://github.com/paperclipai/paperclip/blob/main/paperclip.yaml) and restarting the server
- The `telemetryEnabled` flag in [`server/src/config.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/config.ts) drives this behavior, defaulting to `true`
- When disabled, `initTelemetry()` creates a no-op client that silently discards all events
- Collected data includes usage patterns (routines, projects, goals, agents) and operational metrics (errors, heartbeats), **excluding source code and secrets**
- No environment variable override exists—configuration file modification is mandatory

## Frequently Asked Questions

### Does Paperclip telemetry collect my source code?

No. According to explicit design in the Paperclip source code, telemetry events contain only identifiers and metadata—never raw source code, file contents, or configuration values. The telemetry client in [`services/workspace-git-operation-scheduler.ts`](https://github.com/paperclipai/paperclip/blob/main/services/workspace-git-operation-scheduler.ts) is specifically architected to avoid credential-related data transmission.

### Can I disable telemetry using an environment variable?

No. Paperclip does not support environment variable configuration for telemetry. The only supported method to disable telemetry collection in Paperclip is modifying the `telemetry.enabled` value in your [`paperclip.yaml`](https://github.com/paperclipai/paperclip/blob/main/paperclip.yaml) or [`paperclip.json`](https://github.com/paperclipai/paperclip/blob/main/paperclip.json) configuration file.

### What happens to pending events when I disable telemetry?

Telemetry events are sent synchronously or near-synchronously during operation; there is no persistent queue. When you disable telemetry and restart, the no-op client immediately takes effect—no backlogged events transmit. Any code calling tracking functions simply passes through the no-op implementation without network activity.

### Is the telemetry backend self-hostable?

The default backend is `https://telemetry.paperclip.ing`, but the `feedbackExportBackendUrl` configuration option allows redirection to alternative endpoints. However, Paperclip's telemetry system is designed for the official backend; self-hosted alternatives would require compatible ingestion endpoints matching the schema defined in [`packages/shared/src/telemetry/generated/paperclip-telemetry.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/shared/src/telemetry/generated/paperclip-telemetry.ts).