Apple Silicon Macs

Running XHack on Apple Silicon

A native arm64 build is not available yet. We are working on it.

The current macOS release (xhack-mac.tar.gz) is an x86_64 build. On an M1, M2, M3 or M4 Mac it runs through Rosetta 2, Apple's x86_64 translation layer. Everything works, you just need Rosetta present first.

The GUI would normally offer to install Rosetta on first launch. The CLI does not: it fails with Bad CPU type in executable. So install Rosetta before the installer, not after.

Requirements: macOS 12 or later, and about 200 MB of download.

1. Install Rosetta 2

Skip if you already have it.

softwareupdate --install-rosetta --agree-to-license

Add sudo if it complains about privileges. Drop --agree-to-license if you want to read Apple's licence rather than accept it inline.

2. Verify Rosetta

arch -x86_64 uname -m

Should print x86_64. If you get Bad CPU type in executable, step 1 did not complete.

3. Run the installer

curl -sSL https://xhack.io/cdn/xhack-ai/installer/install-mac.sh | bash

If you would rather read it before running it (reasonable, given the audience):

curl -sSL https://xhack.io/cdn/xhack-ai/installer/install-mac.sh -o install-mac.sh
less install-mac.sh
bash install-mac.sh

What the installer actually does

Worth knowing before you pipe it into a shell.

Step	Detail
Version check	Reads version.json for the current release, falls back to latest if unreachable
Download	xhack-mac.tar.gz, roughly 195 MB, with retries
Install location	/Applications/XHack AI.app if writable, otherwise ~/Applications/XHack AI.app. No sudo either way
CLI symlink	/usr/local/bin/xhack if writable, otherwise ~/.local/bin/xhack
PATH	Only touched in the fallback case: appends an export PATH line to ~/.zshrc, ~/.bashrc or ~/.profile depending on $SHELL
Quarantine	xattr -dr com.apple.quarantine on the bundle
Signature	codesign --deep --force --sign -, an ad hoc signature

An existing XHack AI.app at the destination is removed before the new one is copied in. Your account and settings live server side, so nothing local is lost.

4. Launch

xhack

Or open the bundle directly:

open "/Applications/XHack AI.app"

Sign in with the same account you use at app.xhack.io. That links the machine to your workspace and plan.

If xhack is not found, you hit the ~/.local/bin fallback and your shell has a stale PATH. Start a new shell or source ~/.zshrc.

5. Confirm it is the x86_64 build

file "/Applications/XHack AI.app/Contents/MacOS/xhack-bin"

Expect Mach-O 64-bit executable x86_64. Activity Monitor will show the process Kind as Intel while it is running. Both are expected until the arm64 build lands.

Updating and removing

# update, with backup and automatic rollback on failure
curl -sSL https://xhack.io/cdn/xhack-ai/installer/upgrade-mac.sh | bash

# remove app, CLI symlink, PATH entries and config
curl -sSL https://xhack.io/cdn/xhack-ai/installer/uninstall-mac.sh | bash

The upgrade command is also how you will move to the native build when it ships. Rosetta itself is part of macOS and is left alone by the uninstaller.

Troubleshooting

Symptom	Cause	Fix
Bad CPU type in executable	Rosetta missing	Step 1, confirm with step 2
zsh: command not found: xhack	~/.local/bin fallback, stale PATH	New shell, or source ~/.zshrc
ERROR: This installer is for macOS only	Ran install-mac.sh off Darwin	Use install.sh on Linux
App is in ~/Applications, not /Applications	/Applications was not writable	Expected, and fine. Move it manually and re run codesign --deep --force --sign - if you want it system wide
Gatekeeper complains anyway	Bundle was moved or edited after signing, breaking the ad hoc signature	Re run the installer
Download stalls	Network or proxy	Retry, or fetch xhack-mac.tar.gz directly and extract by hand

Still stuck?

Ask in the XHack Discord for a quick answer, or open a support ticket at support@xhack.io. Either way, include:

• The exact error text, copied rather than described
• Output of sw_vers and uname -m
• Output of arch -x86_64 uname -m
• Where the app landed, /Applications or ~/Applications

That is usually enough for us to answer on the first reply.

Notes

Performance. Translation happens once per code path and is cached. XHack spends most of its time on network calls and model inference, so the practical overhead is small. Local heavy lifting is where you would notice it.

When is arm64 coming? Actively in progress, no date announced yet. This page gets updated when it ships. Apple has signalled Rosetta 2 will be wound down in future macOS releases, so a native build is a requirement rather than a nice to have.

Related

• Installation, the Agent in general
• Getting Started
• Prompting Guide
• Capabilities and Use Cases