Updates and lifecycle

Self-update

The agent updates itself over the WebSocket. On each heartbeat the server compares the agent's version to the current release. If they differ, it sends an update nudge down the open connection, and the agent checks, downloads, verifies, and swaps its own binary, then restarts its own service. Fleet rollout is a matter of minutes.

Update verification is strict:

1. The release ships a signed manifest (version, the SHA-256 of every asset, and an issue timestamp). The agent verifies the manifest signature and takes the hashes from it; nothing unsigned is trusted.
2. The ed25519 signature over the binary itself must also verify against the publisher key baked into the running agent. An unsigned or tampered binary is refused.
3. Anti-downgrade and anti-replay: the agent refuses a release that is not newer than what it runs, and refuses a manifest older than the newest one it has seen, so an attacker who can write to the release channel still cannot roll the fleet back to an old signed build.

All of this fails closed: no manifest, or a broken one, means no update. The download itself is streamed to a temporary file next to the binary and hashed on the way, so a release never sits in memory in full and a download that fails any check leaves nothing behind.

There is a fallback 24-hour poll as well, so an agent that missed the nudge still catches up. A restart of the service is enough to pull the latest release, no manual step needed.

Before restarting into the new version, the agent announces the update over the live connection (an agent_update event with the old and new versions). The server therefore knows the coming reconnect is an update, holds down-detection over the restart window, and the host timeline shows a version hop rather than a bare disconnect.

Manual update

wakora --update

Downloads, verifies, and applies the latest release, then restarts the service. Subject to the same signature and anti-downgrade checks.

Version pinning

A host can be pinned to an exact release, which regulated fleets often require. Set the pin in the console per host, or locally:

wakora --set agent.pin=r345

A pinned agent converges to exactly that version, upward or downward: an explicit pin is the one case where the anti-downgrade rule steps aside (the downgraded build is still signature-verified like any other). There is a pin floor, the oldest release that can still be pinned (r340 today; the signed manifest of the channel names it), and the release channel archives every release from that floor up to the current one, so pinning to any of them works even after newer ones shipped. A pin below the floor is refused rather than half-applied, and the floor only ever moves up, with the releases below it leaving the archive. The console pin and the local pin are kept in sync in both directions, and the effective pin is visible in the host's heartbeat. Remove the pin and the agent rejoins the normal auto-update flow.

On top of pinning, the console can stage rollouts across the fleet in rings (canary first, then waves, with soak gates and one-click rollback); see Fleet rollout.

Restart is init-aware

On self-update the agent relaunches its own service correctly for the init system it runs under: systemd (Restart=always) and OpenRC (supervised) just need a clean exit, while sysvinit has no supervisor, so there the agent spawns a detached relauncher before exiting so it comes back. On Windows the restart is graceful (a detached helper waits for the service to stop, then starts it), so an update does not log a spurious "service terminated unexpectedly".

Never restart your services

This is a hard rule. The agent never restarts or reloads a client or third-party service on its own (php-fpm, nginx, databases, IIS app pools). Self-restart applies only to the agent's own service, for its own update.

When a change needs a service reload to take effect (enabling the APM extension, a kernel module, a sysctl), the agent stages it: it writes the change, marks it pending, and reports an "action required" event with the exact command and its impact (a graceful reload is zero downtime, a full restart is labelled "brief downtime"). A human runs that command, copied from the console, in a maintenance moment or with the next deploy. There is deliberately no remote-execute button anywhere: copy and paste by a human is the only channel, so nothing and nobody can reload your services through Wakora. The agent then detects that the reload happened and flips the capability to active. Until then the zero-touch baseline (eBPF or logs) covers the gap, and the console shows the capability as "staged, awaiting activation" rather than as if it were live.

This is a reputation guarantee for regulated clients: Wakora must never cause an outage.