Skip to Content
DocumentationHyperclay Local App

Hyperclay Local App

A desktop app for running malleable HTML files locally.

Update required for syncing with hyperclay.com: The server now requires filenames to include .html or .htmlclay extensions. Older versions of Hyperclay Local don’t send extensions, so their syncs will fail. Install the latest version (1.16.2) from the Quick Start below.

  • 🛠️ Build Without Limits
    • Self-contained malleable HTML files. No frameworks needed. Just HTML, CSS, and JavaScript.
  • 💾 Your Apps, Your Computer
    • Everything runs locally. No cloud dependencies. Perfect for sensitive projects.
  • 🍄 Zero Friction
    • One click starts your server. No build steps. Edit and refresh instantly.
  • 🌍 Cross-Platform
    • Works on macOS, Windows, and Linux. Share apps with anyone.

Why Use Hyperclay Local?

While hyperclay.com  provides the full hosted experience with user accounts, version history, and collaboration features, this local server lets you:

✅ Work offline - Edit your apps without internet connection
✅ Own your data - Complete independence from any platform
✅ No subscription needed - Run unlimited apps locally for free
✅ Privacy first - Your apps and data never leave your computer
✅ Future-proof - Apps work forever, regardless of service status

Quick Start

For Users (Download Pre-built App)

  1. Download the app for your platform:

  2. Install and run the app

  3. Select your folder containing malleable HTML files

  4. Click “Start Server”

  5. Open your apps by choosing “Open Browser” from the tray or options menu, or visiting http://localhost:4321 

For Developers (Build from Source)

📦 GitHub Repository 

# Install dependencies
npm install
 
# Run in development mode
npm run dev
 
# Build for all platforms
npm run build-all
 
# Build for specific platform
npm run build-mac     # macOS
npm run build-windows # Windows  
npm run build-linux   # Linux

How It Works

Server Integration

The app runs an embedded Express.js server (same as the Node.js version) with:

  • Static file serving with extension-based SPA routing
  • POST /_/save endpoint for app self-saving (identifies the file via Page-URL header)
  • Beautiful directory listings
  • Security protections (path traversal, filename validation)

User Interface

The app lives in your system tray. Clicking the tray icon opens a small popover anchored to it, and the tray menu is the main control surface.

Tray Menu

  • Server: On/Off and Sync: On/Off status at a glance
  • Start/Stop Server
  • Enable/Disable Sync
  • Open Folder and Open Browser
  • View Sync Logs and View Error Logs
  • Enter API Key for Sync (from the options menu)
  • About and Quit

Background Operation

  • The app runs in the tray with no main window
  • It keeps running after you close the popover

Syncing with hyperclay.com

You can two-way sync your local files with your hyperclay.com account:

  1. Choose “Enter API Key for Sync” and paste your hyperclay.com API key
  2. Enable Sync from the tray menu
  3. The sync engine keeps your local folder and your hyperclay.com account in sync, both directions

Security Features

  • Sandboxed renderer: Web content runs in isolated context
  • IPC security: Secure communication between main and renderer processes
  • Path validation: Prevents access to files outside selected folder
  • Filename sanitization: Only allows safe characters in saved files
  • Content validation: Validates file content before saving

Troubleshooting

Installation Issues

macOS “App is damaged” error

xattr -cr "/Applications/Hyperclay Local.app"

Windows SmartScreen warning

Click “More info” → “Run anyway” (This happens because the app isn’t code-signed)

Linux permission denied

chmod +x HyperclayLocal-1.17.0.AppImage

Runtime Issues

Port 4321 already in use

  • The app will show an error dialog
  • Kill any existing process using the port
  • Or wait for the existing process to terminate

Server won’t start

  • Check the folder contains some files
  • Ensure folder path doesn’t contain special characters
  • Try selecting the folder again

Links & Resources

Made with ❤️ for Hyperclay - The platform for malleable HTML files

Last updated on
Undo and RedoFAQ