.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.
Build and run
1
Clone the repository
2
Install dependencies
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
STUDIO_CLOUD_BUILD unset. The build may print these, and they’re expected:- warnings that a file such as
third-party.jsonorNOTICE“overwrites a previously emitted file” - Rollup notes about comment annotations, or about a module imported both dynamically and statically
4
Start Onlook
bun install, including a git worktree of the repository.
The install fails with unknown architecture arm64e.x1
The install fails with unknown architecture arm64e.x1
Some Mac SDKs make a native dependency fail to compile with Use a path the
unknown architecture arm64e.x1. Point the build at another SDK installed on your Mac, then install again. For example: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.
- 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.
- Connect your Claude or ChatGPT subscription. See Connect your AI.
- 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 runningbun dev:
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:
The packaging output says UNSIGNED, damaged, and a stapler error
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.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: