# How to Set Up Palmier Pro Locally: Complete macOS Build Guide

> Set up Palmier Pro locally on your macOS device with Apple Silicon. Follow this complete build guide to quickly clone the repository and launch the app.

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

---

**Clone the repository, ensure you have macOS 26 (Tahoe) on Apple Silicon with Xcode 16+, then run [`./scripts/dev.sh`](https://github.com/palmier-io/palmier-pro/blob/main/./scripts/dev.sh) to build the debug bundle and launch the app.**

Palmier Pro is an open-source, Swift-native video editor designed exclusively for macOS 26 (Tahoe) running on Apple Silicon. Setting up Palmier Pro locally requires the Swift 6.2 toolchain and a standard **Swift Package Manager (SPM)** workflow to compile the executable target into a macOS `.app` bundle.

## Prerequisites for Local Development

Before building Palmier Pro locally, verify your environment meets these strict requirements:

- **macOS 26+ (Tahoe) on Apple Silicon** – The project targets macOS 26 explicitly and requires Apple Silicon architecture according to the [`README.md`](https://github.com/palmier-io/palmier-pro/blob/main/README.md) at lines 11-13.
- **Xcode 16+ with Swift 6.2 toolchain** – Required for compilation as specified in [`CONTRIBUTING.md`](https://github.com/palmier-io/palmier-pro/blob/main/CONTRIBUTING.md) lines 12-14.
- **Internet connectivity** – SPM must fetch dependencies from GitHub during the initial build.

## Clone and Build the Repository

Start by cloning the repository and verifying your Swift toolchain version:

```bash
git clone https://github.com/palmier-io/palmier-pro.git
cd palmier-pro
swift --version  # Should report Swift 6.2

```

Compile the project using Swift Package Manager. The [`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift) file declares the executable target and platform constraints at lines 5-22:

```bash
swift build

```

To run the binary directly without bundling:

```bash
swift run PalmierPro

```

## Development Workflow with Debug Scripts

For rapid iteration, use the provided helper scripts rather than manual builds. The [`scripts/dev.sh`](https://github.com/palmier-io/palmier-pro/blob/main/scripts/dev.sh) file automates building a debug bundle, launching the app, and streaming OSLog output.

Execute the development script:

```bash
./scripts/dev.sh

```

This script internally calls `scripts/bundle.sh debug --fast` to produce a fast-debug bundle, then opens `.build/PalmierPro.app` and streams logs for debugging. To launch without log streaming:

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

```

## Understanding the Project Structure

Key architectural components impact how you navigate and modify the codebase:

### Centralized UI Styling

All visual constants live in [`Sources/PalmierPro/UI/AppTheme.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/UI/AppTheme.swift). Every view imports `AppTheme` to reference standardized colors, spacing, fonts, and shadows, avoiding hard-coded values across the UI. The file defines constants like [`AppTheme.Spacing.md`](https://github.com/palmier-io/palmier-pro/blob/main/AppTheme.Spacing.md), `AppTheme.Background.raisedColor`, and `AppTheme.Radius.sm` at lines 4-30.

### MCP Server Integration

When Palmier Pro launches, it starts an HTTP MCP server at `http://127.0.0.1:19789/mcp`. This enables AI agents (Claude, Codex, Cursor) to interact with the video timeline programmatically. The server implementation resides under `Sources/PalmierPro/` and leverages the `swift-sdk` dependency.

### Build Configuration

The [`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift) file manages several critical build aspects:

- **Dependencies** – Third-party packages including DSWaveformImage (audio waveforms), Sparkle (auto-updates), Sentry (crash reporting), Clerk (authentication), and Convex (backend).
- **Metal Shaders** – The `MetalCIKernelPlugin` compiles `.metal` shader files (e.g., `Vignette.metal`, `Grain.metal`) declared in the target's plugins array at lines 49-51.
- **Resources** – Fonts, images, and MCP bundles are packaged via the `resources` array at lines 43-48.

## Running the Test Suite

Validate your local setup by executing the unit tests:

```bash
swift test

```

This runs the full test suite located in the `Tests/` directory to ensure all modules compile and function correctly on your machine.

## Troubleshooting Common Setup Issues

| Symptom | Likely Cause | Solution |
|---------|--------------|----------|
| Build fails with toolchain errors | Xcode version older than 16 | Install Xcode 16+ or select the correct Swift 6.2 toolchain |
| `swift build` hangs indefinitely | Network proxy blocking GitHub | Ensure outbound HTTPS to `github.com` is allowed for SPM |
| App crashes on launch | Code signing or entitlements | Run the built `.app` directly from `.build/`; the project is non-sandboxed |
| No log output in terminal | OSLog streaming disabled | Use [`./scripts/dev.sh`](https://github.com/palmier-io/palmier-pro/blob/main/./scripts/dev.sh) without the `--no-stream` flag |

## Summary

- **Palmier Pro requires macOS 26 (Tahoe) on Apple Silicon** and Xcode 16+ with Swift 6.2 to build locally.
- Use [`./scripts/dev.sh`](https://github.com/palmier-io/palmier-pro/blob/main/./scripts/dev.sh) for the fastest development workflow, which handles debug builds, bundling, and log streaming automatically.
- The project uses **Swift Package Manager** exclusively; no CocoaPods or Carthage required.
- UI styling is centralized in [`Sources/PalmierPro/UI/AppTheme.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/UI/AppTheme.swift) for consistent design across views.
- The built-in MCP server starts automatically on port 19789 for AI agent integration.
- Metal shaders compile automatically via the `MetalCIKernelPlugin` during the build process.

## Frequently Asked Questions

### Can I run Palmier Pro on an Intel Mac or older macOS version?

No. According to the source code in [`README.md`](https://github.com/palmier-io/palmier-pro/blob/main/README.md) lines 11-13, Palmier Pro strictly requires **macOS 26 (Tahoe) running on Apple Silicon**. The codebase uses APIs and Swift 6.2 features incompatible with older macOS versions or Intel architecture.

### What is the MCP server used for in local development?

The MCP (Model Context Protocol) server runs at `http://127.0.0.1:19789/mcp` when the app launches, enabling AI coding assistants like Claude, Codex, or Cursor to read and manipulate the video timeline programmatically. This facilitates AI-powered editing workflows directly within the Palmier Pro interface.

### How are the Metal shaders compiled during the build process?

The [`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift) file includes a custom build-tool plugin called `MetalCIKernelPlugin` at lines 49-51. This plugin automatically compiles `.metal` shader files located in the `Metal/` directory (such as `Vignette.metal` and `Grain.metal`) during the Swift build process, embedding them as resources in the final `.app` bundle.

### Why does `swift build` fail with missing dependency errors?

SPM requires internet access to fetch dependencies like DSWaveformImage, Sparkle, and Sentry from GitHub. If the build hangs or fails with resolution errors, verify your network connection allows HTTPS traffic to `github.com`. Initial builds may take several minutes to download and compile all external packages.