How to Install and Configure Cocoa-Way on macOS in 2026

Cocoa-Way displays remote or containerized Linux Wayland apps in Mac windows. Linux runs the app, Waypipe moves the display data, and Cocoa-Way handles the Mac side.

We’ll set up both ends, test Rootless mode, and cover Desktop mode for nested compositors. Setup takes 20-30 minutes. App support varies, so keep a VM or XQuartz available.

What Is Cocoa-Way?

Cocoa-Way is a Wayland compositor for macOS. It handles windows, input, and rendering through macOS. Your Mac can’t run an ELF-format Linux binary, so the app needs a Linux host.

Waypipe moves Wayland display data between the Linux app and Cocoa-Way. You need waypipe-darwin on the Mac and waypipe inside Linux. Miss either half and you’ll get an SSH session without a useful window.

Cocoa-Way sits between XQuartz and a full Linux desktop. Compatible Wayland apps get better Mac integration. Results still depend on the app, its toolkit, and the protocols it expects.

Option	Runs	Best fit	Main trade-off
Cocoa-Way	Wayland applications hosted by Linux	Individual Linux apps beside Mac apps	Requires a Linux backend and application compatibility varies
XQuartz	Primarily X11 applications	Older X11-only tools	Does not provide a modern native Wayland compositor
Full Linux VM desktop	A complete Linux desktop	Broad compatibility and desktop-wide workflows	Heavier and less integrated with macOS
Remote desktop	A complete remote session	Administering a whole remote desktop	Usually sends the entire desktop instead of individual app surfaces

Cocoa-Way supports macOS only. There is no supported Windows installation procedure.

Prerequisites

Make sure you have:

• A Mac running macOS 13 Ventura or later
• An administrator account for installing prerequisites
• Homebrew installed
• One Linux backend: a remote host, Apple Container (Apple silicon + macOS 26 or later only), Docker, or OrbStack
• SSH access if you will use a remote Linux host
• waypipe-darwin on macOS and waypipe in Linux
• A Wayland-native Linux test application
• A stable network connection for remote sessions

The commands below use current Homebrew packages and Ubuntu 24.04 LTS for the Linux examples. Fedora, Arch Linux, and other distributions use different package names.

You need Xcode Command Line Tools and Rust 1.75 or later only for a source build. The standard Homebrew install uses compiled packages. That avoids plenty of build troubleshooting.

Step-by-Step Guide

Step 1: Check macOS and Homebrew

Open Applications > Utilities > Terminal, then check the macOS and Homebrew versions:

sw_vers
brew --version

Expected output will resemble:

ProductName: macOS
ProductVersion: 15.x
BuildVersion: 24xxxx

Homebrew 4.x.x

If Terminal returns brew: command not found, follow the official Homebrew install steps before you continue. Homebrew usually lives under /opt/homebrew on Apple silicon and /usr/local on Intel Macs. That difference matters when a shell or script can’t find installed commands.

Step 2: Add the Current Cocoa-Way Homebrew Tap

The project uses the J-x-Z/tap repository. Third-party guides often keep dead tap names long after a project moves. Compare this command with the official README.

brew tap J-x-Z/tap

Expected result:

==> Tapping J-x-Z/tap
Tapped … formulae and … casks

Homebrew versions with trusted-tap support can also run:

brew trust --tap J-x-Z/tap

This command marks the tap as trusted. Some Homebrew releases don’t support or require this step. Skip it if Homebrew rejects the subcommand.

For a downloadable build, check the public Cocoa-Way Releases page. Use the release notes and assets listed there. A version copied into a guide becomes archaeology surprisingly quickly.

Step 3: Install Cocoa-Way and waypipe-darwin

Install both Mac-side packages:

brew install cocoa-way waypipe-darwin

The cocoa-way package provides the compositor. The waypipe-darwin package handles the Mac end of the Waypipe link.

Expected output ends with messages like these:

🍺 cocoa-way was successfully installed!
🍺 waypipe-darwin was successfully installed!

Check that your shell can find both commands:

cocoa-way --help
waypipe-darwin --help

Both commands should print usage details. If either returns command not found, fix the Homebrew path before working on Linux. Debugging two machines at once is an efficient way to waste an afternoon.

Step 4: Start Cocoa-Way

Launch Cocoa-Way from Terminal:

cocoa-way

Leave this process running while you test the connection. Cocoa-Way should open its Mac interface or start the compositor service. It shouldn’t return a fatal error.

If macOS blocks the app, open System Settings > Privacy & Security and find the Cocoa-Way notice. Approve it only if you installed Cocoa-Way from the official tap or project release. Gatekeeper warnings aren’t the place for optimistic clicking.

Step 5: Prepare a Remote Ubuntu Linux Backend

Connect to the Linux machine over SSH:

ssh your-username@linux-host

