macos apple silicon - nself-org/cli GitHub Wiki

macOS Apple Silicon (arm64) Install Guide

Install the ɳSelf CLI natively on Apple M-series Macs (M1, M2, M3, M4). No Rosetta required.

Contents

Why arm64-native matters

The ɳSelf CLI ships a dedicated darwin-arm64 binary in every release. Running the arm64 build on Apple Silicon gives you:

  • Full use of the M-series performance and efficiency cores with no translation overhead
  • Correct file output: Mach-O 64-bit executable arm64 (not x86_64)
  • Compatibility with Docker Desktop for Apple Silicon containers
  • Homebrew's brew install selects the arm64 bottle automatically on M-series hardware

If you previously installed an x86_64 build under Rosetta, uninstall it first (brew uninstall nself) and follow this guide to get the native binary.

Prerequisites

  • macOS 11 Big Sur or later (macOS 12 Monterey or later recommended)

  • Apple M-series chip (M1, M2, M3, or M4, any variant)

  • Homebrew installed for Apple Silicon (prefix /opt/homebrew). If you are unsure, run:

    brew --prefix

The output must be /opt/homebrew. If it is /usr/local, your Homebrew is running under Rosetta. Reinstall Homebrew natively before continuing.

After installing Docker Desktop, confirm it is running and that the engine is reachable:

docker info --format '{{.Architecture}}'

Expected output: aarch64

Step 1: Add the Homebrew tap

brew tap nself-org/nself

This registers the official ɳSelf tap. You only need to do this once per machine.

Step 2: Install nself

brew install nself

Homebrew downloads the darwin-arm64 bottle, verifies the sha256 checksum, and places the binary on your PATH. No manual download or architecture selection is needed.

Step 3: Verify architecture

Confirm the installed binary is the native arm64 build:

file $(which nself)

Expected output:

/opt/homebrew/bin/nself: Mach-O 64-bit executable arm64

If the output shows x86_64 instead of arm64, your Homebrew is running under Rosetta. Follow the Homebrew Apple Silicon reinstall guide, then repeat Steps 1 and 2.

Step 4: Verify version

nself version

Expected output:

nself version 1.0.9

Step 5: Run your first project

nself init my-project
cd my-project
nself start

nself init creates the project directory and .env.dev. nself start boots the full stack (Postgres, Hasura, Auth, Nginx) using Docker Desktop. The first run pulls container images and may take a few minutes depending on your connection.

Once started, nself urls shows the local endpoints for your project.

Troubleshooting

Docker Desktop memory and CPU for M-series

Docker Desktop on Apple Silicon shares the macOS unified memory pool. The default allocation may be too low for a full ɳSelf stack.

Recommended settings (Docker Desktop Preferences > Resources):

Resource Minimum Recommended
CPU cores 2 4
Memory 4 GB 8 GB
Disk image size 20 GB 60 GB

After changing these settings, click "Apply and restart" in Docker Desktop.

sha256 validation error from Homebrew

If brew install nself fails with a checksum mismatch, your local Homebrew formula cache may be stale. Refresh it:

brew update
brew install nself

If the error persists, check github.com/nself-org/homebrew-nself for any open issues on the current release.

Gatekeeper quarantine on first run

macOS Gatekeeper may block the binary the first time you run it if Homebrew's bottle was not notarized. To clear the quarantine attribute:

xattr -d com.apple.quarantine $(which nself)

Then re-run nself version to confirm the binary executes.

nself start hangs or times out

If containers fail to start, check Docker Desktop is running and the engine is responsive:

docker ps

If Docker is running but nself start still hangs, increase the memory allocation (see above) and retry. Use nself logs to inspect service output for a specific error.

Related