# Security and Privacy Considerations for Context Hub Telemetry: Complete Implementation Guide

> Learn security and privacy considerations for Context Hub telemetry. Implement robust data protection and opt-out features for anonymous usage collection without PII.

- Repository: [Andrew Ng/context-hub](https://github.com/andrewyng/context-hub)
- Tags: how-to-guide
- Published: 2026-03-20

---

**Context Hub collects anonymous usage telemetry without transmitting personally identifiable information (PII) or source code, offering built-in opt-out mechanisms via configuration files and environment variables.**

The `andrewyng/context-hub` CLI implements a privacy-first telemetry system designed to improve the content registry while maintaining strict data minimization principles. All telemetry logic resides in the `cli/src/lib/` directory, with explicit safeguards against data leakage verified by comprehensive test suites.

## Built-in Opt-Out Mechanisms

The telemetry system provides redundant disable methods implemented in [`cli/src/lib/telemetry.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/telemetry.js) (lines 5-22). The `isTelemetryEnabled()` helper evaluates these controls in priority order: environment variables override configuration files, which override defaults.

**Environment Variable Control**

Export `CHUB_TELEMETRY=0` (or `false`) to immediately disable telemetry for the current session:

```bash
export CHUB_TELEMETRY=0
chub search "stripe"

```

This setting takes precedence over all other configurations (lines 5-7).

**Configuration File Method**

Add `telemetry: false` to `~/.chub/config.yaml`. When parsed by [`cli/src/lib/config.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/config.js), this value causes `isTelemetryEnabled()` to return `false`, short-circuiting all telemetry paths before network initialization (lines 5-9).

**Programmatic Status Check**

Import the helper to verify telemetry state within custom scripts:

```javascript
import { isTelemetryEnabled } from './cli/src/lib/telemetry.js';

if (isTelemetryEnabled()) {
  console.log('Telemetry is active – anonymized usage data will be sent.');
} else {
  console.log('Telemetry is disabled.');
}

```

## Data Collection Scope and Limitations

Context Hub telemetry strictly limits data transmission to non-identifying metadata. The system explicitly excludes error messages, stack traces, and user content from all payloads.

**Analytics Events (PostHog Integration)**

In [`cli/src/lib/analytics.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/analytics.js) (lines 60-71), the `client.capture()` method transmits only generic runtime metadata:

```javascript
client.capture({
  distinctId,
  event,
  properties: {
    ...properties,
    platform: process.platform,
    node_version: process.version,
    cli_version: _cliVersion || undefined,
  },
});

```

This implementation sends only the **client ID**, platform type, Node.js version, and CLI version. No error messages or stack traces are included, as verified by tests in [`cli/tests/lib/analytics.test.js`](https://github.com/andrewyng/context-hub/blob/main/cli/tests/lib/analytics.test.js) (lines 63-81). The `posthog-node` library loads lazily; if the dependency is missing, analytics are silently skipped (lines 33-45).

**Sending Custom Analytics Events**

When telemetry is enabled, use the `trackEvent` function with the `setCliVersion` initializer:

```javascript
import { trackEvent, setCliVersion } from './cli/src/lib/analytics.js';

setCliVersion('1.4.0');

await trackEvent('custom_command', {
  command_name: 'my-tool',
  entry_id: 'openai/chat',
});

```

**Feedback Submissions**

The separate feedback endpoint (`/feedback`) defined in [`cli/src/lib/telemetry.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/telemetry.js) (lines 58-78) accepts optional user ratings with a minimal payload:

```javascript
body: JSON.stringify({
  entry_id: entryId,
  entry_type: entryType,
  rating,
  doc_lang: opts.docLang || undefined,
  agent: {
    name: opts.agent || detectAgent(),
    version: detectAgentVersion(),
  },
})

```

Note that this excludes actual documentation content, file contents, or path information that could reveal project structure.

## Anonymous Client Identification

Rather than transmitting raw machine identifiers, the CLI generates a **stable, anonymous 64-character hexadecimal ID** through cryptographic hashing. In [`cli/src/lib/identity.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/identity.js) (lines 66-73), the system retrieves the machine UUID (from `/etc/machine-id` on Linux or OS-specific GUIDs) and processes it through SHA-256:

```javascript
const uuid = getMachineUUID();
const hash = createHash('sha256').update(uuid).digest('hex');
writeFileSync(idPath, hash, 'utf8');

```

The raw UUID never leaves the host; only the hash is stored in `~/.chub/client_id` and transmitted. This identifier is cached in memory for the process lifetime to prevent unnecessary disk reads.

## Network Security and Error Handling

All telemetry transmissions implement defensive mechanisms to prevent CLI hangs and data leakage. In [`cli/src/lib/telemetry.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/telemetry.js) (lines 48-52), each request wraps an `AbortController` with a **3-second timeout**:

```javascript
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 3000);

```

Network errors are caught and suppressed; the user interface never exposes stack traces or connection details. All communications use HTTPS by default (`https://api.aichub.org/v1`), with the underlying Node.js `https` module enforcing certificate validation.

## Self-Hosting and Endpoint Customization

Organizations requiring data residency can redirect telemetry to internal infrastructure. The `CHUB_TELEMETRY_URL` environment variable overrides the default endpoint:

```bash
export CHUB_TELEMETRY_URL="https://telemetry.mycompany.com/v1"
chub get openai/chat

```

This routes all analytics events through corporate servers, allowing security teams to inspect traffic, implement additional filtering, or enforce geographic data boundaries while maintaining full CLI functionality.

## Summary

- **Opt-out by design**: Disable telemetry via `~/.chub/config.yaml` (`telemetry: false`) or `CHUB_TELEMETRY=0`, with logic implemented in [`cli/src/lib/telemetry.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/telemetry.js) (lines 5-9).
- **Anonymous identifiers only**: Client IDs are SHA-256 hashes of machine UUIDs, generated in [`cli/src/lib/identity.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/identity.js) (lines 66-73), ensuring no raw hardware identifiers leave the host.
- **Metadata-only collection**: Analytics payloads contain only platform, Node.js version, and CLI version; no source code, file paths, or error messages are transmitted.
- **Secure transmission**: All traffic uses HTTPS with 3-second timeouts via `AbortController` (lines 48-52) to prevent hanging.
- **Verified by tests**: Test suites in [`cli/tests/lib/analytics.test.js`](https://github.com/andrewyng/context-hub/blob/main/cli/tests/lib/analytics.test.js) (lines 63-81) explicitly verify the absence of `error_message` properties and PII.
- **Enterprise flexibility**: The `CHUB_TELEMETRY_URL` variable enables self-hosted collectors for air-gapped or compliant environments.

## Frequently Asked Questions

### Does Context Hub telemetry collect my source code or project files?

No. The telemetry system explicitly excludes source code, documentation content, and file paths from all transmissions. As implemented in [`cli/src/lib/analytics.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/analytics.js) and verified in [`cli/tests/lib/analytics.test.js`](https://github.com/andrewyng/context-hub/blob/main/cli/tests/lib/analytics.test.js), payloads contain only metadata such as platform type, Node.js version, and entry identifiers.

### How do I completely disable telemetry for all users on a system?

Set the environment variable `CHUB_TELEMETRY=0` in system-wide shell profiles such as `/etc/profile` or `/etc/environment`. This takes precedence over user-specific configuration files. Alternatively, set `telemetry: false` in the global [`config.yaml`](https://github.com/andrewyng/context-hub/blob/main/config.yaml) if your deployment supports system-wide configuration paths.

### What is the client ID and how is it generated?

The client ID is a 64-character hexadecimal string generated by hashing the machine's UUID with SHA-256 in [`cli/src/lib/identity.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/identity.js) (lines 66-73). The raw machine identifier never leaves the device; only the cryptographic hash is stored in `~/.chub/client_id` and transmitted, providing stable analytics aggregation without hardware fingerprinting.

### Can I redirect telemetry to my own server for compliance purposes?

Yes. Set the `CHUB_TELEMETRY_URL` environment variable to your custom HTTPS endpoint before running CLI commands. This overrides the default `https://api.aichub.org/v1` URL, allowing you to self-host the collector, implement additional filtering, or maintain data within specific geographic boundaries.