Build the apps

You can build Hermit from the public repo and run it on your own iPhone or Mac. You need a Mac.

What you need

• macOS 26 and Xcode 26. We use 26.6. The package needs Swift 6.2, so older Xcodes won’t open it.
• XcodeGen. The Xcode project isn’t checked in. XcodeGen writes it from project.yml.
• An Apple developer team, if you want to run it on a device.

Get the code and open it

1. Clone the repo and generate the project.

   git clone https://github.com/Hermit-Ai-Labs/hermit-app && cd hermit-app
   brew install xcodegen
   xcodegen generate        # writes Hermit.xcodeproj from project.yml
   open Hermit.xcodeproj

2. Pick a scheme: Hermit for the Mac, HermitiOS for the iPhone. HermitWidgets builds along with the iPhone app.

3. Sign with your own team. project.yml signs the iPhone targets and the Mac Release build with our team ID, which you can’t use. For each target you want to run, open Signing & Capabilities, pick your team, and change the bundle identifier to one of yours (ours start with my.hermit). The widget’s identifier has to start with the iPhone app’s.

4. Press Run. On first launch the app downloads the model, the same as the one you’d get from us. See first launch.

xcodegen generate rewrites the project, so you’ll pick your team again each time you run it. Or put your team in project.yml.

Mainnet

Your own build is still mainnet. Real swaps move real money, and the same spending policy and Face ID (Touch ID on a Mac) review stand in front of every move.

Build without signing

This is what our CI does on a macos-26 runner (.github/workflows/apple.yml). It’s handy for checking that everything compiles.

Mac

xcodebuild -project Hermit.xcodeproj -scheme Hermit -configuration Release \
  -destination 'generic/platform=macOS' -derivedDataPath build \
  CODE_SIGN_IDENTITY=- CODE_SIGN_STYLE=Manual DEVELOPMENT_TEAM= build

The app lands in build/Build/Products/Release/Hermit.app. It’s ad-hoc signed, so the first time you right-click it and choose Open.

iPhone Simulator

xcodebuild -project Hermit.xcodeproj -scheme HermitiOS -configuration Debug \
  -destination 'generic/platform=iOS Simulator' -derivedDataPath build-ios \
  CODE_SIGNING_ALLOWED=NO build

Keys you’ll want

Builds from the repo don’t carry our shared keys. Those files are gitignored and only go into our TestFlight builds. Without them:

• Private Cloud chat needs your own NEAR AI Cloud key. Add it in Settings, Cloud. You can get one at cloud.near.ai. The enclave check runs without a key.
• NEAR Intents quotes carry 1Click’s extra 0.2% fee, and confidential swaps are off. A 1Click partner key from partners.near-intents.org turns both around. Paste it in the wallet’s Security tab.

Our scripts

They’re in scripts/ and all run on a Mac. Only core-tests.sh is meant for you. The rest expect our team Mac’s folders (~/hermit) and signing keychain, so read them as notes on how we ship.

Script	What it does
bash scripts/core-tests.sh	Runs the non-UI tests without building MLX or SwiftUI. See Run the tests.
zsh scripts/run-iphone.sh [device-id]	Builds a development copy and installs it on a connected iPhone.
zsh scripts/release-mac.sh	Makes the signed, notarized DMG that hermit.my/dmg serves.
zsh scripts/release-mac-appstore.sh	Archives the Mac app for the Mac App Store and uploads it to TestFlight.
zsh scripts/release-ios.sh	Archives the iPhone app and uploads it to TestFlight. With ARCHIVE_ONLY=1 it stops before the upload.
bash scripts/bundle-shared-key.sh	Writes our shared NEAR AI key and 1Click partner key into the bundle, masked, for TestFlight builds. --remove takes them out.
bash scripts/agent-check.sh	Runs the on-device tool loop against a real model folder, outside the app.
zsh scripts/mac-shots.sh, zsh scripts/phone-shots.sh	Take screenshots of every screen from Debug builds.

Release builds get a UTC timestamp as their build number, like 202611102228. That’s how you can tell TestFlight builds apart.

If it doesn’t build

• 'Hermit.xcodeproj' does not exist means you skipped xcodegen generate.
• A signing error on HermitWidgets means its bundle identifier doesn’t start with the app’s, or it still has our team.
• The first build fetches the Swift packages and compiles MLX. It takes a while. Later builds are quicker.