Operations

Upgrades#

ClawMetry ships many releases a day. An observability sidecar that lags the fleet by weeks is worse than useless: it renders old shapes, misses fixes for the very bugs it is supposed to surface, and quietly makes the dashboard look broken. So the daemon keeps itself current by default, on rails, with a hard kill switch.

If you would rather drive it by hand, skip to Turning it off.

The three ways to upgrade#

All three land on the same wheel from PyPI. The automatic path is the only one that also restarts the daemon for you.

What the daemon actually does#

The update-check worker (routes/update_check.py) runs inside the sync daemon and does four things on a loop:

1. Poll PyPI every CLAWMETRY_UPDATE_CHECK_SECS seconds (default 60,

clamped to [30, 86400]). This is one small CDN-cached GET per node per minute.

1. Pick a target. Not necessarily the absolute latest — the newest release

that is newer than what you run and has survived the stability window (see below).

1. Install it with pip, if auto_update is on for this node.
2. Restart, so the new wheel is actually the code that runs.

Only the daemon role installs. A dashboard process — often a foreground terminal a human is watching — will never pip-install and exit underneath you unless you explicitly set CLAWMETRY_AUTO_UPDATE=1 yourself.

The stability window#

CLAWMETRY_AUTOUPDATE_MIN_AGE_HOURS is how many hours a release must have sat on PyPI before an unattended install will take it. The default is 0 — the fleet tracks the absolute latest.

That default is deliberate. An earlier 48-hour gate meant that during an active release run every published version was too fresh, so nodes never found an installable target and froze on an old build for days. The safety net for a bad wheel is the rollback guard below, not a stale window.

Set it if you want a more conservative fleet:

CLAWMETRY_AUTOUPDATE_MIN_AGE_HOURS=24    # only install releases 24h+ old

The selection logic honours it: with a window set, the daemon installs the newest release that has aged in, which keeps the node at latest-minus-window rather than frozen.

Failed installs back off#

A pip install that fails is not retried on the next 60-second tick. The failed version is recorded with a deadline and skipped until it passes:

Newer releases are still considered during the backoff — only the specific version that failed is held down.

Restart behaviour#

How the daemon comes back depends on whether something is supervising it.

The re-exec exists because an unsupervised node used to install the wheel and then keep the old code in memory indefinitely — a containerised node stayed stale until somebody bounced the pod. Disable it with CLAWMETRY_AUTOUPDATE_EXEC_RESTART=0.

The rollback guard#

clawmetry/update_guard.py is a firmware-OTA-style crash-loop guard. A self-update arms it right after pip succeeds; the daemon checks it at every boot.

On a crash loop the guard pip-installs the previous version and exits; the supervisor respawns on the rolled-back build. The rollback is written to ~/.clawmetry/update_rollback.json so the dashboard and the heartbeat can say what happened instead of leaving you with a mysteriously old version.

Plans turn it on#

When the daemon's heartbeat resolves an entitled plan — Trial, Starter, Pro or Enterprise — it enables auto_update for that node, so "I pay for this, the node should stay current" is true without a manual step.

Three properties of that behaviour matter:

• It only ever enables. A downgrade never silently re-disables what you

chose, and it never disables a setting you turned on.

• It respects an explicit opt-out: with CLAWMETRY_AUTO_UPDATE set to

0 / false / no / off, the plan sync does nothing.

• It no-ops for free and inactive plans.

The same heartbeat also provisions clawmetry-pro immediately on an upgrade, so paid runtimes start syncing within a cycle or two rather than waiting for the next entitlement watcher pass. See Plans and entitlements.

Turning it off#

CLAWMETRY_AUTO_UPDATE=0

That is the hard kill switch. It is checked before anything else and it beats the stored config, the plan sync, and the default-on policy. Put it in the daemon's environment — the launchd plist, the systemd unit, the container spec — not just in an interactive shell, or the daemon will never see it.

To turn it off for one node without an env var, use the config endpoint:

curl -X POST localhost:8900/api/update-check/config \
  -H 'Content-Type: application/json' \
  -d '{"auto_update": false}'

Inspecting the state#

Across a fleet, the same picture is in the nodes view — a node stuck several versions behind is usually one whose daemon is not running at all, which clawmetry status will tell you in one line.

Environment reference#

→ Uninstall · Troubleshooting