Install Waypipe and a small Wayland-native test app on Ubuntu 24.04 LTS or Debian:

sudo apt update
sudo apt install waypipe foot

foot is a small terminal with native Wayland support. It starts fast and has few moving parts. That makes it a better first test than Firefox or a full desktop.

Check both programs:

waypipe --version
foot --version

Expected output should include a version for each command. If one is missing, fix the Linux package before checking Cocoa-Way.

Cocoa-Way doesn’t run foot, Firefox, or other Linux binaries on macOS. The binary runs on Linux. Its Wayland surfaces, input events, and session data cross the connection.

Step 6: Connect to Remote Linux with Waypipe

The Cocoa-Way repository includes a run_waypipe.sh helper for compatibility. Download it from the official repository. Place it in a working directory and make it executable:

cd "$HOME/Downloads"
chmod +x ./run_waypipe.sh

Start Cocoa-Way first. Then open a second Mac Terminal window and run:

cd "$HOME/Downloads"
./run_waypipe.sh ssh your-username@linux-host foot

Replace your-username, linux-host, and foot with your SSH account, host address, and app command. The helper checks the local command and reports the remote Waypipe requirement before it connects.

You should get a Linux foot terminal inside a Mac window. On the first SSH connection, check the server’s host-key fingerprint before accepting it. Once the test works, SSH keys remove repeated password prompts.

Step 7: Configure Apple Container as a Local Backend

For a local backend, you’ll need a Mac with Apple silicon running macOS 26 or later – that’s Apple Container’s minimum supported host. Install the latest official Apple Container release with Apple’s instructions, then start Cocoa-Way and open Container > Apple Container.

Click Start System. Wait for the Compatibility card to report that the service is available and running. Stop if it reports a missing runtime or an incompatible host. App settings can’t repair a backend that never started.

Apple Container provides the local Linux system. Cocoa-Way handles the display. The selected Linux image holds the app and its dependencies. You still have two systems to maintain. You’ve only removed the network hop.

Step 8: Create and Validate an Apple Container Application

Open Container > Applications in Cocoa-Way.

• In Images, pull or import an Open Container Initiative (OCI) image, or build the bundled GUI-ready example.
• Create an application entry.
• Select the image and enter the Linux application command.
• Set Presentation to Rootless for an individual application.
• Leave Display set to Auto.
• Click Check and correct any reported image, command, display, or runtime problem.
• Click Launch after validation succeeds.

You should see a running instance with its Linux app open on the Mac. Use Check before each launch while you build the definition. Its errors usually tell you more than a silent window that never appears.

Step 9: Use Rootless Mode for Individual Mac Windows

Choose Rootless when each Linux xdg-toplevel surface needs a separate Mac window. It works well for terminals, editors, and admin tools. Apps that expect to control a full desktop may struggle.

Launch the validated app entry. Check that its window can move, resize, minimize, maximize, and enter fullscreen with the usual Mac controls.

The app still runs inside Linux, but its top-level window joins the Mac desktop. This is Cocoa-Way’s most useful mode for daily work when the app uses standard Wayland behavior.

Step 10: Use Desktop Mode for a Nested Compositor

Choose Desktop when a nested compositor such as niri or Hyprland must control several Linux windows.

In Container > Applications:

• Duplicate or create an application definition.
• Select an image containing the nested compositor and its required packages.
• Set the launch command to the compositor’s documented nested-session command.
• Change Presentation to Desktop.
• Keep Display on Auto initially.
• Click Check, then Launch.

You should get one Cocoa-Way window that contains the nested compositor and its child windows. This layout uses more resources than Rootless mode. Some desktop workloads still need that ownership model.

Hyprland and niri have different graphics, protocol, and runtime needs. Desktop mode provides the right presentation model. A compositor or plugin can still fail if it needs an unsupported protocol or direct hardware access.

Step 11: Inspect and Verify the Running Instance

Return to Container > Applications and select the running instance. Check its status and logs first. Some builds also show terminal access, files, audio, display details, or resource data.

A working setup should meet these checks:

• The instance status remains running.
• Logs do not show a repeated Wayland socket or renderer failure.
• The application window responds to keyboard and pointer input.
• Rootless windows resize correctly, or the Desktop session remains inside one host window.
• Closing the application changes the instance state as expected.

One clean launch isn’t enough. Resize the window, type into it, close it, and launch it again. Display and lifecycle bugs often wait until the second action before introducing themselves.

Docker and OrbStack can also provide the Linux runtime. Install waypipe and the GUI app inside the Linux image or machine. Then expose the required Wayland transport and connect the backend to Cocoa-Way.

Docker and OrbStack are alternative Linux backends. Cocoa-Way remains the compositor. Their controls change between releases, so use each product’s current docs. Don’t assume Cocoa-Way has a dedicated menu for either one.

