Files

T

justinandClaude Opus 5 fe7b220ab9 feat(checkpoints): record agent and intent in the checkpoint name

Zerto's tagged checkpoint insert takes exactly one field. The 10.x
swagger model VpgInsertTagCheckpointDataApi has a single property,
checkpointName, and the 9.0 API reference lists CheckpointName as the
only request value. There is no description field, so who the agent is
and what it is about to do have to live inside the name.

Old name:
  ai:claude:chg-412:20260921T170829Z

New name:
  ai:claude | edit /home/justin/app-config.yaml | vm=jp-ubuntu |
  change=chg-412 | 20260921T170829Z

zerto_create_tagged_checkpoint and zerto_guard_before_mutate take a new
action argument: free text saying what the agent is about to do. The VM
name is filled in from the find result. An operator reading the journal
in the Zerto UI can now see which agent inserted a checkpoint and why,
without the agent transcript.

Field text is sanitised so the name stays one readable line: control
characters and runs of whitespace collapse to single spaces, ';' becomes
',' because Zerto appends "; Used for File Level Restore" to its own
tags, and '|' becomes '/' because ' | ' is our field separator. Capped
at TAG_MAX_LEN (250).

Measured against ZVM 10.x while picking the format:

- names of at least 400 chars are accepted, and spaces, slashes,
  parentheses, '=' and '|' all survive the round trip
- tagged checkpoint inserts fired back to back at one VPG are silently
  dropped. The POST returns 200 and queues a task, but only the first
  checkpoint appears. tag_vpgs already inserts then waits per VPG, so
  it is correct; added a comment so nobody turns that loop into an
  asyncio.gather().

Verified end to end: guard inserted cp 1197 on VPG jp-ubuntu, the name
read back byte-identical from the journal, and FLR from that checkpoint
returned the 158 byte pre-mutation file.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_016yVfC5nvZowoLFnEGWhLGn

2026-09-21 13:09:08 -04:00

2.8 KiB

Raw Blame History

name, description

name	description
zerto-rewind	Before changing a VM, find its Zerto VPGs and insert a tagged checkpoint. Recover files from that tag with FLR after a human confirms. Use whenever an agent will mutate a guest that might be protected by Zerto.

Zerto rewind

Zerto already journals the VM. This skill makes the agent use that journal. Git does not have the guest file. Official ZVM MCP does not insert tagged checkpoints.

You talk to one MCP: zerto_rewind_mcp. Do not also require official ZVM MCP.

Loop (mandatory)

Before every guest-mutating tool call:

Take the hostname / VM name / Zerto vmIdentifier from the tool args.
Call zerto_guard_before_mutate with change_id and action (or zerto_find_protection then zerto_create_tagged_checkpoint).
If ok is not true: stop. Do not mutate.
Then run the mutating call.

Reads skip the guard.

Unlisted MCP tools pass through. If you are about to change a protected VM with a tool that is not in the catalog, call zerto_add_mutating_tool (server, tool, vm_arg) and then guard.

find_protection outcomes

outcome	what you do
none	Unprotected or unknown. Refuse the change. Say Zerto cannot rewind this.
ambiguous	Two or more VMs matched. Ask for a `vmIdentifier`. Do not guess.
ok, no taggable VPG	Syncing or not Protecting. Refuse. A resync deletes checkpoints.
ok, taggable VPGs	Tag every protecting VPG with the same tag. Wait until listed (the tool blocks).

A VM can be in up to three VPGs (local backup + remote DR is common). Tag all of them.

Recover

Human must confirm. Pass confirmed=true only after they say yes.

Bad config / dropped file: zerto_recover_file from that tag.
Inspect a whole VM: zerto_offsite_clone or zerto_start_failover_test.
Never Failover Live. Never Move. Those are DR, not rewind.

Facts that bite

A tagged checkpoint is crash-consistent, not app-quiesced.
Tagged checkpoints are not supported when the protected site is Azure or AWS. Talk to the vSphere protected ZVM.
10.9 FLR Operator RBAC fails; Administrator is the documented workaround.
FLR cannot run during clone, test, live failover, or EJC.
Linux FLR: files >1.5GB are a bad idea; some characters in names are refused.

Tag

The checkpoint name is the only field the Zerto API takes, so it carries the whole story:

ai:<agent> | <action> | vm=<vm> | change=<change-id> | <utc>
ai:claude | edit /etc/nginx/nginx.conf | vm=web01 | change=chg-412 | 20260921T150405Z

Always pass action: a plain description of the change you are about to make. An operator scrolling the journal in the Zerto UI should be able to tell which agent inserted the checkpoint and why, without reading your transcript.

Same string on every VPG for that call.

2.8 KiB Raw Blame History