eyehands 1.6.0: free-tier install heartbeat

Releases & policy · ~4 min read · 11 April 2026

by Fireal Software · ~4 min read

Short release. One feature: free-tier installs now send an anonymous heartbeat to portal.fireal.dev/api/updates/eyehands/ping every 6 hours so I have a rough count of real usage. This has been the single biggest gap in my understanding of who uses eyehands — paid installs are counted via the existing license-check path, but free installs were invisible until 1.6.0.

This post is the release notes. If you want the full privacy model, with exact payload fields and opt-out options, see the separate privacy disclosure post.

What’s sent

Every 6 hours, free installs POST this payload:

{
  "installId": "sha256-hash-of-a-local-random-token",
  "installToken": "hex-of-the-same-token-client-side",
  "deviceId": "sha256-of-hostname-and-SystemRoot",
  "version": "1.6.0"
}

That’s it. No IP logging, no hardware info, no usage data, no file paths, no window titles, no screenshots, no input data, no license keys or email addresses.

What isn’t sent

I listed the exclusions explicitly in the privacy post because “anonymous” is often used as a cover for sending a lot more than advertised:

No IP address persisted
No OS / CPU / GPU / hardware info
No usage / endpoint-call data
No file paths, window titles, or screen content
No input data (keystrokes, mouse clicks, typed text)
No license keys or email addresses (paid installs don’t use this path)

How to opt out

Three independent ways, any of which disables the heartbeat completely:

# Option 1: CLI flag
eyehands --no-telemetry

# Option 2: Marker file
touch "%APPDATA%/eyehands/.no-telemetry"    # or in repo root for source checkouts

# Option 3: Block outbound connections to portal.fireal.dev
#   (or just run offline)

When either --no-telemetry or the .no-telemetry file is present, eyehands checks for them before generating the install token. Opting out never touches the filesystem for telemetry purposes at all.

Why now

eyehands has been live for a few months and I’ve been making roadmap decisions blind — I know how many paid installs there are (from licensing) but not how many free users. That makes it hard to decide whether a feature is useful to “90% of my user base” or “three people on the free tier”.

The anonymous heartbeat gives me enough signal to make those decisions (count of unique installs, distribution of versions, rough device-level dedup) without collecting anything I’d be uncomfortable sending from my own machine as a user.

If this trade-off isn’t one you’re comfortable with: --no-telemetry is a single flag and the feature works identically. Nothing in eyehands depends on the heartbeat being active.

Implementation details

_free_checkin() in eyehands/server.py is the function. It runs on a daemon thread so a slow portal can’t block the first /screenshot. Results are cached for 6 hours in .free_ping_cache so repeat server starts within the cache window don’t re-ping.

On the server side, portal.fireal.dev stores only sha256(installToken) in the database. The plaintext token is verified once per request and discarded. A compromised database can’t impersonate an install because the plaintext only lives on your machine.

Upgrade

pip install --upgrade eyehands

Or via the built-in update endpoint:

curl -X POST -H "Authorization: Bearer $(cat .eyehands-token)" \
  http://127.0.0.1:7331/update

What’s next

1.7 will probably focus on the Claude Code plugin.json wrapper and official marketplace submission. I want eyehands to ship as a proper plugin, not just a skill, so users can install it with /plugin install eyehands@<marketplace> instead of pip install eyehands && eyehands --install-skill.