# Agent upgrades

> Upgrade falak-agent after a Falak update — per server or all at once from the UI, API or artisan — with the atomic swap, batching and manual rollback.

Source: https://falak.sh/docs/servers/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:

  ```bash
  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

  
    **Servers** → **Update** next to *update available* in the server's row, or open the server and click **Update agent** (header or banner).
  
  
    **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.
  
  
    ```bash
    curl -X POST https://falak.example.com/api/v1/servers/01k…/agent/upgrade \
      -H "Authorization: Bearer $FALAK_TOKEN" -H "Accept: application/json"
    ```

    ```json title="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

```bash title="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