> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skybridge.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Telemetry

> Learn what data Skybridge collects, why we collect it, and how to opt out.

# Telemetry

Skybridge collects anonymous usage telemetry to help us understand how the framework is being used and improve the developer experience. Telemetry is collected from two places:

1. **CLI commands** — when you run `skybridge dev`, `build`, `start`, etc.
2. **Skybridge server runtime** — when a Skybridge-powered MCP server handles a `tools/call` request.

**Telemetry is completely optional** and you can opt out at any time. The same opt-out controls apply to both telemetry collectors.

<Info>
  **Your Privacy Matters**

  We only collect aggregate usage data. We never collect personal information, project code, file contents, tool names, tool arguments, tool results, or any sensitive data.
</Info>

## What We Collect

### CLI commands

When you run a Skybridge CLI command, we collect the following anonymous information:

| Data             | Description                             | Example                    |
| ---------------- | --------------------------------------- | -------------------------- |
| **Command**      | The CLI command that was executed       | `dev`, `build`, `start`    |
| **Version**      | The Skybridge CLI version               | `1.2.3`                    |
| **Machine ID**   | A random UUID generated on first run    | `a1b2c3d4-...`             |
| **Session ID**   | A unique ID for this command execution  | `e5f6g7h8-...`             |
| **Outcome**      | Whether the command succeeded or failed | `success` or `failure`     |
| **Error**        | Error message if the command failed     | `Port 3000 in use`         |
| **Platform**     | Your operating system                   | `darwin`, `linux`, `win32` |
| **Node Version** | Your Node.js version                    | `v24.0.0`                  |
| **Is CI**        | Whether running in a CI environment     | `true` or `false`          |

### Skybridge server tool calls

When your deployed Skybridge server handles an MCP `tools/call` request, it emits a single anonymous counter so we can measure aggregate usage of Skybridge in production. We collect **only**:

| Data        | Description                                      | Example |
| ----------- | ------------------------------------------------ | ------- |
| **Version** | The Skybridge runtime version (major.minor only) | `1.2`   |

That's the entire payload. There is no machine ID, no session ID, no tool name, no arguments, no result, no IP-derived identity, and no user metadata attached to these events.

### What We Don't Collect

* ❌ Project names or file paths
* ❌ Source code or file contents
* ❌ Tool names, tool arguments, or tool results
* ❌ End-user prompts, conversations, or model output
* ❌ Environment variables or secrets
* ❌ IP addresses or location data stored or used as identifiers
* ❌ Personal identifiable information

## Why We Collect Telemetry

Telemetry helps us:

* **Understand usage patterns** — Which commands are most used? Where do developers spend time?
* **Identify common errors** — What problems do developers encounter most frequently?
* **Prioritize improvements** — Which platforms and Node versions should we support?
* **Measure adoption** — How is Skybridge being adopted in production over time, and which versions are still in active use?

## How to Opt Out

Telemetry preferences are stored per-machine. You can opt-out of telemetry using any of the following methods:

* updating the `telemetry.enabled` property in `~/.skybridge/config.json` configuration file
* using CLI `skybridge telemetry disable` command
* setting environment variables `SKYBRIDGE_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1`

The right opt-out method depends on **where** the telemetry is being emitted from:

* **Your local development machine**: Prefer the use of `skybridge telemetry disable` that will update your local `~/.skybridge/config.json` config file
* **CI runners** & **Deployed Skybridge servers**: Prefer the use of `SKYBRIDGE_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1` environment variable. It's much simpler than packaging a local `~/.skybridge/config.json`

### Using the Configuration File

Telemetry settings are stored per-machine in `~/.skybridge/config.json`:

```json theme={null}
{
  "machineId": "a1b2c3d4-e5f6-...",
  "telemetry": {
    "enabled": false
  }
}
```

This file is generated on first skybridge CLI command run with `telemetry.enabled` set to `true` by default.

Disable telemetry by setting `telemetry.enabled` to `false`.

<Note>
  In CI environments (GitHub Actions, GitLab CI, Jenkins, etc.), telemetry is **enabled by default** and the machine ID is set to the CI provider name (e.g., `GitHub Actions`).
</Note>

### Using the CLI

The easiest way to disable telemetry:

```bash theme={null}
skybridge telemetry disable
```

To re-enable it later:

```bash theme={null}
skybridge telemetry enable
```

Check your current telemetry status:

```bash theme={null}
skybridge telemetry status
```

All the above commands write and read from the `~/.skybridge/config.json` configuration file.

### Using Environment Variables

Set `SKYBRIDGE_TELEMETRY_DISABLED=1` to disable telemetry:

```bash theme={null}
# In your shell profile (.bashrc, .zshrc, etc.)
export SKYBRIDGE_TELEMETRY_DISABLED=1
```

Or use the standard `DO_NOT_TRACK` environment variable:

```bash theme={null}
export DO_NOT_TRACK=1
```

<Note>
  Environment variables always take precedence over the configuration file. If `SKYBRIDGE_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1` is set, telemetry is disabled regardless of any config file setting, and regardless of whether a config file exists at all.
</Note>

## Debug Mode

To see what CLI telemetry data would be sent without actually sending it, enable debug mode:

```bash theme={null}
SKYBRIDGE_TELEMETRY_DEBUG=1 skybridge dev
```

This will print the telemetry event to stderr instead of sending it, useful for understanding exactly what data is collected.

<Note>
  Debug mode applies to CLI telemetry only. The runtime tool-call counter has no payload beyond the version tag, so there is nothing to inspect — disabling telemetry is the only relevant control.
</Note>

## Data Handling

### CLI events

* CLI telemetry is sent to [PostHog](https://posthog.com/), a privacy-focused analytics platform
* Data is stored on PostHog's US servers
* We retain aggregated data for product analytics purposes
* Individual events are anonymized and cannot be linked to specific users

### Tools/call events

* The Skybridge runtime emits a [DogStatsD](https://docs.datadoghq.com/developers/dogstatsd/) counter over UDP for every `tools/call`
* Packets are sent fire-and-forget; failures never block or delay tool execution
* They are received by a Skybridge-operated [Vector](https://vector.dev/) instance
* Only aggregate per-version counters are stored — there is no per-event record retained, and individual calls cannot be linked to a server, project, or user