Hyperclay Local
  1. Hyperclay Local
  2. Guide
  3. Quick start

Quick start

Download Hyperclay Local, pick a folder of malleable documents, and start serving on localhost.

Install Hyperclay Local, pick a folder on your computer, and start editing malleable documents in the workspace window or your browser.

Install#

Download the v1.32.0 installer for your platform. The URL pattern is stable across releases:

Text
https://local.hyperclay.com/HyperclayLocal-1.32.0-arm64.dmg      macOS, Apple Silicon
https://local.hyperclay.com/HyperclayLocal-1.32.0.dmg            macOS, Intel
https://local.hyperclay.com/HyperclayLocal-Setup-1.32.0.exe      Windows, x64, NSIS
https://local.hyperclay.com/HyperclayLocal-1.32.0.AppImage       Linux, x64, AppImage
https://local.hyperclay.com/HyperclayLocal-1.32.0-arm64.AppImage Linux, arm64, AppImage

To check the current release version and exact file sizes in bytes without scraping a page, fetch the release manifest:

Shell
curl -s https://local.hyperclay.com/release-info.json

It returns { "version", "commit", "date", "files": [...], "sizes": { filename: bytes } }. Each build is roughly 100 MB because it bundles Electron.

  • macOS: Signed by Hyperspace Systems LLC (JC7YGGXYKH) with hardened runtime and notarized.
  • Windows: One-click, per-user NSIS installer (HyperclayLocal-Setup-1.32.0.exe) with a timestamped signature. If Windows SmartScreen warns on a new release, click More info and then Run anyway.
  • Linux: Shipped as a single-file AppImage for x86_64 and arm64.

Post-install fixes for common platform prompts:

Shell
# macOS, if Gatekeeper reports "App is damaged"
xattr -cr "/Applications/HyperclayLocal.app"

# Linux, the AppImage arrives without the executable bit
chmod +x HyperclayLocal-*.AppImage

Run the server#

Hyperclay Local lives in your system tray and includes a 1200x800 Hyperclay Local workspace window. Closing the workspace window hides the window (and hides the macOS dock icon) while the app keeps running in the tray.

  1. Open the tray popover

    Click the Hyperclay Local icon in your system tray to open the popover panel (340x500 px).

  2. Choose your personal folder

    Under Choose a folder, click Choose folder… and pick a folder in the native directory picker (titled Select folder containing your malleable documents). Any folder inside your home folder works, including an empty one.

  3. Start serving automatically

    On your first run, picking a folder also starts the server. After that, use the Serve switch in the popover (Turn server on / Turn server off) or Start Server / Stop Server in the tray menu to turn serving on and off.

  4. Open your documents

    Click Open workspace (or click localhost:4321 on the folder card) to open your folder in the workspace window. To use your default browser instead, open the folder card’s ⋯ menu and click Open in Browser, or visit http://localhost:4321 (a top-level browser visit to http://localhost:4321/ also redirects into the workspace).

Folder actions and changing folders#

Use the ⋯ menu on a folder card (or the folder’s submenu in the system tray) for:

  • Open in Browser: Opens http://localhost:<port> in your default browser.
  • Copy Address: Copies http://localhost:<port> to the clipboard.
  • Reveal Folder: Opens the folder in Finder or your file manager.
  • Backups: Opens <folder>/.hyperclay/versions/ in your file manager.
  • Export a File as Zip…: Packages a document together with its linked uploads into a .zip archive (see Export as zip).

To serve a different personal folder, open Options in the popover footer and click Change Personal Folder….

Ports and multiple folders#

Hyperclay Local binds to 127.0.0.1 (localhost) only:

  • Personal folder: Served on port 4321.
  • Team folders: When you connect sync with hyperclay.com, each team folder you set up gets its own folder and the first free port from the ladder 5432, 6543, 7654, 8765, 9876, falling back to a random port between 49152 and 65535.

If another program is using a folder’s port, the popover shows Can't serve (Not served. Another program has :<port>.) with a Retry button and, for team folders, a Use port <n>… button to move the folder to the next free port. See Folders and ports for details.

Your configured folders, ports, and switch states are saved in settings.json (and currently running folders are listed in served-roots.json), so folders that were serving when you quit start serving again on the next launch. When you quit, Hyperclay Local waits for open tabs to finish saving, stops the sync engine, and stops the local servers.

Run or build from source#

The source code is in the GitHub repository. Building from source requires Node.js 20 or newer.

Shell
# Install dependencies
npm install

# Run in development mode (watches CSS, renderer, and Electron)
npm run dev

# Build the production renderer and start Electron
npm start

# Package the app for your current platform into dist/
npm run build

# Build macOS and Linux release packages
npm run build-all

# Per-platform build scripts
npm run mac-build:local   # Unsigned local macOS build
npm run mac-build:run     # Signed macOS DMG and ZIP (moved to executables/)
npm run linux-build:run   # Linux AppImage (moved to executables/)

See Platforms and building from source for full build and packaging details.