# Files the app writes

> Where Hyperclay Local stores version backups, compiled stylesheets, uploads, sync state, settings, and logs on disk.

Source: https://hyperclaylocal.com/docs/files/

Hyperclay Local keeps document artifacts inside each served folder and stores app settings, sync metadata, and logs in your operating system's application data and log directories.

## Inside each served folder

Inside a served personal or team folder, Hyperclay Local writes the following paths:

```text
.hyperclay/versions/<name>/<timestamp>.html             version history backups, never served, never synced
.hyperclay/recovered/<name>/recovered-<timestamp>.html  recovered live edits when a file is replaced on disk
.hyperclay/conflicts/<base>.remote-<etag8><ext>         parked remote copy for an unresolved sync conflict
.hyperclay/conflicts/conflicts.json                     open conflict records
.hyperclay/page-state/                                  page editor merge state (one record per file name)
.hyperclay/api/<name>.json                              data API sidecar cache
.hyperclay/guard/<name>.json                            data-clobber guard state
.hyperclay/guard/<name>.recover.html                    whole-file recovery copy
tailwindcss/<name>.css                                  compiled Tailwind stylesheets
uploads/assets-<name>/                                  files stored by POST /_/upload
.trash/                                                 files deleted on hyperclay.com or moved to Trash
```

- **Version backups and recovered copies**: `.hyperclay/versions/` (which replaced the older `sites-versions/` path) keeps backups newer than 60 days plus the newest 20 per document. `.hyperclay/recovered/` stores unsaved live edits when an external program overwrites or removes a document and is never pruned (see [Recover from backups](https://hyperclaylocal.com/docs/guide/backups/)).
- **Uploads**: Attachments uploaded from a document are saved under `uploads/assets-<name>/` and linked via `/_/uploads/`, matching the layout on hyperclay.com (see [Metadata and uploads](https://hyperclaylocal.com/docs/metadata-and-uploads/)).
- **Ignored by sync**: Every dot-prefixed path (`.hyperclay/`, `.trash/`, `.DS_Store`), `tailwindcss/`, `sites-versions/`, and `node_modules/` is skipped by sync, while `uploads/` syncs with hyperclay.com (see [What syncs](https://hyperclaylocal.com/docs/what-syncs/)).

## In the app data directory

Outside your served folders, Hyperclay Local writes to Electron's `userData` directory (`~/Library/Application Support/Hyperclay Local` on macOS, `%APPDATA%\Hyperclay Local` on Windows, and `$XDG_CONFIG_HOME/Hyperclay Local` or `~/.config/Hyperclay Local` on Linux):

```text
settings.json            settingsVersion (2), deviceId, actor, serverEnabled,
                         syncEnabled, roots (path and port per folder),
                         syncSessions, seenTeamIds, serverUrl, apiKey (encrypted),
                         autoStartEnabled, aiEdit
settings.v1.json         backup of pre-v2 single-folder settings kept after migration
served-roots.json        pid, updatedAt, and running roots [{ path, port }] for CLI discovery
sync-meta/<12 hex>/      node-map.json, sync-state.json, tombstones.json
update-skip              skipped AppImage version after a failed update rollback
update-seen              highest update feed version seen
update-healthy           health marker written after an update starts cleanly
update-request.json      in-progress update handoff state
```

- **`settings.json`**: Written atomically via a temporary file, `fsync`, and rename so a crash or disk error never corrupts your existing settings file (see [Settings and profile](https://hyperclaylocal.com/docs/settings/)).
- **`served-roots.json`**: Lists every folder currently in the `running` state along with its real path and port, and is removed when the app quits (see [Programs and helpers](https://hyperclaylocal.com/docs/programs/)).

## Logs

Logs are written to `app.getPath('logs')`, which is `~/Library/Logs/Hyperclay Local` on macOS and a `logs` directory inside `userData` on Windows and Linux. Hyperclay Local writes one file per day and retains logs for 30 days:

```text
sync/2026-08-27.log      [timestamp] [LEVEL] [context] message | {json}
errors/2026-08-27.log
```

You can open both folders from the popover under **Options** > **View Sync Logs** and **Options** > **View Error Logs**. Paths recorded in the sync log have the synced folder prefix stripped.

## Development builds

A development build (`npm run dev`) appends `-dev` to the `userData` directory name (for example, `~/Library/Application Support/Hyperclay Local-dev`), so development state never collides with your installed app's settings or sync metadata.