# Platforms and building from source

> Supported macOS, Windows, and Linux architectures and installer formats for Hyperclay Local, plus steps to run and package the app from source.

Source: https://hyperclaylocal.com/docs/platforms/

Hyperclay Local runs on macOS, Windows, and Linux. You can install a pre-built release or run and package the application from source.

## Pre-built installers and architectures

Each release publishes installers for five platform and architecture targets:

| Operating system | Architecture | Package format | Filename |
| --- | --- | --- | --- |
| macOS | Apple Silicon (`arm64`) | DMG and ZIP | `HyperclayLocal-<version>-arm64.dmg` |
| macOS | Intel (`x64`) | DMG and ZIP | `HyperclayLocal-<version>.dmg` |
| Windows | 64-bit (`x64`) | Per-user NSIS installer | `HyperclayLocal-Setup-<version>.exe` |
| Linux | 64-bit (`x86_64` / `x64`) | AppImage | `HyperclayLocal-<version>.AppImage` |
| Linux | ARM64 (`arm64`) | AppImage | `HyperclayLocal-<version>-arm64.AppImage` |

- **macOS**: builds are signed with a Developer ID certificate and notarized by Apple with Hardened Runtime enabled. The `.dmg` is for initial installation; the `-mac.zip` archive is used by the in-place updater (see [Updates](https://hyperclaylocal.com/docs/updates/)).
- **Windows**: the installer is a one-click per-user NSIS `.exe` signed with a timestamped certificate. There is no `arm64` or 32-bit Windows build.
- **Linux**: before running a downloaded AppImage for the first time, mark it as executable:

```bash
chmod +x HyperclayLocal-*.AppImage
```

Installing Hyperclay Local registers the app with your operating system as an alternate handler for `.html` (Viewer) and `.htmlclay` (Editor) files, so it appears in your file manager's Open With menu without replacing your default browser (see [Open With](https://hyperclaylocal.com/docs/open-with/)).

## Run from source

### Prerequisites

- **Node.js 20 or newer** (`package.json` requires `>=20`)
- **npm**

### Start in development mode

Clone the repository from `https://github.com/panphora/hyperclay-local`, install dependencies, and start the development watchers:

```bash
git clone https://github.com/panphora/hyperclay-local.git
cd hyperclay-local
npm install
npm run dev
```

`npm run dev` watches Tailwind CSS and the React renderer with Webpack and restarts Electron automatically via `electronmon` when source files change. A development run stores its settings and logs in a separate `<userData>-dev` directory so it never overwrites your installed app's settings (see [Files the app writes](https://hyperclaylocal.com/docs/files/)).

To build the production renderer once and launch Electron without file watchers:

```bash
npm start
```

## Build installers from source

To compile the CSS and React renderer and package an unpacked build or installer for your current platform into `dist/`:

```bash
npm run build
```

### Platform-specific build scripts

- **macOS (unsigned local DMG for testing)**:

```bash
npm run mac-build:local
```

- **macOS (signed and notarized DMG and ZIP)**:

```bash
npm run mac-build:run
```

Signing and notarizing on macOS requires a "Developer ID Application" certificate in your Keychain and `APPLE_ID`, `APPLE_APP_PASSWORD`, and `APPLE_TEAM_ID` exported in your environment. Finished macOS artifacts are moved from `dist/` to `executables/`. You can check notarization status with `npm run mac-build:finalize`.

- **Linux (AppImage)**:

```bash
npm run linux-build:run
```

Builds the Linux AppImage for the host architecture and moves the resulting `.AppImage` from `dist/` into `executables/`.

- **Windows (`x64` NSIS installer)**:

Windows releases are built and signed with Azure Trusted Signing in GitHub Actions using:

```bash
npx electron-builder --win --publish never
```