# Quick start

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

Source: https://hyperclaylocal.com/docs/guide/quick-start/

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:

- **macOS (Apple Silicon)**: [HyperclayLocal-1.32.0-arm64.dmg](https://local.hyperclay.com/HyperclayLocal-1.32.0-arm64.dmg)
- **macOS (Intel)**: [HyperclayLocal-1.32.0.dmg](https://local.hyperclay.com/HyperclayLocal-1.32.0.dmg)
- **Windows (x64, NSIS)**: [HyperclayLocal-Setup-1.32.0.exe](https://local.hyperclay.com/HyperclayLocal-Setup-1.32.0.exe)
- **Linux (x86_64, AppImage)**: [HyperclayLocal-1.32.0.AppImage](https://local.hyperclay.com/HyperclayLocal-1.32.0.AppImage)
- **Linux (ARM64, AppImage)**: [HyperclayLocal-1.32.0-arm64.AppImage](https://local.hyperclay.com/HyperclayLocal-1.32.0-arm64.AppImage)

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

```bash
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:

```bash
# 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](https://hyperclaylocal.com/docs/guide/workspace/). Closing the workspace window hides the window (and hides the macOS dock icon) while the app keeps running in the tray.

**Step 1: Open the tray popover**

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

**Step 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.

**Step 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.

**Step 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](https://hyperclaylocal.com/docs/export/)).

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](https://hyperclaylocal.com/docs/guide/sync/), each [team folder](https://hyperclaylocal.com/docs/guide/team-folders/) 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](https://hyperclaylocal.com/docs/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](https://github.com/panphora/hyperclay-local). Building from source requires Node.js 20 or newer.

```bash
# 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](https://hyperclaylocal.com/docs/platforms/) for full build and packaging details.