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

Set telemetry.enabled: false in your 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 — Loads the telemetry.enabled flag from your configuration file
• server/src/telemetry.ts — Creates the telemetry client based on this flag

In server/src/config.ts, the loadConfig() function reads the telemetry setting:

// 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 (or paperclip.json) in your Paperclip instance directory.

2. Add the telemetry disable flag

   # 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:

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 and implemented throughout the server codebase.

Event Categories and Data Collected

Category	Key Functions	Typical Payload Data
Routine Execution	trackRoutineRun in services/routines.ts	routineId, companyId, agentId, durationMs, success/failure status
Project Management	trackProjectCreated in routes/projects.ts	projectId, companyId, creator type
Goal Management	trackGoalCreated in routes/goals.ts	goalId, companyId, goalLevel
Issue & Interaction	trackInteractionCreated, trackInteractionResolved in services/issue-thread-interactions.ts	interactionId, issueId, companyId, agentId, timestamps
Agent Lifecycle	trackAgentCreated in routes/agents.ts	agentId, companyId, role
Plugin Activity	telemetryClient.trackDynamic in services/plugin-host-services.ts	pluginKey, eventName, plugin-supplied custom dimensions
Error Reporting	trackErrorHandlerCrash in middleware/error-handler.ts	Error type, stack trace summary, request context
Heartbeat	trackAgentFirstHeartbeat in 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, 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 to conditionally track events:

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 and restarting the server
• The telemetryEnabled flag in 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 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 or 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}