Hyperclay™ Local Server (Electron App)

License: First Million Stays Yours License. Free to use, no matter who you are or what you use it for. It only ever costs money if you sell or host a product built on this software and that product makes you more than $1M in a year. Under that line you owe nothing, sign nothing, register nowhere.

Free under	Above it	Becomes MIT
$1M/year from products built on it	3% of the excess	2028-02-20 (this version)

Plain answers: hyperclay.com/host-program · binding text in LICENSE · questions: license@hyperclay.com

A beautiful, cross-platform desktop application for running your malleable HTML files locally with zero configuration.

• 🖥️ Native desktop app - Familiar GUI interface
• 📁 Visual folder selection - Point and click to choose your apps folder
• 🚀 One-click server start - Start/stop server with buttons
• 🌐 Auto-browser opening - Automatically opens your default browser
• 📊 Real-time status - Visual indicators for server state
• 🔔 System tray integration - Runs in background, accessible from tray
• 🎨 Beautiful UI - Modern, responsive interface
• 🔗 Quick links - Easy access to Hyperclay.com and docs
• 🔄 Cloud sync - Sync your local files with hyperclay.com using an API key
• 📦 Update notifications - Automatically checks for new versions
• ⚡ Cross-platform - Works on macOS, Windows, and Linux

Hyperclay lets you create malleable HTML files - powerful, self-contained files that you fully own and control. Think of it as combining the simplicity of Google Docs with the power of custom web applications.

• Own Your Stack: No vendor lock-in. Download your apps and run them anywhere.
• Malleable: Your HTML files can modify themselves and save changes instantly.
• Shareable: Send a link, and others can view or clone your app with one click.
• Future-Proof: Built on standard HTML/CSS/JavaScript - no proprietary frameworks.

Your malleable HTML files can edit themselves in real-time. Change text, add features, modify layouts - everything saves automatically and becomes part of the app. Each app is a complete HTML document that includes:

• Your content and data
• Styling (CSS)
• Behavior (JavaScript)
• File references
• Version metadata

Toggle edit mode by adding ?editmode=true to any app URL or clicking the edit button. In edit mode:

• Click any text to edit it inline
• Add new elements and components
• Upload files and images
• Customize styling and behavior
• Save changes instantly with Ctrl+S

• 📝 Writer: Personal writing app with auto-save, word count, and export options
• 📋 Kanban Board: Visual project management with drag-and-drop cards and columns
• 🛠️ Development Log: Track coding projects, bugs, features, and progress over time
• 🏠 Landing Pages: Beautiful pages for projects, products, or personal sites
• 🎯 Custom Apps: Calculators, games, portfolios, databases, dashboards - anything you can imagine

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

This local server provides the core functionality needed to run and edit your Hyperclay apps, ensuring you're never locked into any platform while still benefiting from the powerful malleable HTML concept.

1. Download the app for your platform:

   • macOS (Apple Silicon): HyperclayLocal-1.28.0-arm64.dmg (102.3MB)
   • macOS (Intel): HyperclayLocal-1.28.0.dmg (108.8MB)
   • Windows: HyperclayLocal-Setup-1.28.0.exe (90.1MB)
   • Linux (x86_64): HyperclayLocal-1.28.0.AppImage (123.7MB)
   • Linux (ARM64): HyperclayLocal-1.28.0-arm64.AppImage (123.4MB)

2. Install and run the app

3. Select your folder containing malleable HTML files

4. Click "Start Server"

5. Browser opens automatically to your apps!

npm install
npm run dev

For building and releasing, see BUILD.md.

The standalone hyperclaylocal.com marketing page lives in website/. See WEBSITE.md for its structure, local preview workflow, download-link contract, and tests.

Read and update .html and .htmlclay files as JSON using CSS selector rules.

Caller supplied rules work on both URL forms, for GET and POST. No embedded tag is required:

curl --get 'http://127.0.0.1:51842/soup.htmlclay' \
  --data-urlencode 'data={title:h1}'

curl --request POST \
  'http://127.0.0.1:51842/soup.htmlclay?data=%7Btitle%3Ah1%7D' \
  --header 'Content-Type: application/json' \
  --data '{"title":"Lunch"}'

