macOS Setup

Overview

YeePilot runs natively on macOS with support for both Intel and Apple Silicon Macs. This guide covers installation, Keychain integration, Gatekeeper permissions, and macOS-specific considerations.

System Requirements

Installation

Quick Install (Recommended)

The install script automatically detects your Mac's architecture and installs the correct binary:

curl -fsSL https://yee.to/install.sh | bash

This will:

1. Detect whether you are on Intel or Apple Silicon.
2. Download the appropriate native binary.
3. Verify the download checksum.
4. Install the binary to /usr/local/bin/yeepilot.

After installation, verify it works:

yeepilot version

Manual Installation

1. Download the correct archive from the releases page (opens in new tab):

   • yeepilot-darwin-amd64.tar.gz for Intel Macs
   • yeepilot-darwin-arm64.tar.gz for Apple Silicon Macs (M1, M2, M3, M4)

2. Extract and install:

tar xzf yeepilot-darwin-arm64.tar.gz
sudo mv yeepilot /usr/local/bin/
sudo chmod +x /usr/local/bin/yeepilot

3. Verify the installation:

yeepilot version

Gatekeeper Permissions

macOS Gatekeeper may block YeePilot the first time you run it because the binary is not signed with an Apple Developer certificate. You will see a message like: "yeepilot" cannot be opened because the developer cannot be verified.

Allow via System Settings

1. Open System Settings (or System Preferences on older macOS).
2. Go to Privacy & Security.
3. Scroll down to the Security section.
4. You should see a message about yeepilot being blocked. Click Allow Anyway.
5. Run yeepilot version again and click Open in the confirmation dialog.

Allow via Terminal

Alternatively, remove the quarantine attribute directly:

xattr -d com.apple.quarantine /usr/local/bin/yeepilot

This only needs to be done once. Subsequent updates may require repeating this step.

Initial Setup

Run the interactive setup to configure your AI provider:

yeepilot setup

This creates your configuration file at ~/.yeepilot/config.yaml.

Credential Storage

YeePilot automatically uses the macOS Keychain to store API keys and authentication tokens. This provides secure, encrypted storage that integrates with your system login.

• Credentials are stored in the default login keychain.
• You may see a Keychain Access prompt the first time YeePilot stores or retrieves a credential. Click Always Allow to avoid repeated prompts.
• Credentials are labeled with yeepilot in Keychain Access for easy identification.

Viewing Stored Credentials

Open Keychain Access (in Applications > Utilities) and search for yeepilot to see stored credentials.

No Additional Setup Required

Unlike Linux, no additional packages are needed for credential storage on macOS. The Keychain is available on all macOS installations.

Sandbox Limitations

macOS does not support Linux kernel namespaces. YeePilot uses process-level resource limits instead, which provide basic isolation:

• CPU time limits -- Commands are terminated if they exceed the configured CPU time.
• Memory limits -- Process memory is capped at the configured maximum.
• File size limits -- Individual file creation is limited.

To configure sandbox settings:

# ~/.yeepilot/config.yaml
sandbox:
  enabled: true
  use_namespaces: false  # Not available on macOS, automatically disabled
  max_cpu_seconds: 300
  max_memory_mb: 512
  max_filesize_mb: 100
  max_processes: 64

Note that use_namespaces is automatically set to false on macOS regardless of the configuration value. There is no action required on your part.

For full namespace isolation, consider running YeePilot inside a Linux virtual machine or Docker container on your Mac.

Apple Silicon Notes

YeePilot provides a native arm64 binary for Apple Silicon Macs (M1, M2, M3, M4 series). This runs without Rosetta 2 translation, ensuring optimal performance.

To confirm you are running the native binary:

file $(which yeepilot)

You should see output containing arm64 for Apple Silicon or x86_64 for Intel.

If you accidentally installed the Intel version on an Apple Silicon Mac, it will still work through Rosetta 2, but reinstalling with the correct architecture is recommended:

curl -fsSL https://yee.to/install.sh | bash

The install script always detects and installs the correct architecture.

Terminal Recommendations

YeePilot's TUI works best with terminals that support:

• 256 colors or true color -- For proper theme rendering.
• Unicode -- For box-drawing characters and status indicators.
• Resizing -- The TUI adapts to terminal size changes.

All popular macOS terminals work well:

Updating

Update to the latest version:

yeepilot update

You may need to re-allow the binary in Gatekeeper after an update (see the Gatekeeper Permissions section above).

Uninstalling

Remove YeePilot and all its data:

yeepilot uninstall --all

Or remove only the binary while keeping your configuration:

yeepilot uninstall --binary-only

For a manual removal:

sudo rm /usr/local/bin/yeepilot
rm -rf ~/.yeepilot

Stored Keychain entries can be removed manually through Keychain Access by searching for yeepilot and deleting the matching entries.