macOS Build Guide

April 3, 2026 · View on GitHub

Alpha: The ESF+NE build path is in Alpha. Build steps, signing requirements, and bundle structure may change between releases.

This guide covers building agentsh for macOS using ESF (Endpoint Security Framework) + NE (Network Extension).

Install via Homebrew

The easiest way to install on macOS:

brew tap canyonroad/tap
brew install --cask agentsh

After installation, approve the system extension in System Settings > General > Login Items & Extensions.

Build Modes

ModeSecurity ScoreRequirementsUse Case
ESF+NE90%Xcode 15+Full enforcement (Alpha)
Observation25%NoneTesting, audit-only

ESF+NE Build (Enterprise — Alpha)

ESF+NE provides near-Linux-level enforcement using Apple's Endpoint Security Framework and Network Extension. This build path is in Alpha — expect manual setup steps and breaking changes between releases.

Prerequisites

  1. Xcode 15+ - For building Swift components
  2. Code signing identity - Developer ID or Apple Development certificate
  3. Provisioning profile - With ESF and Network Extension entitlements

Verify Prerequisites

# Check Xcode version
xcodebuild -version
# Should be 15.0 or higher

# Check Swift version
swift --version
# Should be 5.9 or higher

# List code signing identities
security find-identity -v -p codesigning

Build Steps

1. Build Go Binary for macOS

# Build for Apple Silicon (arm64)
make build-macos-go

# This creates:
# - build/AgentSH.app/Contents/MacOS/agentsh (arm64)
# - build/AgentSH-amd64.app/Contents/MacOS/agentsh (amd64)

2. Build Swift Components

# Build System Extension and XPC Service
make build-swift

# This builds:
# - ai.canyonroad.agentsh.sysext.systemextension
# - ai.canyonroad.agentsh.xpc.xpc

3. Assemble App Bundle

# Combine Go + Swift into app bundle
make assemble-bundle

4. Sign the Bundle

# Sign with your Developer ID
SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)" make sign-bundle

# Or for development
SIGNING_IDENTITY="Apple Development" make sign-bundle

Full Enterprise Build

# One-command build (requires all prerequisites)
SIGNING_IDENTITY="Developer ID Application" make build-macos-enterprise

Output Structure

build/AgentSH.app/
├── Contents/
│   ├── Info.plist
│   ├── MacOS/
│   │   └── agentsh                    # Go binary
│   ├── Library/
│   │   └── SystemExtensions/
│   │       └── ai.canyonroad.agentsh.sysext.systemextension/
│   │           ├── Contents/
│   │           │   ├── MacOS/
│   │           │   │   └── ai.canyonroad.agentsh.sysext  # ESF + NE
│   │           │   └── Info.plist
│   └── XPCServices/
│       └── ai.canyonroad.agentsh.xpc.xpc/
│           ├── Contents/
│           │   ├── MacOS/
│           │   │   └── ai.canyonroad.agentsh.xpc  # XPC bridge
│           │   └── Info.plist

System Extension Approval

After installing the ESF+NE app bundle, users must approve the System Extension:

  1. First launch - macOS will prompt "System Extension Blocked"
  2. Open System Settings > General > Login Items & Extensions
  3. Allow the agentsh System Extension
  4. Restart may be required for Network Extension activation

This is a one-time approval per machine.

Graceful Fallback

The ESF+NE binary automatically detects available entitlements:

  1. With ESF + NE entitlements - Uses ESF for file/process, Network Extension for network
  2. Without entitlements - Falls back to observation-only mode

No code changes required - fallback is automatic at runtime.

Troubleshooting

Build Errors

"Xcode not found"

xcode-select --install
sudo xcode-select -s /Applications/Xcode.app

"No signing identity found"

# List available identities
security find-identity -v -p codesigning

# Use a valid identity
SIGNING_IDENTITY="Apple Development: you@email.com (TEAMID)" make sign-bundle

"Entitlement not allowed"

  • Verify the provisioning profile is embedded in the app bundle
  • Network Extension is a standard capability - enable in Xcode Signing & Capabilities

Runtime Errors

"System Extension blocked"

  • User must approve in System Settings > General > Login Items & Extensions

"XPC connection failed"

  • Verify System Extension is approved and running
  • Check Console.app for XPC errors

"ESF client initialization failed"

  • App must be signed with valid ESF entitlement and provisioning profile
  • Check code signing: codesign -dv --entitlements - AgentSH.app

Cross-Compilation

Building macOS binaries from Linux (Go only, not Swift):

# For Apple Silicon
GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 go build -o agentsh-darwin-arm64 ./cmd/agentsh

# For Intel Mac
GOOS=darwin GOARCH=amd64 CGO_ENABLED=0 go build -o agentsh-darwin-amd64 ./cmd/agentsh

Note: CGO_ENABLED=0 means no ESF support. The binary will run in observation-only mode. Swift components (ESF+NE) must be built on macOS.

See Also