Plans and change requests
Seeing beforehand what will change, and letting an agent ask for changes without being able to make them on its own.
The plan: what would happen
Every operation that changes something has its own plan: the platform runs all the checks of the real operation (role, quota, names, networks, firewall rules) and answers with what would happen, without changing anything:
- what would be created, changed, destroyed or left as it is (servers, disks, addresses, rules, networks, clusters, node pools);
- quota usage after the operation;
- whether it can be undone;
- any notes (for example, for reverse DNS, what has to point where).
If the operation would be refused, the plan already says so: no surprises afterwards.
In the panel you always see the plan, before every change, in the Before it happens window. To confirm: Do it; for anything that destroys, first type the name again (Type … to confirm).
With the API and the MCP you ask for it yourself, by adding "dry_run": true. Anyone who can run the operation can ask for its plan.
Change requests: an agent that can only ask
An API key created with Requires my approval for every change changes nothing on its own. Every change asked for with that key, from the API or the MCP, becomes a change request, with:
- exactly what was asked for (Exactly what will be run);
- the plan;
- the reason, in the agent's words (Why, in the words of the agent), if it wrote one;
- the key that asked for it.
Anything the platform would refuse anyway does not become a request: it goes straight back to the agent as an error.
Who decides
- A person in the project with Can edit, Can manage or the owner, from the panel;
- or a program with another key that does not require approval (never the same key that asked).
Those who can decide receive an email as soon as the request is created.
Where to decide
In the panel, on the Cloud page:
- next to the Cloud menu item, a number tells you how many requests are waiting;
- in Normal and Nerd mode, at the top of the page, the pending requests; the Requests section has all of them (Change requests), plus the log of those already decided (Log);
- in AI mode, in the Right now column.
Open the request, read it, and press Approve or Reject. For anything that destroys, to approve you type the name of what will go away.
On a yes the operation starts immediately, with the data held by the platform (not with data sent again by the agent) and within the limits of the key that asked. If the key has been revoked in the meantime, nothing runs.
How long it waits
A request waits 24 hours, then expires (Expired): the agent has to ask again.
| State | Meaning |
|---|---|
Waiting for you (pending) |
Waiting for a decision |
Approved, running (approved) |
Approved, running |
Done (done) |
Carried out |
Failed (failed) |
Approved but did not succeed: the reason is in the result |
Rejected (rejected) |
Rejected |
Expired (expired) |
Expired |
Everything stays in the project's log: who asked, who decided, from where, and how it went.
For developers
A plan: add "dry_run": true to the data of any method or tool that writes. The response:
{
"dry_run": true,
"preview": { "title": "Create server web-1", "summary": "s-2-4 · ubuntu-24.04, 40 GB disk, …", "danger": false, "confirm_text": null },
"plan": {
"changes": [ { "op": "create", "kind": "server", "name": "web-1" }, … ],
"usage_after": { … },
"reversible": true,
"notes": [ … ]
}
}
preview is the summary for a person; confirm_text, if present, is the name to type to confirm. In plan.changes, op is create, update, delete or keep; kind says what (server, disk, public_ip, firewall_rule, power, network, quota, …).
With a key that requires approval, a write answers:
{
"change_request": { "id": "…", "status": "pending", "tool": "cloud_create_server", "preview": { … }, "plan": { … }, "reason": "…", "expires_at": "…" },
"message": "Nothing was changed yet: this key needs approval. …"
}
Add reason (one sentence) to the data: whoever has to approve will see it.
| What | Method | MCP tool | Role |
|---|---|---|---|
List (status: pending or all) |
Cloud/getChangeRequestList |
cloud_get_change_request_list |
viewer |
| One request, with outcome and result | Cloud/getChangeRequest (change_request_id) |
cloud_get_change_request |
viewer |
| Decide | Cloud/decideChangeRequest (change_request_id, approve: true/false, confirm_text for anything that destroys) |
— | operator, with a key that does not require approval |
Errors when deciding: CHANGE_NOT_PENDING (already decided), CHANGE_EXPIRED, CHANGE_CONFIRM_TEXT (wrong name typed), CHANGE_SELF_APPROVAL (a key that requires approval cannot decide), CHANGE_REQUESTER_GONE (the key that asked is no longer valid).