How to Configure gstack Telemetry and What Data It Collects

gstack telemetry is a lightweight, opt-out system that logs high-level operational events—such as domain skill lifecycles and CDP method calls—to a local JSONL file, deliberately excluding all skill bodies, user arguments, and generated text.

gstack, an open-source project available at garrytan/gstack, implements a minimal telemetry subsystem designed for transparency and user control. The gstack telemetry architecture records discrete operational signals to help improve the tool while enforcing strict privacy boundaries that prevent the capture of sensitive content. All configuration logic and data schemas are defined in TypeScript within the browse/src/telemetry.ts module.

Configuring gstack Telemetry

Environment Variable Overrides

The fastest way to disable telemetry is by setting the GSTACK_TELEMETRY_OFF environment variable. When set to 1, the logTelemetry function in browse/src/telemetry.ts immediately becomes a no-op, preventing any disk writes or network calls for the duration of the process.

# Disable for the current shell session

export GSTACK_TELEMETRY_OFF=1
bun run gstack

# Enable explicitly (default behavior)

GSTACK_TELEMETRY_OFF=0 bun run gstack

The module checks process.env.GSTACK_TELEMETRY_OFF on each invocation, with a test helper _resetTelemetryCache available to clear cached values during testing.

Persistent Configuration with gstack-config

For permanent settings across sessions, use the gstack-config CLI helper. This tool writes the selected tier to a state file located at ~/.gstack/.telemetry. The system supports three distinct tiers:

• off: Completely disables event collection; logTelemetry returns immediately without action.
• anonymous: Stores all events locally in ~/.gstack/analytics/browse-telemetry.jsonl without network transmission.
• community: Retains local storage and additionally triggers periodic upload to remote analytics services via the telemetry-sync command.

# Set tier via CLI

gstack-config set telemetry off
gstack-config set telemetry anonymous
gstack-config set telemetry community

The helper resolves the gstack home directory using resolveGstackHome from browse/src/config.ts, which checks $GSTACK_HOME before defaulting to $HOME/.gstack.

Telemetry File Storage

All telemetry records append to ~/.gstack/analytics/browse-telemetry.jsonl. The path is constructed dynamically from the gstack home directory, ensuring users retain full ownership to inspect, delete, or back up their data. Writes are performed asynchronously in a fire-and-forget manner; any disk errors (e.g., permission denied or disk full) are silently swallowed to guarantee that telemetry collection never crashes the main application process.

What Data gstack Telemetry Collects

Event Structure and Common Fields

Every telemetry entry is a single line of JSON (JSONL) containing at minimum an event string and an ISO-8601 ts timestamp. As implemented in browse/src/telemetry.ts, the system records only high-level operational metadata—never skill implementations, command arguments, or conversation history.

Domain Skill Lifecycle Events

These events are emitted from browse/src/domain-skill-commands.ts to track skill management operations:

• domain_skill_saved: Triggered when a skill is persisted, containing fields { host, scope, state, bytes }—the origin host, scope (project or global), resulting state, and byte size of the body.
• domain_skill_state_changed: Records state transitions with { host, from_state, to_state }, such as quarantined to active.
• domain_skill_save_blocked: Logs content filter rejections via { host, reason }.
• domain_skill_fired: Captures invocation events with { host, source, version }, indicating whether the trigger was agent or human.

Chrome DevTools Protocol (CDP) Events

The system monitors CDP usage for security auditing and performance analysis:

• cdp_method_called: Successful calls include { domain, method, allowed, scope }.
• cdp_method_denied: Blocked calls log { domain, method } when the allow-list rejects a request.
• cdp_method_lock_acquire_ms: Performance metrics capturing lock acquisition latency via { domain, method, ms }.

Privacy Guarantees

The telemetry system explicitly avoids collecting sensitive data. According to the source code in browse/src/telemetry.ts, the following are never recorded:

• Skill body content or source code
• User-provided command-line arguments or inputs
• Agent-generated text or conversation transcripts
• Authentication credentials or personal identifiers

Working with Telemetry Programmatically

Logging Custom Events

Developers can utilize the same internal API to record custom high-level events:

import { logTelemetry } from './browse/src/telemetry';

// This writes only if telemetry is enabled
logTelemetry({
  event: 'cdp_method_called',
  domain: 'Network',
  method: 'enable',
  allowed: true,
  scope: 'session',
});

Testing with Temporary Storage

During automated testing, redirect telemetry output and reset the configuration cache:

process.env.GSTACK_HOME = '/tmp/gstack-test-home';
process.env.GSTACK_TELEMETRY_OFF = '0'; // Ensure enabled for test

// Import after setting environment
import { logTelemetry, _resetTelemetryCache } from './browse/src/telemetry';

_resetTelemetryCache(); // Clear any cached config
logTelemetry({
  event: 'domain_skill_saved',
  host: 'example.com',
  scope: 'project',
  state: 'active',
  bytes: 123
});

Summary

• gstack telemetry is disabled by setting GSTACK_TELEMETRY_OFF=1 or using gstack-config set telemetry off, with preferences stored in ~/.gstack/.telemetry.
• Events append to ~/.gstack/analytics/browse-telemetry.jsonl in JSONL format, capturing only metadata like domain_skill_saved and cdp_method_called.
• The system strictly excludes skill bodies, user arguments, and generated text, recording only anonymous operational signals such as timestamps, host origins, and byte counts.
• Runtime configuration is evaluated in browse/src/telemetry.ts, with the cache resettable via _resetTelemetryCache for isolated testing scenarios.

Frequently Asked Questions

How do I completely disable gstack telemetry?

Set the environment variable GSTACK_TELEMETRY_OFF=1 before executing any command, or run gstack-config set telemetry off to write the preference permanently to ~/.gstack/.telemetry. When disabled, the logTelemetry function in browse/src/telemetry.ts becomes a no-op, ensuring no data is written to disk or transmitted over the network.

What is the difference between anonymous and community telemetry tiers?

The anonymous tier stores all events locally in ~/.gstack/analytics/browse-telemetry.jsonl without any network activity, while the community tier permits the telemetry-sync command to upload aggregated data to remote analytics servers. Both tiers collect identical event schemas; only the data transmission behavior differs.

Does gstack telemetry record the content of my skills or prompts?

No. The implementation in browse/src/telemetry.ts deliberately excludes skill bodies, user-provided arguments, and agent-generated text from all event payloads. For example, the domain_skill_saved event records metadata such as the host, scope, state, and byte size, but never the actual skill implementation or content.

Where can I inspect the telemetry data that has been collected?

All telemetry records are stored in ~/.gstack/analytics/browse-telemetry.jsonl (or $GSTACK_HOME/analytics/browse-telemetry.jsonl if the home directory is customized). The file uses JSON Lines format, with one JSON object per line, allowing you to view entries with standard tools like cat, parse them with jq, or delete the file entirely to clear history.

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