Replace the port with your file's port. The same requests work with /_/api/soup.htmlclay?data=%7Btitle%3Ah1%7D, and with .html files. Supplied rules replace the embedded mapping for that request, even if the tag is malformed. They are never merged with it or saved into the file. Without data, /_/api/ uses the embedded api tag as before. An empty, malformed, or repeated data parameter returns 400; it never falls back to the tag. POST bodies remain strict JSON, with no rules envelope. The response uses the same rules as the request. GET and POST return the source file's ETag; send it as If-Match to refuse a stale write with 412.

Writes preserve the existing save flow, including backups and live updates. They change content only: scripts, styles, event handlers, executable URLs, and raw HTML targets are refused. Unknown body keys and unmatched selectors return 400 without writing anything. Use Content-Type: application/json and a body no larger than 1 MB. Browser requests must come from the same origin; command line requests need no browser token.

Caller projections bypass the embedded mapping's cache. Each complete source filename has its own JSON cache, so soup.html and soup.htmlclay remain independent. Existing legacy Tailwind CSS URLs still share a basename: cold generation prefers .html, then falls back to .htmlclay if the HTML file is missing.

The app lives in your system tray. Click the tray icon to open a popover panel with:

• Server controls: Start/stop server and open browser
• Folder selection: Choose which folder to serve
• Sync status: Cloud sync controls and status indicators
• Options menu: Folder management, sync settings, auto-start, and about info

• Status labels: Shows server and sync state (On/Off) in the context menu
• Quick actions: Start/stop server, toggle sync, open folder, open browser
• Background operation: App runs entirely from the tray with no dock icon (macOS)

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

• Static file serving with extensionless HTML support
• POST /_/save endpoint for app self-saving, with Document-URL identifying the file
• Beautiful directory listings
• Security protections (path traversal, filename validation)

• Folder Selection: Native OS folder picker dialog
• Path Security: Ensures all files served are within selected folder
• File Types: Serves all file types, special handling for HTML
• Hidden Files: Automatically hides dotfiles and system files

• Auto-launch: Opens default browser when server starts
• External links: Opens external links in default browser

• API key authentication: Securely encrypted with Electron's safeStorage
• Two-way sync: Syncs local files with your hyperclay.com account
• Auto-resume: Sync restarts automatically on app launch if previously enabled
• Sync queue: Changes are queued and synced reliably with conflict handling

Select some text in any HTML file that loads ClayJS, press ⌘J (Ctrl+J on Windows and Linux) or click the small AI chip at the end of the selection, and describe the change. An agent on your computer rewrites the block around the selection, and the page shows the rewrite in place. Keep saves it. Revert puts the original back. Nothing is saved while the rewrite waits for your answer.

• On by default. Turn it off with AI Editing in the tray menu.
• Uses the agent CLIs you already have installed and signed in: Claude Code by default, @fable for Fable, @codex for the Codex CLI. Start the request with the name to pick one.
• The agent runs with no tools: it cannot read files, run commands or browse. It sees the block's HTML, the selected text, your request, any file you name with @name.ext (it must sit inside the served folder; at most 8 files, 256 KB each, 1 MB in total), and with @page the whole saved page. The agent CLI sends that prompt to its model provider.
• A reply that adds a script, an inline event handler or a javascript: URL is refused.
• @agy is not supported, because agy can read files without asking.
• One AI edit runs per document at a time.
• Your own agents: add "aiEdit": { "engines": { "name": ["command", "arg", "{prompt}"] } } to settings.json in the app's data folder. An argument containing {prompt} receives the prompt; without one, the prompt arrives on standard input. "default": "name" makes one the default.

• 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
• Encrypted credentials: API keys stored using Electron's safeStorage

