# Recover from backups

> Open local version backups, restore previous versions in the workspace, and find recovered copies in your Hyperclay Local folders.

Source: https://hyperclaylocal.com/docs/guide/backups/

Every time a document saves in Hyperclay Local, the server writes a timestamped backup copy on your computer inside that folder's `.hyperclay/versions/` directory. You can restore previous versions from the [workspace window](https://hyperclaylocal.com/docs/guide/workspace/) or open the backups folder directly in Finder or your file manager.

## Open the backups folder on disk

1. Click the Hyperclay Local tray icon to open the [popover](https://hyperclaylocal.com/docs/popover/).
2. Click the `⋯` button on a folder card (or open the folder's submenu in the system tray menu).
3. Click **Backups**.

Hyperclay Local creates `<folder>/.hyperclay/versions/` if it does not exist yet and opens it in your system file manager.

Inside `.hyperclay/versions/`, each document has its own subfolder matching its relative path without the `.html` extension:

```bash
<folder>/.hyperclay/versions/<document-path>/<timestamp>.html
```

Each backup filename uses your local wall-clock time plus your UTC offset (`YYYY-MM-DD-HH-MM-SS-mmm±ZZZZ`, such as `2026-11-01-01-30-00-431-0400`, with `-001` through `-999` appended if multiple saves happen in the same millisecond). You can open any backup file to inspect it or copy it back over your working document.

Because `.hyperclay/` starts with a dot, local backups stay on your computer and are never uploaded by sync (see [What syncs](https://hyperclaylocal.com/docs/what-syncs/) and [Files the app writes](https://hyperclaylocal.com/docs/files/)).

## Restore a version in the workspace

You can browse and restore versions of a document from the [workspace window](https://hyperclaylocal.com/docs/guide/workspace/) (see [Version history routes](https://hyperclaylocal.com/docs/version-history/)).

When you restore a version in the workspace, Hyperclay Local writes a safety backup of the current file on disk before replacing it. A restore is refused if:

- The current file exists on disk but cannot be read, because no safety backup can be written (`current file cannot be read, so no safety backup is possible`).
- The document changed on disk since it was loaded (`document changed since it was loaded`).
- The requested version file does not exist (`version not found`), exceeds the size limit (`version is too large to restore`), or is not a complete HTML document (`version is not a complete HTML document`).

## How long backups are kept

Hyperclay Local prunes `.hyperclay/versions/` automatically using two rules per document:

- Every backup newer than **60 days** is kept.
- The **newest 20 backups** for each document are always kept, even if they are older than 60 days.

Any backup that is both older than 60 days and beyond the newest 20 for that document is removed during pruning.

## Recovered copies

If another program on your computer replaces or removes a document on disk while that document has unsaved live edits open in Hyperclay Local, the file on disk takes precedence and Hyperclay Local saves the unsaved live edits as a recovered copy:

```bash
<folder>/.hyperclay/recovered/<document-path>/recovered-<timestamp>.html
```

Recovered copies appear alongside regular backups in version history labeled `recovered` and can be restored the same way. Unlike `.hyperclay/versions/`, the `.hyperclay/recovered/` folder is never pruned, so recovered copies remain on disk until you delete them.

## Trashed files

When a document is deleted from the workspace or deleted on hyperclay.com and synced to your computer, it is moved to `<folder>/.trash/<relative-path>` rather than deleted immediately (see [Conflicts and deletions](https://hyperclaylocal.com/docs/guide/conflicts/)). You can restore trashed files from the workspace Trash view or move them back from `.trash/` in your file manager.