Hyperclay Local
  1. Hyperclay Local
  2. Docs
  3. Reference
  4. How it works

How it works

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

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 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):

  • 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).
  • Workspace and directory listings: A top-level GET / on a folder’s port redirects to the workspace window 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, 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).

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

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

AI editing#

Select text in any editable document that loads ClayJS, 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). 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). 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.