Cocoa-Way runs Linux GUI applications on macOS through a Metal Wayland compositor

Wayland in, Metal out

The mechanism is a protocol translation with a native renderer. Cocoa-Way receives the Wayland protocol on macOS and presents Linux applications through a Metal renderer, and it can connect to an existing Linux machine with Waypipe or manage local GUI applications through Apple Container, Docker and OrbStack. The feature table spells out the rendering side: a native Metal renderer with Retina scaling and damage-aware shared memory uploads. So the Linux application believes it is talking to a Wayland compositor, and on the macOS side what actually draws is Metal through a CAMetalLayer, with the compositor logic built on Smithay. The repository vendors Smithay locally rather than taking it from crates.io, and the version 2.1 notes call out the reason as reduced dependency maintenance, alongside a small reproducible patch set and pinned native window bindings.

Three objects model the whole system

The API is organised around three concepts, and the naming tells you how the author thinks about the problem. An application profile is a saved configuration of image, command, runtime, presentation, audio, mounts and environment settings. An application instance is one running profile with its own process, logs, transport and lifecycle state. A display is either the default compositor window or an isolated display worker assigned to an instance. The separation of profile from instance is the part that matters practically, because it means the same saved configuration can be launched several times as separate instances, each with its own transport and logs, and each with a display assignment. The display concept then supports automatic assignment, named displays, and isolated workers for concurrent applications, which is how two Linux windows can run side by side without sharing a compositor.

Two ways to present an application

Presentation is either Desktop mode or rootless mode, and the distinction is the one most people will care about. Desktop mode is for compositors, presenting a full Wayland session to a macOS window, which is the closest thing to running a Linux desktop inside macOS. Rootless mode is for individual xdg-shell applications, so a single Linux program appears as a native-feeling macOS window. The project also describes itself as a control plane rather than only a renderer, with native runtime panels, a `cocoa-wayctl --json` interface for scripting, diagnostics, tasks, logs and resource warnings. There is an optional read-only MCP server and an onboarding skill for driving it from an assistant, and the automation is deliberately constrained, since launch, stop and deletion remain explicit user actions.

Waypipe over SSH is the simplest path in

For a remote Linux machine, the compatibility script wraps the connection. You start Cocoa-Way, then run the script with the host, the user and the program you want:

./run_waypipe.sh ssh user@linux-host firefox

Waypipe has to be installed on both the Mac and the remote Linux host, and the script checks for the local command and prints the remote requirement before it connects, which saves a failed connection and a manual diagnosis. The same connection can also be created from the Connect to Machine dialog, and saved entries land in the Connections menu and are stored in `~/.config/cocoa-way/connections.toml`, with the reassuring detail that passwords are never stored. The script also supports local Waypipe socket workflows and stays independent of Container Mode, so the remote path does not drag in the container machinery.

Homebrew, a disk image, or cargo

There are three install routes. Homebrew uses a tap that has to be trusted explicitly before the install:

brew tap J-x-Z/tap
brew trust --tap J-x-Z/tap
brew install cocoa-way waypipe-darwin

The `waypipe-darwin` package is required on the Mac for transported applications. The release archive route downloads a `.dmg` or `.zip` from the GitHub releases, and the source route needs libxkbcommon and pkg-config, then a clone and a release build:

brew install libxkbcommon pkg-config
git clone https://github.com/J-x-Z/cocoa-way.git
cd cocoa-way
cargo build --release

The signing situation is stated without hedging: release apps are ad-hoc signed, not Apple-notarised, and if macOS blocks a download the instruction is to review the release and use the Open Anyway path in Privacy and Security rather than disabling Gatekeeper globally. That is the right advice and also a reminder that you are running an unsigned binary.

Apple Container is a separate runtime with a version floor

Apple Container is Apple's own runtime, not bundled with Cocoa-Way, and the README is specific about which version to use. It says to use the latest official release, that the managed workflow has been validated with 1.5.0, and that versions older than 1.4.1 should be avoided because that version fixes OCI image loading and Unix-socket vulnerabilities. It also says Cocoa-Way checks runtime capabilities separately from the version number, which is the sensible design, since a capability check survives a version bump. The runtime is optional when you only use SSH, Docker, OrbStack or an existing local Waypipe socket. The managed workflow has its own steps: select Container, then Apple Container, then Start System and confirm the Compatibility card reports a running service, then pull or import an OCI image, create an application with a presentation mode, run Check, and only then Launch.

What 2.1 actually changed

The release title for 2.1.0 is Desktop Background, and the version notes describe the rest. Version 2.1 adds an opt-in interactive desktop background, event-driven Wayland wakeups, display-aware frame pacing, and bounded transport backpressure. The desktop background is manually enabled, with ordinary macOS applications above it and a restore shortcut, and the demo video for it uses a Niri and DankMaterialShell setup, which the README is careful to say is an optional demo configuration and not a Cocoa-Way dependency or a bundled desktop. The dependency work is what most maintainers would care about: pinned upstream Smithay, a small reproducible patch set, no unused Pixman linkage, and pinned native window bindings. The Cargo manifest shows the pinning style throughout, with exact version requirements on winit, objc2 and its Foundation, Metal, AppKit and Quartz Core companions.

Editorial conclusion

Adopt Cocoa-Way if you want to run Linux GUI applications on macOS, either against a remote host over SSH with Waypipe or locally in a container, and you are prepared to deal with the platform constraints it inherits. Do not adopt it expecting a polished consumer product, since the release artefacts are ad-hoc signed rather than Apple-notarised and the project names a specific Apple Container version it has been validated with. Verify first that you are on macOS 26 with Apple silicon if you plan to use the managed container workflow, that the remote host has a compatible Waypipe server installed, and that the version of Apple Container you use is at or above the version the README recommends.

Frequently asked questions

Official sources

1. Issues
2. J-x-Z/cocoa-way on GitHub
3. License: GPL-3.0
4. README
5. Releases