Mac Mini

Overview

Headless Mac turns any Apple Silicon Mac into a Wendy target: install Wendy Agent, point the CLI at it, and deploy native macOS apps with wendy run — same as a Jetson or Pi. Apps run as native macOS processes (not Linux containers), making it a fit for headless Mac mini/Studio servers, mixed WendyOS + Mac fleets, and Core ML / Metal / Neural Engine apps.

Requirements

• An Apple Silicon Mac target running macOS 15 or later
• Wendy CLI on a Mac development machine (Developer Machine Setup) — it builds the app locally before syncing to the target
• A native macOS SwiftPM app project to deploy

If one Mac is both development machine and target, install both the CLI and Wendy Agent on it.

Installation

The recommended path uses Homebrew:

brew tap wendylabsinc/tap
brew install --cask wendy-agent

For the nightly build:

brew install --cask wendy-agent-nightly

Without Homebrew, download the wendy-agent-macos-arm64 zip from the Wendy releases page, unzip it, and move WendyAgentMac.app to /Applications:

open /Applications/WendyAgentMac.app

Wendy Agent appears in the macOS menu bar. Open the menu to confirm the agent is running.

Headless Mac Setup

For any Mac that will run without a monitor, set it up once with a keyboard, mouse, and display attached before putting it on the shelf. Use a virtual display dongle or HDMI dummy plug for the final headless setup.

1. Plug in the virtual display dongle, then open System Settings → Displays and confirm macOS sees it.

2. Open System Settings → Energy Saver and keep the Mac awake on AC power: enable Prevent automatic sleeping when the display is off and Wake for network access.

3. For a MacBook used as a target, open System Settings → Battery → Options, enable Prevent automatic sleeping on power adapter when the display is off, and keep it on AC power.

4. Open System Settings → Lock Screen and set Turn display off on power adapter when inactive to a short interval. The display can sleep; the Mac itself should stay awake.

5. Recommended: open System Settings → General → Sharing and enable Screen Sharing for named trusted admin users so you can administer the Mac remotely.

6. Recommended: in the same Sharing pane, enable Remote Login and set up key-based SSH from your development Mac:

   ssh-copy-id {user}@{hostname}
   ssh {user}@{hostname}

7. When Wendy Agent first opens, leave Open Wendy Agent automatically when you log in enabled.

Verify the Installation

From your development Mac, check that the CLI can reach the Mac target:

wendy --device {hostname}:50051 device info --json

The response should report "os": "darwin" and "cpuArchitecture": "arm64".

Discovery

Headless Mac advertises over Bonjour/mDNS as _wendyos._udp. Use wendy discover to find it on the local network.

Deploying Apps

From a native macOS SwiftPM project configured for a Darwin target:

wendy run --device {hostname}:50051

If you set the Mac as your default device, omit --device:

wendy run

The CLI builds the app on the Mac development machine, syncs the build output to Wendy Agent for Mac, and starts it as a native macOS process. These apps currently run natively on macOS, not inside a Linux-style container.

Homebrew dependencies with Brewfile

Native SwiftPM and Xcode Mac apps can declare Homebrew dependencies with a Brew Bundle Brewfile. Place Brewfile.wendy at the project root for auto-detection, or set a relative path in wendy.json:

{
  "platform": "darwin",
  "brewfile": "ops/Brewfile"
}

wendy run syncs the Wendy Brewfile to the target Mac and Wendy Agent runs brew bundle --file <synced Brewfile> before starting the app. A plain project-root Brewfile can remain dedicated to developer-machine setup; Wendy does not apply it to the target unless wendy.json explicitly references it. Homebrew must already be installed on the target Mac; Wendy reports a clear error if brew is missing or if brew bundle fails. This only applies to native Mac deployments.

What Works

• Apple Silicon Mac targets running macOS 15 or later
• Installing Headless Mac with Homebrew or the release zip
• Deploying native SwiftPM macOS apps with wendy run
• Discovering Mac targets over Bonjour/mDNS
• Setting the Mac as your default Wendy device

Not Supported

• Intel Macs
• Linux container deployment (Dockerfile, Compose)
• Wi-Fi remote provisioning — configure Wi-Fi through macOS network settings
• Bluetooth, audio, and GPU hardware APIs via Wendy
• Wendy camera APIs — use native hardware SDKs (AVFoundation, etc.) directly in your app
• WendyOS OTA updates — update macOS and Wendy Agent through their normal install paths

Troubleshooting

If the CLI cannot connect:

1. Confirm Wendy Agent is open in the menu bar.
2. Run with an explicit device address: wendy --device {hostname}:50051 device info --json
3. If wendy discover doesn't show the Mac, check macOS Local Network permission for the CLI process.
4. Quit and reopen Wendy Agent from the menu bar.
5. If you installed both stable and nightly builds, quit both and open only the one you want.