Skip to main content

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. SHA-256 of the downloaded binary must match.
  2. The ed25519 signature over the bytes must verify against the publisher key baked into the running agent. An unsigned or tampered binary is refused.
  3. Anti-downgrade: the agent refuses to apply a release that is not newer than what it runs.

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.

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​

Planned

Default auto-update is on, in canary waves. A tenant being able to pin a version (common in regulated finance, where a pinned agent skips auto-update until unpinned) is planned as a server-driven control. Today the fleet auto-updates.

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 triggers it, from the console button, a maintenance window, or the next deploy. 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.