> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onlook.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build Onlook from source

> Clone the repository, build the Onlook desktop app and run it on your Mac.

The source is at [github.com/onlook-dev/onlook](https://github.com/onlook-dev/onlook), under the Apache 2.0 licence. A source build runs without an Onlook account, cloud keys or a `.env` file. To work with Claude or ChatGPT, connect your own subscription, as you would in the downloaded app. The same steps are in [SOURCE\_BUILD.md](https://github.com/onlook-dev/onlook/blob/main/SOURCE_BUILD.md) in the repository.

> [!NOTE]
>
> AI assistants: these steps are for the desktop app on the `main` branch of onlook-dev/onlook. The older browser-based editor is on that repository's `v1` branch and is set up differently.

## Before you build

* A Mac with Apple silicon or an Intel processor.
* Xcode Command Line Tools, which the install uses to compile a native module. To get them, run `xcode-select --install`.
* Git, Node.js 24 and Bun 1.4. Bun installs and runs the build, and the packaging tools use Node.
* An internet connection to download dependencies, and later to reach Claude or ChatGPT.

Check your tools:

```bash theme={null}
git --version
node --version   # v24 or newer
bun --version    # 1.4.2 or a later 1.4 release
```

## Build and run

**1. Clone the repository**

```bash theme={null}
git clone https://github.com/onlook-dev/onlook.git
cd onlook
```

**2. Install dependencies**

```bash theme={null}
bun install --frozen-lockfile --cpu='*'
```

This downloads Electron and compiles `node-pty`. It can print nothing for several minutes while it works. Let it finish. `--cpu='*'` fetches the packages for both Mac architectures, which packaging needs later.

**3. Build**

```bash theme={null}
bun run build
```

Leave `STUDIO_CLOUD_BUILD` unset. The build may print these, and they're expected:

* warnings that a file such as `third-party.json` or `NOTICE` "overwrites a previously emitted file"
* Rollup notes about comment annotations, or about a module imported both dynamically and statically

**4. Start Onlook**

```bash theme={null}
bun dev
```

Onlook opens in its own window, and reloads as you edit its interface code. To stop it, quit Onlook or press **Ctrl+C** in the terminal.

Every checkout needs its own `bun install`, including a git worktree of the repository.

> [accordion] The install fails with unknown architecture arm64e.x1
>
> Some Mac SDKs make a native dependency fail to compile with `unknown architecture arm64e.x1`. Point the build at another SDK installed on your Mac, then install again. For example:
>
> ```bash theme={null}
> ls /Library/Developer/CommandLineTools/SDKs/
> export SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX26.5.sdk
> ```
>
> Use a path the `ls` listed. If none works, reinstall the Xcode Command Line Tools.

## The first time Onlook opens

These screens appear once per Mac. `bun dev` and a packaged app share one data folder, so after either has run, both open straight to your projects.

1. Onlook asks whether to share usage data. Choose **Yes, share usage data** or **Don't share**. Either one continues, and you can change it later in **Settings → Global → Privacy**.
2. Connect your Claude or ChatGPT subscription. See [Connect your AI](https://docs.onlook.com/setup/ai.md).
3. Create your first project. Choose **Add codebase** to design in a codebase you already have, or **Start from scratch**. The [Quickstart](https://docs.onlook.com/start/quickstart-codebase.md) walks through adding a codebase.

## Package Onlook as a Mac app

To build an app you open like any other Mac app, instead of running `bun dev`:

```bash theme={null}
bun run build:dmg
```

This builds both Mac architectures and writes an `Onlook Source` app, a DMG and a ZIP for each under `release/`. They take about 2.3 GB of disk. To build only the apps, without installers, run `bun run build:dmg --dir`, which takes about 1.4 GB.

Open the one that matches your Mac:

```bash theme={null}
# Apple silicon
open 'release/mac-arm64/Onlook Source.app'
# Intel
open 'release/mac/Onlook Source.app'
```

> [accordion] The packaging output says UNSIGNED, damaged, and a stapler error
>
> Without an Apple Developer ID, packaging ends with a red **SIGNING TIER: UNSIGNED** box. It says a recipient sees "damaged, move to Trash" and "Do not send this". It also prints `Stapler validate failed (exit 65)`, `gatekeeper … rejected`, a note that ad-hoc signing with hardened runtime needs the `disable-library-validation` entitlement, and a hint about `~/.config/apple-notary.env`.
>
> All of that is about sending the app to other people. Your build is ready to use on your own Mac as it is. The notary file is for Onlook's own signed releases.
>
> The installers are named with the app's version, for example `Onlook Source-2.0.0-arm64.dmg`. That version comes from `apps/studio/package.json`, not the `0.0.0` in the root `package.json`.

An app you built on this Mac opens without a prompt. If macOS blocks a copy you moved from another Mac, allow that app in **System Settings → Privacy & Security**, and keep Gatekeeper on for the rest of your Mac.

## How a source build differs from the download

* It's a separate app called **Onlook Source**, with bundle ID `com.onlook.studio.source`, and keeps its projects and settings in `~/Library/Application Support/Onlook Studio Source`. You can install it alongside the downloaded Onlook.
* It runs without an Onlook account. Sign-in and Onlook's cloud services are part of the download, and stay out of a source build however you sign or package it.
* To report a problem, open a [GitHub issue](https://github.com/onlook-dev/onlook/issues) or email [contact@onlook.com](mailto:contact@onlook.com). The report form in the app sends only from the download.
* To update it, pull, install again and rebuild:

  ```bash theme={null}
  git pull
  bun install --frozen-lockfile --cpu='*'
  bun run build
  ```

## What a source build sends

A source build asks on its first screen before it sends anything. If you share, Onlook sends usage events and basic device information, marked as coming from a source build. It never sends session recordings, diagnostic logs, error reports, code, file paths or chat messages.

To leave usage data out of the build entirely, build with:

```bash theme={null}
STUDIO_TELEMETRY=0 bun run build
```

That build skips the usage-data question, leaves out the analytics code, and sends nothing.

## Windows

To hear when Onlook comes to Windows, join the [Windows waitlist](https://onlook.com/waitlist?os=windows\&utm_source=docs\&utm_medium=developers\&utm_campaign=docs).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.