Key-refresh daemon

A small on-device relay that keeps a long session authenticated by re-minting the client key underneath it.

Anyray hands each developer a short-lived client key (ark_…). Tools that bake the key in once at launch — Claude Code and Codex on a subscription seat — start failing with 401 the moment that key lapses, mid-session, and the fix is a relaunch. The key-refresh daemon removes that failure mode: anyray-connect points those tools at 127.0.0.1 instead, and the daemon fills a freshly minted key into each request on its way to the gateway.

On by default

Nothing to enable. A normal anyray-connect run installs it for the tools that need it. --no-key-refresh opts out and forces the legacy bake-once lane.

What it does

The daemon relays your request to the gateway byte for byte. Its one mutation is filling the empty x-anyray-api-key slot that Connect leaves in the tool's config — the enrollment certificate on the machine re-mints a key when the old one nears expiry, and that key goes into the request. Everything else is untouched: method, path, body, streaming, and the gateway's response, including its status code.

• It never routes around the gateway. If the gateway is unreachable, your request fails, the same as it would without the daemon.
• It never overrides a credential you presented. A request that carries its own key or Bearer token is relayed as-is.
• It sees prompt and response bytes only in transit — nothing is logged or stored on the device.

Check it

anyray-connect status    # daemon port and health
anyray-connect doctor    # full check, including the loopback leg

Endpoint security (EDR/AV) allow-list

To survive a reboot, the refresher has to be a login item — and that is the same shape a persistence implant uses. Heuristic scanners (SentinelOne, CrowdStrike, Defender ATP) sometimes act on the resemblance: they kill the process and quarantine the unit file. The tell is anyray-connect doctor reporting the daemon enabled but not responding and the schedule missing at the same time, on a machine whose enrollment is otherwise clean.

Print the sheet your security team needs, from the affected machine:

Print the allow-list

anyray-connect doctor --security-review

It runs no probes and needs no gateway or key, so it still works after a quarantine. What it lists:

What	macOS	Linux (systemd --user)	Windows
Key-refresh daemon	~/Library/LaunchAgents/ai.anyray.connect.fallback.plist	~/.config/systemd/user/anyray-fallback.service	not installed
Key-refresh scheduler	~/Library/LaunchAgents/ai.anyray.connect.refresh.plist	~/.config/systemd/user/anyray-refresh.timer + .service	Task Scheduler task \AnyrayConnectKeyRefresh

Both run unprivileged as the logged-in user from ~/.anyray/bin/anyray-connect. The daemon binds 127.0.0.1 only — never a routable interface — and its only outbound destination is your own Anyray gateway over HTTPS.

The daemon's label still says fallback

The label is baked into unit files already installed on every enrolled machine, so it keeps its historical spelling. It is the key-refresh daemon; the provider-direct fallback lane it was named for is gone (see below).

Until the allow-list lands, anyray-connect --no-key-refresh unblocks the seat immediately: it installs no background service at all and points tools straight at the gateway. Optimization, metering, and spend attribution are unaffected — those happen at the gateway, not on the device. The only cost is that a lapsed key needs a re-run.

Turning it off

Opt out

anyray-connect --no-key-refresh    # point tools straight at the gateway
anyray-connect --revert            # remove the daemon and the stored enrollment

Your tools then carry a static key that was minted at launch, and a long session will 401 when that key expires — re-run anyray-connect (or relaunch the tool) to get a fresh one.

Zero-touch fleets

On MDM-provisioned machines the daemon also carries the shell/SDK lane of zero-touch enrollment: a gateway 401 for a request that presented no credential triggers a desktop sign-in notification (device-grant URL + code), and once the user is enrolled the daemon completes credentialless requests with that user's own key. A request that presents any credential of its own is never touched. See MDM & bulk enrollment.

The retired fallback lane

Earlier releases had a second, opt-in mode (anyray-connect --fallback) where the daemon routed straight to the provider during a gateway outage. It required the org's provider key to sit encrypted on every developer machine, so it was removed. --fallback / --no-fallback are still parsed and ignored, so an old MDM payload doesn't break.

If a seat ever ran --fallback, have them re-run their install command. The installer always fetches the latest release, and the run deletes the provider key that lane cached on the machine (~/.anyray/fallback-bundle.enc and its key) and restarts the daemon on the current build. Tools keep working throughout — the loopback stays, it just loses the provider-direct leg.