# How to Run Palmier Pro Locally: Complete macOS Setup Guide

> Learn to run Palmier Pro locally on macOS. Follow this guide to clone the repository, build with Swift, and launch a debug build with live log streaming for efficient development.

- Repository: [Palmier/palmier-pro](https://github.com/palmier-io/palmier-pro)
- Tags: how-to-guide
- Published: 2026-06-30

---

**Clone the repository, run `swift build`, then execute [`./scripts/dev.sh`](https://github.com/palmier-io/palmier-pro/blob/main/./scripts/dev.sh) to launch a debug build with live log streaming on macOS 26.**

Palmier Pro is an AI-native macOS video editor built with Swift 6.2, SwiftUI, and AVFoundation. To run the Palmier Pro project locally, you need a Swift Package Manager-based workflow that compiles the executable target, builds Metal shaders via a custom plugin, and bundles resources for the GPU-accelerated video pipeline.

## Prerequisites for Local Development

Before attempting to run Palmier Pro locally, ensure your development environment meets the following requirements:

- **macOS 26 (Tahoe)** on Apple Silicon – The [`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift) specifies `.macOS(.v26)` as the minimum platform target.
- **Xcode 16 or later** – Required for the Swift 6.2 toolchain and macOS SDK support.
- **Command-line tools** – Verify `swift`, `git`, and `bash` are available in your `$PATH`.

The app cannot run on Intel Macs or macOS versions earlier than 26 due to platform-specific APIs and Swift 6.2 dependencies.

## Clone the Palmier Pro Repository

Download the source code from the `palmier-io/palmier-pro` repository:

```bash
git clone https://github.com/palmier-io/palmier-pro
cd palmier-pro

```

This creates a local copy of the Swift package, including the `Sources/PalmierPro` directory containing the UI and video editing logic, as well as the `Metal/` directory for GPU kernels.

## Build and Run Palmier Pro Locally

You have three primary methods to compile and launch the application. Choose based on whether you need a quick test or a full debuggable bundle.

### Option 1: Quick Swift Build

For rapid iteration without bundling, use Swift Package Manager directly:

```bash
swift build
swift run PalmierPro

```

**What happens:** `swift build` reads [`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift), resolves dependencies (MCP, Sparkle, Sentry, Clerk, Convex, Tokenizers, Lottie), and compiles the executable. The `MetalCIKernelPlugin` automatically builds `.metallib` files from sources in `Metal/` before linking. `swift run` executes the binary from `.build/debug/PalmierPro`.

### Option 2: Debug Bundle with Log Streaming (Recommended)

For development with console visibility into OSLog messages, use the provided helper script:

```bash
./scripts/dev.sh

```

To disable the log stream and launch only:

```bash
./scripts/dev.sh --no-stream

```

**What happens:** The [`scripts/dev.sh`](https://github.com/palmier-io/palmier-pro/blob/main/scripts/dev.sh) script invokes `scripts/bundle.sh debug --fast` to assemble `.build/PalmierPro.app`, injects a minimal `Info.plist`, performs ad-hoc code signing, and launches the app. While running, it streams logs matching the subsystem `io.palmier.pro` to your terminal, making it ideal for debugging the MCP server (running on `127.0.0.1:19789`) or video pipeline issues.

### Option 3: Run the Test Suite

Validate functionality before running the full application:

```bash
swift test

```

This executes the `PalmierProTests` target, covering video project loading, caption handling, AI tool integration, and UI behaviors.

## Understanding the Local Build Architecture

To troubleshoot effectively, understand how the components interact:

- **[`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift)** – Defines the executable product `PalmierPro`, declares third-party dependencies, and registers the `MetalCIKernelPlugin` as a build-tool plugin for GPU-accelerated effects.
- **[`Plugins/MetalCIKernelPlugin/MetalCIKernelPlugin.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Plugins/MetalCIKernelPlugin/MetalCIKernelPlugin.swift)** – Compiles `.metal` source files (e.g., for Vignette and HueCurves effects) into `.metallib` libraries during the build process.
- **`Sources/PalmierPro/`** – Contains SwiftUI views, AppKit integrations, AVFoundation video logic, and bundled resources (fonts, images, Lottie files, MCP bundles).
- **[`scripts/bundle.sh`](https://github.com/palmier-io/palmier-pro/blob/main/scripts/bundle.sh)** – Handles resource copying, app bundle structure creation, and code signing.

## Troubleshooting Common Local Build Issues

| Issue | Cause | Solution |
|-------|-------|----------|
| **"requires macOS 26"** build error | Running on older macOS version | Upgrade to macOS 26 (Tahoe) or use a compatible VM |
| **Missing Metal shaders** (`.metallib` not found) | Plugin execution failed | Clean build with `swift package clean` then rebuild; verify `MetalCIKernelPlugin` runs during build |
| **Launch crash with missing key errors** | `Info.plist` variables (e.g., `CLERK_PUBLISHABLE_KEY`) undefined | For local development, these warnings are non-fatal unless you access those specific code paths; production builds require proper keys |
| **"Command not found: log"** when streaming | macOS version predates the `log` CLI (introduced in macOS 12) | Run with `--no-stream` flag or upgrade macOS |

## Summary

- **Requirements:** macOS 26, Xcode 16, Apple Silicon Mac.
- **Clone:** `git clone https://github.com/palmier-io/palmier-pro`.
- **Quick run:** `swift build && swift run PalmierPro`.
- **Development:** [`./scripts/dev.sh`](https://github.com/palmier-io/palmier-pro/blob/main/./scripts/dev.sh) for debug bundles with log streaming.
- **Testing:** `swift test` to verify functionality.
- **Architecture:** The `MetalCIKernelPlugin` in `Plugins/` is essential for GPU effects, while [`scripts/bundle.sh`](https://github.com/palmier-io/palmier-pro/blob/main/scripts/bundle.sh) handles app packaging.

## Frequently Asked Questions

### What are the exact system requirements to run Palmier Pro locally?

You need **macOS 26 (Tahoe)** running on **Apple Silicon** (M1 or later), plus **Xcode 16** for the Swift 6.2 toolchain. The [`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift) explicitly targets `.macOS(.v26)`, and the codebase uses Swift 6.2 features unavailable in earlier versions. Intel-based Macs are not supported.

### Why does the build fail with "requires macOS 26"?

This error occurs when your host system is running macOS 15 or earlier. The [`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift) manifest declares a platform requirement that Swift Package Manager enforces strictly. You must upgrade to the macOS 26 developer beta or final release, or use a remote build environment that supports the required SDK.

### How do I debug Palmier Pro if it crashes on launch?

Run the [`./scripts/dev.sh`](https://github.com/palmier-io/palmier-pro/blob/main/./scripts/dev.sh) command without the `--no-stream` flag to capture OSLog output in real-time. Look for subsystem `io.palmier.pro` messages that indicate where the initialization fails. Common causes include missing Metal shader libraries (ensure the `MetalCIKernelPlugin` completed successfully) or missing API keys for services like Clerk or Sentry, though the app typically handles missing keys gracefully in debug builds until those specific features are accessed.

### Can I run Palmier Pro on Intel Macs?

No. The project is configured for Apple Silicon architectures only, and dependencies such as the Metal compute shaders and specific AVFoundation optimizations require ARM64. Attempting to build on Intel hardware will fail during the compilation phase or produce non-functional binaries.