How Versioning Works
Every write to a file in your cloud workspace captures what was there a moment before. If an edit, an agent or a script ruins a file, the previous content is in the file's history, one click or one command away.
What triggers a version
| What happens | What gets captured |
|---|---|
| An agent, the API, the CLI or a shell command changes a file | The content before that write |
| A run creates a new file | A create marker, so undoing the run deletes the file again |
| You edit a file in the editor | The content before your editing burst, at most one version per burst (about a ten minute window) |
| You take a checkpoint | A full snapshot of the content as it is right now |
| You restore an older version | The content you are replacing, so the restore is itself undoable |
Monofile coalesces your own saves on purpose. The editor auto-saves while you type, and a version per keystroke pause would bury the versions that matter. The first save after an agent touched the file always captures a version, so the hand-off state stays in the history.
What does not create a version
A write that changes nothing. If the incoming content is identical to the stored content, Monofile skips the write, and the file's modified time does not move.
Renaming or moving a file. Only content changes create versions, and a rename keeps the same file, its history and its links.
Media files. Images and video live in object storage, so they have no version history. Replacing one replaces it.
Local files. Version history is a cloud workspace feature. Files in a browser-only local workspace live in that browser, and a plain local folder in the desktop app is your disk.
It applies to every text file type
Versioning sits underneath the filesystem, so a .py file, a .json config, an Excalidraw .draw, a .canvas board and an .html page all get versions the same way. See Supported File Types for the full list.
How long versions last
Versions do not expire on a clock. Monofile trims automatic versions to the newest 20 per file, so a heavily edited file keeps only its recent past. Three kinds are exempt from trimming and stay until the file is deleted:
Checkpoints you named yourself.
Create markers, which record that a run brought the file into existence.
Checkpoint snapshots taken as part of a folder checkpoint.
Browsing a file's history
In the web app, open a file and pick History from the tab actions menu, or run Version history… from the command palette. The panel lists versions newest first, grouped by the run that produced them and labelled with that run's summary, a checkpoint name, "Your edits" or "Before revert". Select one to preview it, compare it against the file as it is now, and restore it.
From the terminal, the CLI lists and restores versions directly. From the API, the same history is three tools: list_versions for the list, read_version for the content of one entry, and revert_file to restore it. Reading needs the files:read scope, restoring needs files:write.
monofile versions /Projects/report.md
monofile revert /Projects/report.md --to ver_abc123curl -X POST "https://www.monofile.ai/api/tools/list_versions" \
-H "Authorization: Bearer $MONOFILE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path": "/Projects/report.md", "limit": 20}'Next steps
CheckpointsNamed snapshots of a file or a folder subtree you can return to.
ChangesetsRuns grouped into one reviewable, revertable unit.
Reverting SafelyRestore a file or undo a whole run, and what happens on a conflict.
Reviewing ChangesThe diff view and the changeset card: keep or revert everything an agent touched.
Files and FoldersPaths, the file tree, renaming, moving, deleting and restoring.