src/
├── main/
│   ├── main.js              # Electron main process
│   ├── server.js            # Express server
│   ├── popover.js           # Tray popover window
│   ├── popover-preload.js   # Secure IPC bridge
│   ├── format-html.js       # HTML formatting
│   ├── error-logger.js      # Error logging
│   ├── templates/           # Eta.js templates for directory listings
│   └── utils/               # Backup and utility functions
├── renderer/
│   ├── popover.html         # Popover UI shell
│   ├── PopoverApp.jsx       # React UI component
│   ├── popover-index.js     # Renderer entry point
│   └── styles/              # Tailwind CSS source and output
└── sync-engine/             # Cloud sync with hyperclay.com
    ├── index.js             # Sync engine entry point
    ├── api-client.js        # API communication
    ├── file-operations.js   # File sync operations
    ├── sync-queue.js        # Sync queue management
    └── ...                  # Validation, logging, utilities
assets/                      # App icons, tray icons, fonts
build-scripts/               # Build, notarize, and release tooling
config/                      # Webpack configuration
tests/                       # Unit tests

npm install
npm run dev

Development mode features:

• Hot reload: Automatically restarts on file changes

For building signed installers, see BUILD.md.

When running npm run dev, the app exposes two debugging affordances that are never active in production builds (they're gated on !app.isPackaged):

1. Chrome DevTools Protocol (CDP) on port 9229 — lets agent-browser (or any CDP client) drive the popover's React UI directly. Attach with:

   agent-browser connect 9229
   agent-browser --auto-connect false snapshot -i

   Filter for the target whose URL contains popover.html.

2. Two HTTP endpoints on the local server (localhost:4321, dev only) for controlling the popover without clicking the tray:

   curl -X POST http://localhost:4321/__dev/popover/show    # show + stick
   curl -X POST http://localhost:4321/__dev/popover/hide    # hide + unstick

   /__dev/popover/show opens the popover, marks it "sticky" (suppresses the normal blur-hide so it stays open while you focus other apps), and writes a marker file (<userData>-dev/debug-popover-sticky.flag) so the state survives electron-reload restarts and full npm run dev restarts. The popover will automatically reappear sticky on the next dev launch until you call /__dev/popover/hide.

   These routes only exist when !app.isPackaged and are not registered in production builds.

This combination lets an AI assistant work on the popover UI in the background while you keep using your Mac — the popover stays open, CDP stays accessible, and reloads don't interrupt the session.

When adding new npm dependencies, consider whether they need asarUnpack in package.json. Electron bundles node_modules into a .asar archive, which can break:

• Native bindings (e.g., lightningcss in tailwind-hyperclay)
• Dynamic require.resolve() with package.json exports
• File system operations with hardcoded paths

If a module fails in production builds but works in development, add it to asarUnpack:

"asarUnpack": [
  "node_modules/your-module/**"
]

Pure JavaScript modules (like livesync-hyperclay) typically work without unpacking.

macOS "App is damaged" error:

xattr -cr "/Applications/HyperclayLocal.app"

Windows SmartScreen warning:

• Click "More info" → "Run anyway"
• This happens because the app isn't code-signed

Linux permission denied:

chmod +x HyperclayLocal-*.AppImage

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

Folder selection not working:

• Ensure you have read permissions for the folder
• Try selecting a different folder
• Restart the app if the dialog doesn't appear

Server won't start:

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

Apps won't save:

• Check browser console for error messages
• Ensure the app is making requests to localhost:4321
• Verify the save endpoint is working by testing manually

App feels slow:

• This is normal for Electron apps
• Close other resource-intensive applications

High memory usage:

• Electron apps use more memory than native apps
• ~100-200MB usage is normal
• Restart the app if memory usage grows excessively

Planned features for future versions:

• Auto-updater: Automatic app updates (update checking already exists, auto-install planned)
• Multiple servers: Run multiple folders simultaneously
• Custom ports: Configure server port in settings
• HTTPS support: Local SSL certificates
• File watcher: Auto-refresh browser on file changes
• Themes: Dark mode and custom themes
• Plugin system: Extend functionality with plugins

Contributions welcome! Areas that need help:

• UI/UX improvements: Better design and user experience
• Performance optimization: Reduce app size and memory usage
• Cross-platform testing: Ensure consistent behavior
• Documentation: Improve guides and troubleshooting
• Feature requests: Suggest and implement new features

Made with ❤️ for Hyperclay - The platform for malleable HTML files
Get the full experience at hyperclay.com