# How it works

> How Hyperclay Local serves folders, saves documents, syncs with hyperclay.com, runs AI edits, and enforces local security.

Source: https://hyperclaylocal.com/docs/how-it-works/

Hyperclay Local combines a local HTTP server per folder, a native workspace window, a two-way sync engine for hyperclay.com, and local AI editing in one desktop app. Every document is a standard HTML file built with [ClayJS](https://clayjs.com/docs/) that sits in a normal folder on your disk.

## Local server integration

Hyperclay Local runs an embedded Express.js server bound to `127.0.0.1` for each served folder (`localhost:4321` for your personal folder and a dedicated port for each team folder; see [Folders and ports](https://hyperclaylocal.com/docs/folders-and-ports/)):

- **Static file serving**: Serves your documents with extensionless HTML support and every other file in the folder.
- **Self-saving endpoint**: Accepts `POST /_/save` requests with `Document-URL` identifying the target file (see [Saving and stale-write protection](https://hyperclaylocal.com/docs/saving/)).
- **Workspace and directory listings**: A top-level `GET /` on a folder's port redirects to [the workspace window](https://hyperclaylocal.com/docs/guide/workspace/) with a one-time 60-second ticket and a per-port session cookie, and falls back to a directory listing when the workspace cannot start or for `HEAD` and framed requests.
- **Shared write gate**: Browser saves, the [Data API](https://hyperclaylocal.com/docs/data-api/), version restores, uploads, Tailwind compilation, and sync all coordinate through one shared/exclusive write gate so concurrent operations never clobber each other.
- **Request protections**: Blocks path traversal, validates filenames, and checks `Host`, `Origin`, and Fetch Metadata headers (see [Rejected requests](https://hyperclaylocal.com/docs/rejected/)).

## File management

- **Folder selection**: Uses the native OS folder picker dialog (**Choose folder…** on first run, **Options** > **Change Personal Folder…**, and **Set up →** for team folders). Served folders must sit inside your home folder and cannot overlap another served folder.
- **Path security**: Serves only files inside the selected folder and refuses symlinks created while the server is running.
- **File types**: Serves all file types with special handling for `.html` and `.htmlclay` documents, attaches `nosniff` headers, and serves web-page types inside `uploads/` as downloads so attachments cannot run scripts on the folder's origin (see [Metadata and uploads](https://hyperclaylocal.com/docs/metadata-and-uploads/)).
- **Hidden files**: Hides dotfiles, dot-directories (such as `.hyperclay/` and `.trash/`), and system files (`Thumbs.db`, `desktop.ini`, `.DS_Store`).

## Workspace and browser integration

- **Workspace window**: Opens from **Open workspace** in the tray or popover, or by visiting `http://localhost:<port>/` in your browser, showing the folder tree, search, and framed documents (see [The workspace window](https://hyperclaylocal.com/docs/guide/workspace/)).
- **Open in Browser**: Each folder card's menu includes **Open in Browser** and **Copy Address** to open or copy `http://localhost:<port>`.
- **External links**: Opens external links in your default system browser.

## Cloud sync

When you connect your account in **Options** > **Sync Key…**, Hyperclay Local syncs your personal folder and team folders with hyperclay.com (see [Sync with hyperclay.com](https://hyperclaylocal.com/docs/guide/sync/)):

- **API key authentication**: Stores one sync key (`hcsk_...`) for the whole app, encrypted on disk with Electron's `safeStorage`.
- **Two-way sync**: Compares a 16-character SHA-256 checksum of each local file and the server's ETag against the recorded baseline to upload local changes and download remote changes (see [How sync decides](https://hyperclaylocal.com/docs/how-sync-decides/)).
- **Auto-resume**: Restarts sync automatically on app launch when sync was previously enabled, and starts in offline mode if hyperclay.com is unreachable.
- **Sync queue and conflict handling**: Queues changes with automatic retries and keeps both copies when a file changes on both sides, parking the server copy in `.hyperclay/conflicts/` until you choose **Keep mine**, **Keep theirs**, or **Keep both** in **Notices** (see [Conflicts and deletions](https://hyperclaylocal.com/docs/guide/conflicts/)).

## AI editing

Select text in any editable document that loads [ClayJS](https://clayjs.com/docs/), press `⌘J` (`Ctrl+J` on Windows and Linux) or click the **AI** chip at the end of the selection, type your request in **Describe the change**, and press **Send** (see [AI editing](https://hyperclaylocal.com/docs/guide/ai-editing/)). An agent on your computer rewrites the block around the selection and previews the change in place. Click **Keep** to save it, **Revert** to put the original back, or **Stop** to cancel. Nothing is saved while the rewrite waits for your choice.

- **On by default**: Turn it off or on with **AI Editing** in the **Options** menu or **Disable AI Editing** and **Enable AI Editing** in the tray menu.
- **Uses your local agent CLIs**: Runs the agent CLIs you already have installed and signed in on your machine without an API key: Claude Code by default (`claude`), `@fable` for Fable, or `@codex` for the Codex CLI. Start your prompt with the `@` name to pick one. If the default Claude command is missing, AI editing falls back to Codex. An explicit `@claude` or `@fable` request never switches agents.
- **Runs with no tools**: Built-in agents cannot read arbitrary files, run shell commands, or browse the web. The agent receives the block's HTML, where the selection sits in the document, the selected text, your request, any file you name with `@name.ext` (which must sit inside the served folder, cannot be hidden, and is capped at 8 files, 256 KB each, and 1 MB in total), and with `@page` the whole saved document. The agent CLI sends that prompt to its model provider.
- **Content-only replies**: A reply that adds a `<script>` tag, an inline event handler, or a `javascript:` URL is refused.
- **`@agy` is refused**: `@agy` is not supported because agy can read files without asking and has no switch to disable that behavior.
- **One edit at a time**: One AI edit runs per document at a time.
- **Custom agents**: Add `"aiEdit": { "engines": { "name": ["command", "arg", "{prompt}"] } }` to `settings.json` in the app data folder (see [Files the app writes](https://hyperclaylocal.com/docs/files/)). An argument containing `{prompt}` receives the prompt; if no argument contains `{prompt}`, the prompt is passed on standard input. Adding `"default": "name"` makes that engine the default.

## Security features

- **Sandboxed renderer**: The popover and workspace windows run in isolated, sandboxed Electron contexts (`contextIsolation: true`, `sandbox: true`, `nodeIntegration: false`). Framed documents in the workspace may only request `clipboard-sanitized-write` and `fullscreen` permissions; all other permission requests and hardware device selections (HID, serial, USB, Bluetooth) are refused.
- **IPC security**: Communication between main and renderer processes uses narrow preload bridges, and sensitive IPC calls verify the sender window.
- **Path validation**: Prevents access to files outside the served folder and checks real paths on every read and write.
- **Filename sanitization**: Allows only safe characters in saved filenames and strips Windows-invalid characters from uploaded filenames.
- **Content validation**: Validates document content before saving, strips save tokens from the opening `<html>` tag so credentials never reach disk, and serves uploads with `X-Content-Type-Options: nosniff`.
- **Encrypted credentials**: Encrypts your sync API key on disk using Electron's `safeStorage`.