Hyperclay Local
  1. Hyperclay Local
  2. Docs
  3. Reference
  4. Files the app writes

Files the app writes

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

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).
  • 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).
  • 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).

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).
  • 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).

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.