Configuration

Setting	Recommended use
Presentation: Rootless	One or more Linux apps should behave as separate Mac windows
Presentation: Desktop	A nested compositor must manage several Linux windows
Display: Auto	Best default; lets Cocoa-Way select the display assignment
Manual display	Use only when an app repeatedly targets the wrong socket
Metal renderer	Normal choice on modern Macs; offers direct integration with Apple graphics hardware
OpenGL fallback	Useful on older or incompatible systems, but may be slower or less consistent
Log level	Increase temporarily when diagnosing startup, connection, or rendering failures

Cocoa-Way supports HiDPI output, but one Retina scale won’t suit every app. Apply scaling in one layer when possible. Combining Mac, compositor, and app scaling can produce huge text or blur that looks suspiciously like bad eyesight.

If automatic display selection fails, find the active Cocoa-Way display. Then set WAYLAND_DISPLAY for that Linux launch session:

export WAYLAND_DISPLAY=wayland-0
foot

Replace wayland-0 with the socket reported by your session. Don’t add this export to a global shell profile unless every Wayland app should use that socket. Stale display values can survive reboots, coffee, and several incorrect theories.

Tips and Troubleshooting

No application window appears

Likely cause: Cocoa-Way is stopped, Waypipe is missing on one side, SSH failed, or the app selected the wrong display.

Fix:

• Start cocoa-way on the Mac.
• Run waypipe-darwin --help locally.
• Run waypipe --version on Linux.
• Confirm plain SSH works before involving the GUI application.
• Return Display to Auto.
• Test with a small Wayland-native application such as foot.
• Review Cocoa-Way and instance logs.

Run those checks in order. Fix a basic SSH failure as an SSH problem before Wayland adds three more layers of noise.

Apple Container will not launch an application

Likely cause: Apple Container is missing, its system service is stopped, or the app definition is invalid.

Fix: Open Container > Apple Container, click Start System, and confirm the Compatibility card reports a running service. Then open Container > Applications and select the entry. Click Check, fix each reported problem, and click Launch again.

The application opens on the wrong display

Likely cause: A stale WAYLAND_DISPLAY value or manual display assignment points elsewhere.

Fix: Set Display to Auto and relaunch. For a manual assignment, copy the exact socket reported by the active Cocoa-Way instance. Guessing wayland-0 works until another session claims it.

Retina text is too small, large, or blurry

Likely cause: macOS, the nested compositor, and the app use different scale factors.

Fix: Start with automatic display selection and one scale setting inside the Linux app or desktop. Restart the app after changing it. Test integer scaling first because some toolkits render fractional values poorly.

Remote sessions lag

Likely cause: Waypipe sends display updates over the network. Latency, packet loss, resolution, and app redraw behavior all affect the result.

Fix: Run the same app through Apple Container, Docker, or OrbStack. If the local instance runs smoothly, check the remote link.

Use wired Ethernet when the network is the bottleneck. A reliable USB-C Ethernet adapter, Cat6 cable, and 2.5GbE switch can improve throughput. Bandwidth won’t repair a 70 ms round trip. Apps that redraw large surfaces will also perform worse than a terminal.

Rendering glitches or crashes occur

Likely cause: The app uses an unsupported or changing Wayland protocol. The selected renderer may also have a compatibility problem.

Fix: Test a current GTK4 or Qt6 Wayland app. Try the other presentation mode, inspect the logs, and test the available rendering fallback.

If the failure repeats, report it to the Cocoa-Way issue tracker. Include the macOS version, Linux distribution, app version, presentation mode, renderer, and related logs. Remove hostnames, addresses, paths, and tokens first.

An X11-only application does not open

Likely cause: Cocoa-Way targets Wayland, while the app requires X11.

Fix: Use the app’s Wayland-native build when one exists. Otherwise, use XQuartz or a Linux system with suitable X11 support. Forcing an X11-only tool through a Wayland path adds work without improving the result.

Homebrew uses an old or incorrect tap

Likely cause: The instructions came from an older third-party guide.

Fix: Check the official repository and use the current documented packages:

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

Wrapping Up

Step	Action	Applies To
1	Install Cocoa-Way and waypipe-darwin	macOS
2	Install waypipe and the application	Linux backend
3	Connect over SSH or configure a local container	Remote or local Linux
4	Select Rootless or Desktop and validate	Cocoa-Way
5	Check status, logs, rendering, and scaling	Running session

Cocoa-Way fits when you need compatible Linux Wayland apps beside Mac software. Rootless mode is the useful default. A local container removes network delay once you’ve configured the image.

Keep a VM, XQuartz, or remote desktop ready for apps with X11 dependencies, unusual protocols, or full-desktop assumptions. Cocoa-Way handles conventional Wayland apps well. The fallback covers everything with stronger opinions.