huggingface_hub silently fingerprints which AI coding agent you’re using and sends it as telemetry

Understanding Hugginface_hub’s Hidden Agent Fingerprinting and How to Protect Your Privacy

In the evolving landscape of AI development and deployment, transparency around data sharing and telemetry is more critical than ever. Recently, a nuanced discovery highlighted that the huggingface_hub Python library silently detects which AI coding tools are in use and transmits this information as telemetry—raising questions about privacy and data visibility for developers and users working locally or in controlled environments.

---

The Unexpected Discovery

During routine troubleshooting of unauthorized network activity involving a local Automatic Speech Recognition (ASR) module, the contributor noticed an unfamiliar file in their Hugging Face cache directory:

~/.cache/huggingface/.agent_harnesses.json

This small (approximately 6 KB) JSON file contains a registry of 26 AI coding agents, such as Claude Code, GitHub Copilot, Cursor, Gemini CLI, Devin, Cline, Goose, Codex, and others. For each agent, the registry lists specific environment variables that are typically set during their execution.

An example snippet of this registry:

json
{
"standardEnvVars": ["AI_AGENT", "AGENT"],
"harnesses": {
"cursor": {
"prettyLabel": "Cursor",
"envVars": {"CURSOR_TRACE_ID": "*"}
},
"claude-code": {
"prettyLabel": "Claude Code",
"envVars": {"CLAUDECODE": "*", "CLAUDE_CODE": "*"}
},
"github-copilot": {
"prettyLabel": "GitHub Copilot",
"envVars": {"COPILOT_MODEL": "*", "COPILOT_GITHUB_TOKEN": "*"}
}
// ...additional agents
}
}

---

How Does huggingface_hub Detect Your AI Tool?

The core mechanism resides in the library’s _detect_agent.py module, which operates as follows:

1. Fetching and Caching the Registry:
   The module retrieves a JSON registry from the Hugging Face API endpoint .../api/agent-harnesses, caching it locally for 24 hours to minimize repeated requests.

2. Detecting the Agent:
   On every API interaction with Hugging Face (e.g., model downloads, tokenizations, updates), the library scans your environment variables, comparing them against known signatures in the cache to identify which agent is active.

3. Sending Telemetry:
   The detected agent’s name is appended as a custom header to the API request, effectively reporting which AI tool is being used—without explicit user notification.

This subtle telemetry happens in the background, meaning that even if you’re running local models, the library might be reporting your development environment’s specifics to Hugging Face.

---

How Was This Detected?

In case you’re curious about practical triggers: the detection was revealed when tracing a background HTTPS call initiated during the import of faster-whisper, an open-source speech recognition library backed by Hugging Face. When passing a model name (e.g., "base.en") instead of a local path, the library automatically contacts the Hub to check for updates or download the model. During this process, it also transmits the detected agent information via headers.

The registry file (.agent_harnesses.json) was the cache resulting from this background request, providing a snapshot of all known agents and their environment variables.

---

Practical Steps to Mitigate or Block Agent Detection

If you value control over your environment and wish to prevent such silent fingerprinting, several strategies are available:

1. Environment Variables to Disable Telemetry and Network Access:

Set these before running your code:

bash
export HF_HUB_OFFLINE=1
export TRANSFORMERS_OFFLINE=1
export HF_HUB_DISABLE_TELEMETRY=1

• HF_HUB_OFFLINE=1 prevents any network interaction with Hugging Face, blocking agent detection and model downloads.
• TRANSFORMERS_OFFLINE=1 similarly enforces offline mode for the transformers ecosystem.
• HF_HUB_DISABLE_TELEMETRY=1 aims to disable telemetry, although its effect on agent detection headers may be limited.

2. Use Local Paths Instead of Model Names

Instead of specifying a model via its name:

python
model = WhisperModel("base.en")

Use a local directory path:

python
model = WhisperModel("/path/to/local/model/")

This instructs the library to load the model from disk and skips the online check, thereby avoiding telemetry altogether.

3. Network-Level Blocking

Employ a custom firewall or socket wrapper that intercepts outbound network calls made by the library before they occur. This approach involves customizing Python’s socket behavior to:
– Block connections to servers like huggingface.co
– Raise errors if the code attempts to connect to disallowed hosts

Such a solution can be implemented via a sitecustomize.py script that patches socket functions, providing granular control without modifying the library code.

---

What’s in the Registry File?

The .agent_harnesses.json file contains no API keys or credentials—only a registry of agent signatures. Deleting this file:

bash
rm ~/.cache/huggingface/.agent_harnesses.json

prevents the detection until it is regenerated via an online request. However, setting HF_HUB_OFFLINE=1 ensures it won’t be downloaded again unless the environment is reconfigured.

---

Why Should This Matter to You?

For developers and organizations committed to maintaining privacy and transparency, this discovery underscores a subtle aspect of how modern libraries operate:

• Data Privacy:
  While model weights and input data remain local, the environment—specifically which tools and agents are in use—may be quietly reported, contributing to an ecosystem-wide dataset.

• Developer Trust:
  Silent environment fingerprinting without explicit user consent can erode trust, especially for those who select local models precisely to avoid external telemetry.

• Ecosystem Transparency:
  Hugging Face’s registry of agents is maintained openly, but unbeknownst to many users, this registry enables silent detection and reporting.

---

Final Thoughts

While current implementation appears to serve primarily for ecosystem analytics and usage statistics, awareness is key. Developers concerned about privacy can deploy simple measures—such as disabling network access or using local file paths—to mitigate silent fingerprinting.

Staying informed and vigilant ensures that your work remains as private and controlled as intended, fostering a more transparent and trustworthy AI development environment.

---

References & Further Reading:

• Hugging Face API documentation
• huggingface_hub source code (publicly available on GitHub)
• Community discussions on AI tool telemetry and privacy considerations

---

Maintain your environment and code privacy by reviewing how libraries communicate with external services and implementing protective measures where appropriate.