Skip to main content
The source is at 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 in the repository.
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:

Build and run

1

Clone the repository

2

Install dependencies

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

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

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.
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:
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.
  3. Create your first project. Choose Add codebase to design in a codebase you already have, or Start from scratch. The Quickstart 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:
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:
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 or email contact@onlook.com. The report form in the app sends only from the download.
  • To update it, pull, install again and rebuild:

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