Auto-update

The CMDOP agent ships with an opt-in auto-updater. This guide covers channels, cadence, and pinning a version when stability beats novelty.

How auto-update works

The daemon checks for new releases on a schedule. When a candidate is found:

Download the new binary to a side-by-side location.
Verify checksum and signature.
Atomic rename swap; restart the daemon.
Heartbeat resumes within seconds.

The whole flow takes 5–30 seconds depending on download size. Active sessions survive (the daemon’s session manager hands off seamlessly across restarts).

Channels

Channel	Cadence	Best for
`stable`	~monthly	Production servers.
`beta`	~weekly	Staging, internal QA.
`nightly`	per-merge	Personal dev machines, scratch VMs.

Switch channels:


cmdop update --channel stable
cmdop update --channel beta
cmdop update --channel nightly

The choice persists in config.yaml until you change it.

Enabling auto-update


cmdop update --auto on
cmdop update --auto off

When on, the daemon checks every 6 hours by default. Override:


cmdop update --auto on --interval 24h

Manual update


cmdop update                     # check + apply if available
cmdop update --check             # check only, do not apply
cmdop update --version v1.2.3    # install a specific version

--check is useful in monitoring to surface “an update is waiting” without forcing a restart.

Pinning a version

Production fleets often want predictable rollouts. Pin:


cmdop update --pin v1.2.3

Pinned versions ignore the channel cadence. To unpin:


cmdop update --unpin

Pinning is per-machine. Centralized fleet-wide pinning is on the roadmap; for now, push the pin via your config-management tool (Ansible, Terraform, etc.).

Rollback

If a new version misbehaves:


cmdop update --rollback

The previous binary stays cached for 7 days. Rollback is one operation: stop, swap, start. After 7 days the cached binary is purged.

Verifying signature

The auto-updater verifies a signed checksum before swapping. Tampering aborts the swap and writes a CRITICAL log line. To verify a binary you downloaded manually:


cmdop update --verify ./cmdop

The signing key fingerprint is published in the release notes.

Logging

Update events land in the daemon’s log:


cmdop agent logs -f | grep update

And in the cabinet’s audit log under event=agent_update.

Pitfalls

Sandboxed binary path — installs into /usr/local/bin/ need write access. Run the agent as a user with permissions, or install to ~/.local/bin/.
Long-lived sessions — they survive restarts via the session manager, but the network round-trip causes a brief gap. Schedule updates outside critical windows.
Custom builds — auto-update overwrites custom builds. Pin if you maintain a fork.

nightly channel ships untested code. Use it on your laptop, not on production. Promote good nightlies to beta and then to stable.

Pinned versions still receive security advisories in the changelog feed. Watch the changelog and bump the pin manually for security-critical releases.