Fleet policies and drift

A fleet policy is a named Agent Warden policy that a team applies to agents on many sites. It has versions: each change makes a new version, and earlier versions never change.

Create a fleet policy#

1. On a site you trust, set up an agent's policy the way you want it in Agent Warden → Agents, then export it with WP-CLI: wp agentwarden policy export <agent-id> --file=policy.json --user=<admin>.
2. In the hub, open Fleet policies, choose the team, enter a name, paste the exported policy, and select Create policy.
3. To change it later, paste the new document under the policy and select Save as a new version.

The hub checks that the document is a policy it can send. Each site checks it fully when it applies it.

Apply it to an agent#

1. Open a site from Sites.
2. Next to the agent, choose the fleet policy and select Apply.

The site applies the policy on its next report, within five minutes, through the same validation, plan checks, and conflict rules as its own admin screen. If the site refuses, for example because the policy uses a feature the site's plan does not include, the hub shows Refused by the site with the reason, and the agent keeps its policy.

Drift#

The hub shows each managed agent as:

• In sync: the agent's policy is the fleet policy the site applied.
• Waiting for the site: a new assignment or version is on its way.
• Changed on the site: someone edited the agent's policy on the site after the fleet policy was applied. The site shows the agent as hub-managed and warns before a local edit, but it does not stop one.
• Refused by the site: the site did not save the policy.

For a drifted agent, Re-apply sends the fleet policy again, and Detach stops managing the agent and keeps whatever policy it has now.