Myrax docs

Checkpoints and rewind

Before the first edit of a batch the workspace is committed. That commit is the difference between a wrong turn and a lost afternoon.

An agent that writes files can also write the wrong files. A checkpoint is the cheap insurance: a git commit taken before the first edit of a batch, so there is always a place to go back to that is not “retype it”.

When a checkpoint is taken

Before the builder touches anything, once per run. The workspace is mapped first (branch, dirty state, detected stack, sensitive paths), then committed with a message naming the project. The reference is shown in the build log ascheckpoint: a3e8aa9 and stored with the project record.

For a new project the workspace is an empty folder that becomes a repository, and the checkpoint is the empty baseline. For an existing repo it is a commit on top of your working state, which is why a dirty tree matters: uncommitted changes get folded into the checkpoint.

Going back

myrax-connector rewind <dir> <ref>

This rewinds the workspace to a named ref. Used with the checkpoint from the build log, it undoes the whole edit batch. It is a real git operation on your folder, so anything you wrote by hand after the checkpoint goes with it. Read the ref before running it.

Two things that are not checkpoints

  • Shield snapshots. Those freeze a build that already passed so it can be restored later. They are a shipping convenience, not an undo for a running edit.
  • The uploaded artifact. That is a zip of a successful build. It is a delivery format, not a branch you can edit.

The diff you get back

After each build the connector measures the workspace against the checkpoint and reports a file list with added and removed line counts. The patch text is capped and lines that look like key=, secret=, password= or token= are replaced with a redaction marker before anything is sent. A failed build reports its diff too: seeing what it touched is how you decide whether to repair or rewind.

A note on workspace location

Workspaces live under ~/.myrax/workspaces/<project-id> by default, and the Connector refuses to work inside a folder that sits inside another git repository it did not create. That rule exists because the first version defaulted to a folder next to the product's own checkout, and the first checkpoint committed the product's repository under a “checkpoint before editing” message. Set MYRAX_WORKSPACE if you want them somewhere else.

The build lifecycle that produces these checkpoints is described in How a build works.