The open-source Arc replacement for macOS. Spaces, pinned tabs, split view, Little Windows and Arc's shortcuts on Chromium, with your Arc sidebar imported in one go.
Releasing Cra
Goal: a build that installs like any other Mac app. Download the DMG, drag Cra to Applications, open it. No right-click, no warnings. That needs three things on top of the plain build: a Developer ID signature with the hardened runtime, Apple's notarization ticket stapled to the app and the DMG, and a packaged download. Everything is scripted; the only manual part is obtaining the certificate once.
One-time setup
Apple Developer Program membership for the account that will sign.
Developer ID Application certificate. In Xcode → Settings → Accounts → Manage Certificates, add "Developer ID Application". Export it from Keychain Access as a
.p12with a password. Note the identity string, for exampleDeveloper ID Application: Victor Kildahl (ABCDE12345):security find-identity -v -p codesigning.Notarization credentials. Create an app-specific password at appleid.apple.com. Locally you can store it once:
xcrun notarytool store-credentials cra --apple-id [email protected] --team-id ABCDE12345and then setNOTARY_KEYCHAIN_PROFILE=cra.GitHub secrets on
VictorKildahl/cra(Settings → Secrets and variables → Actions):Secret Value MACOS_CERTIFICATE_P12base64 -i DeveloperID.p12 | pbcopyMACOS_CERTIFICATE_PASSWORDthe .p12passwordMACOS_SIGN_IDENTITYthe identity string from step 2 APPLE_IDthe Apple ID email APPLE_TEAM_IDthe 10-character team id APPLE_APP_PASSWORDthe app-specific password MACOS_PROVISIONING_PROFILEoptional, for passkeys (see Passkeys) CRA_GOOGLE_API_KEYoptional, for Safe Browsing (see Safe Browsing)
Until these exist the Release workflow still runs: it publishes an ad-hoc build as a
regular release (pre-releases are invisible to releases/latest) with the install
steps in .github/release-notes-unsigned.md.
Installing unsigned builds
Gatekeeper only checks files carrying the quarantine flag, which browsers set and curl
does not. So the friction-free path for an ad-hoc build is scripts/install.sh, run as
curl -fsSL https://raw.githubusercontent.com/VictorKildahl/cra/main/scripts/install.sh | bash
It downloads releases/latest/download/Cra.zip, replaces the app in /Applications
(or ~/Applications), quitting a running Cra first, and opens it. Rerunning it updates.
The DMG path needs one manual approval: open Cra, click Done on the "could not verify" dialog, then System Settings → Privacy & Security → Open Anyway. Right-click → Open no longer bypasses Gatekeeper since macOS 15. The README, release notes and the website's download page all carry both paths; keep them in step.
Cutting a release
Run the manual checks in release-checklist.md for every area the release touched first.
# 1. Add the release to the website's src/content/releases.ts and bump CRA_VERSION defaults if needed.
# 2. Tag and push. The Release workflow builds, signs, notarizes, packages and publishes.
git tag v0.1.0
git push origin v0.1.0
Clips in the release notes
When a release changes something you can see (UI, animations, dragging), give its
highlight a short clip. scripts/clips/ records one from a test copy of Cra (CraClip, own
data folder, the website's demo profile) at 120 fps with a pointer that glides like a hand;
the release-clips skill in .claude/skills/ has the steps. Then encode it from the
website repo:
FPS=120 scripts/release-clip.sh 0.1.14 reorder-spaces ../cra/build/clips/rec/dock.mov 0.9 5.9
It writes public/releases/<version>/<name>.mp4 (H.264, silent, ≤1520 px) and a poster
.jpg, and prints a media: {…} entry to paste into that highlight in releases.ts (fill
in alt). A .png works too, for still changes. The release notes page loops clips muted
while they're on screen. Keep them under ~8 s and ~2 MB.
A Claude Code hook (.claude/settings.json → scripts/clips/check-release-media.sh) blocks
pushing a v* tag when Sources/Cra/UI changed since the previous tag and the release's
entry has no media. If there is nothing to film, add // no clip: <reason> to the entry.
Artifacts land on the GitHub release: Cra.dmg, Cra.zip, SHA256SUMS.txt. The names
carry no version so releases/latest/download/Cra.dmg always resolves; the website's
download button and scripts/install.sh rely on that.
Locally
CRA_VERSION=0.1.0 \
CRA_SIGN_IDENTITY="Developer ID Application: Victor Kildahl (ABCDE12345)" \
NOTARY_KEYCHAIN_PROFILE=cra \
scripts/release.sh
scripts/release.sh runs build.sh (sign, innermost first, with the CEF entitlements),
notarizes and staples the app, runs package.sh (zip, DMG with an Applications link,
checksums), then notarizes and staples the DMG and checks it with spctl.
Without CRA_SIGN_IDENTITY it produces an ad-hoc build and skips notarization.
The DMG window
Opening Cra.dmg shows a drag-to-install window modelled on Dia's installer (decoded from
its .DS_Store): 800×400 pt, no toolbar or sidebar, 212 pt icons with Cra at (190, 180)
and Applications at (610, 180), and a background with the install line and a chevron
between them. scripts/package.sh builds it with dmgbuild,
which writes the Finder layout directly, so it needs no Finder scripting and runs on CI.
It installs a pinned dmgbuild into build/dmgbuild-venv on first use.
resources/dmg/settings.py: window, icon size and positions, volume icon.resources/dmg/background.png: 1600×800 px at 144 dpi. Regenerate it withswift scripts/make-dmg-background.swiftafter changing the brand colours or the layout.
What the signing covers
Order matters because each signature seals what is inside it:
- every
.dylibinChromium Embedded Framework.framework/Libraries - the framework itself
- Sparkle's
AutoupdateandUpdater.app, thenSparkle.framework(its XPC services are removed: they are only for sandboxed apps) - the five helper apps, each with
resources/CraHelper.entitlements Cra.appwithresources/Cra.entitlements
The entitlements are the hardened-runtime exceptions Chromium needs (JIT, unsigned executable memory, library validation off, dyld environment variables), plus camera, microphone and location so sites can ask for them.
The helpers run in Chromium's own macOS sandbox (seatbelt): CraHelper enters it through
CefScopedSandboxContext (which loads the framework's Libraries/libcef_sandbox.dylib)
before loading CEF, and CefSettings.no_sandbox is off. Renderer, GPU, network, storage
and audio processes are sandboxed, video capture is not (Chrome's choice too).
Passkeys
Security keys and phones (the QR code in Chrome's "Passkeys & Security Keys" dialog) work in every build. Passkeys kept on the Mac need entitlements macOS only honours with a provisioning profile, the way Chrome, Arc and Dia ship:
| Entitlement | Turns on |
|---|---|
keychain-access-groups = <team>.dk.kildahl.cra.webauthn |
Chromium's Touch ID passkeys, stored in Cra's keychain group. scripts/cef-patches/webauthn-keychain-access-group.patch derives the group from the app's application-identifier (Chromium's branding has no team ID). |
com.apple.developer.web-browser.public-key-credential |
iCloud Keychain passkeys (Passwords app), through Chromium's own iCloud Keychain code. Managed: Apple must approve it. |
One-time setup, as the Account Holder:
- Request the entitlement for
dk.kildahl.craat https://developer.apple.com/contact/request/macos-browsers-passkeys/ (Account Holder only). Apple reviews it and adds it as a managed capability, which then shows under the App ID's Additional Capabilities. The Touch ID group needs no approval. - Create a Developer ID provisioning profile for the explicit App ID
dk.kildahl.craand download it. Once the entitlement is approved, regenerate it and check that it is included:security cms -D -i Cra.provisionprofile | grep -A1 public-key. - Locally:
CRA_PROVISIONING_PROFILE=Cra.provisionprofilenext toCRA_SIGN_IDENTITY. In CI: theMACOS_PROVISIONING_PROFILEsecret,base64 -i Cra.provisionprofile | pbcopy.
build.sh embeds the profile as Contents/embedded.provisionprofile and adds to
Cra.entitlements only what the profile grants (application and team identifier,
the keychain group, iCloud Keychain once approved), because macOS refuses to launch an
app that claims an entitlement its profile lacks. Ad-hoc builds never get them.
Safe Browsing
Chromium's phishing and malware lists come from Google's Safe Browsing API, which needs an API key. Without one the lists never download and dangerous pages load without a warning.
- In the Google Cloud console, create a project, enable the Safe Browsing API and create an API key. Restrict it to that API: it ships inside the app, so anyone can read it.
- Locally:
CRA_GOOGLE_API_KEY=<key>next toCRA_SIGN_IDENTITY. In CI: theCRA_GOOGLE_API_KEYsecret. Never commit it.
build.sh writes it to Info.plist as CraGoogleAPIKey, and CraCEF sets
GOOGLE_API_KEY from it before Chromium starts.
The key lives in the Google Cloud project cra-browser, restricted to the Safe Browsing
API. Every install shares its quota: 10,000 list updates and 10,000 lookups a day. A
running Cra fetches list updates 1–5 minutes after launch and then once a day
(scripts/cef-patches/safe-browsing-update-interval.patch; Chrome uses Google's ~30
minutes), plus a full-hash lookup when a URL matches a list: about 1–3 updates per
install per day. An alert policy in the project emails at 7,000 a day; ask for more on
the API's Quotas page in the Cloud console (the Cloud Quotas API can't). Once the quota
allows it, shorten the interval in the patch. A client over quota backs off (up to 24
hours) and its lists go stale until an update succeeds.
The Safe Browsing API is for non-commercial use. Google's commercial service, Web Risk, is not a drop-in: it has its own endpoints and request format, so Chromium would need a patch to its update and full-hash protocol.
Updates
Cra updates itself the way Arc does, with Sparkle 2
(scripts/fetch-sparkle.sh puts a pinned, checksummed release in vendor/sparkle). Every
8 hours it reads releases/latest/download/appcast.xml, downloads a newer Cra.zip in
the background, installs it when Cra quits, or restarts into it by itself once the user
is away. Cra menu ▸ Check for Updates… and Settings ▸ Advanced ▸ "Automatically update Cra"
are the controls. Details and Arc's original are in docs/arc-reverse-engineering.md
("Software updates").
- Signing key. Updates are accepted only when
Cra.zipcarries an EdDSA signature matchingSUPublicEDKeyinresources/Info.plist. The private key is in the login keychain of the Mac that made it (vendor/sparkle/bin/generate_keys --account cra, made 26 Oct 2026) and in theSPARKLE_PRIVATE_KEYsecret. Back it up (generate_keys --account cra -x <file>): without it, installed copies can never be updated again. - Appcast.
scripts/release.shends withscripts/appcast.sh, which signs the finalCra.zipand writesbuild/dist/appcast.xml; the workflow uploads it with the other assets.CRA_RELEASE_NOTES=<file.html>adds release notes to the update window. - Version numbers. Sparkle compares
CFBundleVersion, the build numberbuild.shtakes from the clock, so every release is newer than the last. - Dev builds have no feed (
build.shdropsSUFeedURLunlessCRA_RELEASE=1), so they never replace themselves with a release. To test, run a copy withCRA_UPDATE_FEED=http://127.0.0.1:8889/appcast.xml(andCRA_UPDATE_IDLE_SECONDS=0for the automatic restart) against a local appcast made withCRA_UPDATE_URL=… scripts/appcast.sh. - Copies from before the updater (0.1.0, 0.1.1) update once by hand: rerun the install line.
The Chromium engine (CEF)
Cra ships its own CEF build, not Spotify's prebuilt one: Spotify builds leave out H.264/AAC, so MP4 and HLS video (X, Instagram, Reddit, news sites) never plays. Codecs are a compile-time switch and FFmpeg is linked into the framework, so there is no way around building it.
scripts/build-cef.sh # ~80 GB free, several hours; resumes where it stopped
scripts/publish-cef.sh # uploads the archive as pre-release cef-<version>-codecsN
build-cef.sh checks out the same CEF commit fetch-cef.sh pins, applies
scripts/cef-patches/*.patch on top of CEF's own patches, and builds an official
release with proprietary_codecs=true ffmpeg_branding=Chrome. fetch-cef.sh (and CI,
keyed on its hash) downloads the published archive into vendor/cef, replacing a copy
from a different source. To change the build without a CEF version bump, bump the
codecsN suffix of CEF_RELEASE and publish again. Needs Xcode's Metal toolchain
(xcodebuild -downloadComponent MetalToolchain).
Patch rounds and Intel. Once build-cef.sh has built a version, a new or changed
patch goes through rebuild-cef.sh, which builds from that checkout for both CPUs
(minutes each) and never reruns CEF's patcher (rerunning it compiles Web Push out). The
Intel (macosx64) build is cross-compiled on the same Mac from the same sources, in its
own out/Release_GN_x64 (~12 GB; the first one compiles everything):
scripts/rebuild-cef.sh [arm64] [x64] # both when no CPU is given
scripts/publish-cef.sh # arm64 asset
CEF_ARCH=macosx64 scripts/publish-cef.sh # Intel asset, same release
Staying current. Chromium only ships security fixes for its newest version. The
"CEF updates" workflow (.github/workflows/cef-updates.yml, daily, free Linux runner)
runs scripts/check-cef-update.sh: when Spotify's index lists a newer stable CEF for
macOS arm64, it opens one "Chromium engine update available" issue, assigned to the repo
owner, with the exact command. The build itself runs on the Mac, because GitHub's free
macOS runners are too small (3 cores, 14 GB disk, 6 hour jobs) and larger ones are billed:
scripts/update-cef.sh <cef_version> # build + publish arm64 and x64, pin, rebuild Cra
A same-major update reuses the checkout: build-cef.sh moves it to the new Chromium tag
itself, and ninja recompiles nearly everything (about 2½ hours on the M2 Max). A new Chromium
major needs a fresh checkout as well. Then test build/Cra.app, commit scripts/fetch-cef.sh, close the
issue and tag a release.
Later
- Homebrew. A cask (
brew install --cask cra) pointing at the DMG andSHA256SUMS.txt. - Intel. CEF is published for
macosx64too (above). Still missing: an x86_64swift buildinscripts/build.sh, a separate Intel DMG from the release workflow and its own Sparkle feed.