Agent upgrades

Updating the control plane (falak-ctl update) does not touch your servers. Each server keeps its falak-agent until you upgrade it. The new control plane image ships the matching agent build and tells you which servers are behind.

See what is outdated

• Servers list: the Agent column shows each version and update available.

• After an update, falak-ctl update prints how many agents are older.

• On the control plane host:

  falak-ctl artisan falak:agents              # shipped build and number of outdated agents
  falak-ctl artisan falak:agents --outdated --count

An agent is outdated when its binary checksum differs from the shipped build (development builds can share version strings), except that an agent newer than the shipped release never is.

Upgrade

One server

Servers → Update next to update available in the server’s row, or open the server and click Update agent (header or banner).

Several servers

Servers → tick the servers → Update selected (n), or Update all agents (n) for every outdated online agent. Falak upgrades 2 servers at a time (FALAK_AGENT_UPGRADE_BATCH_SIZE) and stops at the first failure, cancelling the rest.

API

curl -X POST https://falak.example.com/api/v1/servers/01k…/agent/upgrade \
  -H "Authorization: Bearer $FALAK_TOKEN" -H "Accept: application/json"

202 Accepted

{"data": {"id": "01k…", "server_id": "01k…", "status": "running", "from_version": "v0.3.0", "to_version": "v0.4.0",
          "rollout_id": null, "error": null, "requested_at": "2026-09-28T10:00:00+00:00", "finished_at": null}}

409 when there is no agent, it is offline, there is no verifiable build for its architecture, or it already runs it.

Upgrading needs fleet.agents.manage (owners and admins).

What happens on the server

1. The agent downloads the build from your panel (/install/agent/linux-<arch>) and verifies its SHA-256.
2. It runs falak-agent.new version to make sure the binary works on this machine (a wrong-architecture or truncated build never replaces a working agent).
3. It swaps /usr/local/bin/falak-agent atomically; the previous binary stays as /usr/local/bin/falak-agent.prev.
4. It restarts (supervised programs restart with it).
5. Its next heartbeat reports the new version and binary checksum; the upgrade is succeeded.

The upgrade fails if the agent has not come back with the new build within 600 seconds (FALAK_AGENT_UPGRADE_TIMEOUT, minimum 60). Failures raise the Agent upgrade failed alert (fleet.agent_upgrade_failed).

Roll back by hand

On the server

sudo mv /usr/local/bin/falak-agent.prev /usr/local/bin/falak-agent
sudo systemctl restart falak-agent

Compatibility

Agents report the features they support. The control plane strips new optional payload fields for agents that do not support them yet, so an older agent keeps working with a newer control plane until you upgrade it. After an upgrade, Falak re-applies Caddy and telemetry configuration so the agent gets the new fields.

Limits

“Update all agents” was verified by hand on a real fleet of three servers (0.2.x). The automated suite covers single upgrades and the batching logic.

Next steps

Upgrade the control planefalak-ctl update and automatic rollback.

The agentFiles, flags and logs.