Updates and release channels

Neither the agent nor the CA connector updates itself. A separate binary, the aethercert Update Service, is the only thing on a host that replaces either of them. It is installed alongside them by default.

Versioning

Every component uses YEAR.MONTH.VERSION.FIX.HOTFIX - for example 2026.8.3.0.0 - and each is versioned independently. Older schemes are still parsed and compared, because agents in the field report them, but they can no longer be published.

aethercert-agent version and the equivalent on each binary print what that host is running. The dashboard shows the same on the agent list.

What happens on a host

The Update Service wakes twice a day, at two fixed UTC anchors offset by a per-host jitter of up to about two and a half hours. The offset is derived from a stable identifier of the host, so the same machine lands at the same two times every day - easy to reason about in a log - while a whole fleet is scattered rather than hitting the CDN in the same second.

On each cycle it asks the control plane, per component, whether there is an update. The answer is either "no" or a manifest naming exactly one build: version, an immutable URL, the SHA-256, the size and a detached signature. If there is one, it downloads it, verifies it, stops the service, swaps the binary in and starts it again.

The cheap check runs on that twice-daily cadence; the actual download is throttled separately and far more conservatively, so a fleet does not re-fetch the same bytes.

A check can also be triggered on demand from the Windows tray icon.

The three checks

Every one of them runs before a single byte is written anywhere it could be executed from, and none is skippable by a flag:

1. The declared size matches the manifest, both from the response's length and from the bytes actually received.
2. The SHA-256 matches. The digest came from the control plane over TLS, so a compromised CDN cannot get past this.
3. A detached Ed25519 signature verifies against a key compiled into the binary. The signing key is on no server, so a compromised control plane cannot get past this either.

A failure at any step returns an error. It never returns partial bytes with a warning attached.

A build compiled without release keys configured falls back to checksum verification only

• that is what every build before signing existed did, and it is a supported self-hosting case. A build compiled with keys refuses any update that is not validly signed, and nothing at runtime can relax that.

The agent never chooses its own version

The control plane answers "which build should this host install", per host, from the release catalogue. The agent contributes nothing to that decision except the version it reports running: its identity, platform, architecture and channel all come from its own database row.

That asymmetry is the point. An agent that could name its own channel would put itself in the narrowest ring and pull untested builds; one that could name its own platform would be handed a binary for the wrong operating system.

The rules, in the order they apply

1. Status. Only active and testing builds are offerable. draft was never published, paused is a rollout somebody stopped, revoked is a build known to be bad, superseded has been replaced.
2. Channel. A release is visible to an agent whose ring is at least as narrow as the release's. A testing release is additionally confined to the pre-production rings whatever its channel says.
3. Platform and architecture must match exactly.
4. An emergency rollback wins. A release flagged as one is the only way an agent ever installs an older version than it is running, and it is chosen ahead of any newer build.
5. Newest first, then eligibility. Remaining candidates are considered newest-version-first, and the first one this agent is eligible for wins. That is what makes a staged rollout behave: while a new build sits at 5%, an agent outside that 5% falls through to the previous build at 100% rather than being stranded further back.
6. No downgrades and no sideways moves, outside rule 4.
7. A minimum upgradable version lets a release refuse a jump from too far back, for a build that needs an intermediate migration.

Release channels

Four rings, narrowest first:

An agent sees a release whose channel is at least as wide as its own. Promoting a build from canary to stable therefore never takes it away from the canary hosts already running it.

Set the channel organization-wide under Settings > Organization > General. Override it for one agent under Manage > Agents > Manage > Settings > Update channel, which is what you want for canarying a build on a single host rather than a fraction of the fleet.

Staged rollout

A release carries a rollout percentage. Whether a given agent is inside it is derived by hashing the agent and the release together, so:

• The answer is stable. The same agent asks twice a day and gets the same answer, with nothing persisted.
• Raising the stage only ever adds agents. 0.5% → 5% → 25% → 100% is a progression, not a reshuffle.
• The pair is hashed, not the agent alone, so the same few hosts are not the canary for every build the product ever ships.

Pausing a release stops it being offered to anyone, reversibly. Revoking one stops it permanently.

Pinning a version

Turn Automatic updates off on an agent under Manage > Agents. The agent then stays on whatever build it has, and its settings page shows the exact command to update it by hand:

aethercert-update-service update --agent
aethercert-update-service update --connector

Run it elevated on the host. It downloads and applies whatever build the control plane currently has for that component, skipping the auto-update gate but not the verification. It does not require the Update Service itself to be installed or running.

A host with no Update Service

--no-update-service at install time, or a container running aethercert-agent run directly, leaves the host with nothing that can update it. That is a supported choice - rebuild the image, or run the manual command above - but it is a choice, not an accident: such a host stays on its build until somebody acts.

What is recorded

A host reports the outcome of each update cycle. The event log records a rollback, a failure, and a repeated failure across hosts - which is the signal that a release itself is bad rather than one machine being unlucky. Those are also pushed to any monitoring integration you have configured, and counted in aethercert_agent_updates_total on the monitoring API.