System tools > Cocoa-Way

Native macOS Wayland compositor for running Linux GUI apps without VM overhead. Built with Smithay.

Package 841 stars GitHub

Cocoa-Way

Native macOS Wayland compositor for running Linux apps seamlessly

Demo Video • Install • Quick Start • Architecture

Demo Video

True protocol portability: Cocoa-Way rendering Linux apps from OrbStack via Unix sockets.

Features

Feature	Description
Native macOS	Metal rendering
Compositor Zero VM Overhead	Direct Wayland protocol via socket, no virtualization
HiDPI Ready	Optimized for Retina displays with proper scaling
Polished UI	Server-side decorations with shadows and focus indicators
Hardware Accelerated	Efficient Metal rendering pipeline

Installation

Homebrew (Recommended)

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

Download Binary

Download the latest .dmg or .zip from Releases.

Build from Source

# Install dependencies
brew install libxkbcommon pixman pkg-config

# Clone and build
git clone https://github.com/J-x-Z/cocoa-way.git
cd cocoa-way
cargo build --release

Quick Start

⚠️ Required: You must install waypipe-darwin to connect Linux apps.
brew tap J-x-Z/tap && brew install waypipe-darwin

Start the compositor:
```
cocoa-way
```

Connect Linux apps via SSH:

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

Architecture

graph LR
    subgraph macOS
        CW[Cocoa-Way<br/>Compositor]
        WP1[waypipe<br/>client]
    end
  
    subgraph Linux VM/Container
        WP2[waypipe<br/>server]
        APP[Linux App<br/>Firefox, etc]
    end
  
    APP -->|Wayland Protocol| WP2
    WP2 <-->|SSH/Socket| WP1
    WP1 -->|Wayland Protocol| CW
    CW -->|Metal| Display[macOS Display]

Comparison

Solution	Latency	HiDPI	Native Integration	Setup Complexity
Cocoa-Way	⚡ Low	✅	✅ Native windows	🟢 Easy
XQuartz	🐢 High	⚠️ Partial	⚠️ X11 quirks	🟡 Medium
VNC	🐢 High	❌	❌ Full screen	🟡 Medium
VM GUI	🐢 High	⚠️ Partial	❌ Separate window	🔴 Complex

Roadmap

macOS backend (METAL)
Waypipe integration
HiDPI scaling
🚧 Windows backend (win-way)
📱 Android NDK backend (planned)
Multi-monitor support
Clipboard sync

Troubleshooting

SSH: "remote port forwarding failed"

A stale socket file exists on the remote host. Our run_waypipe.sh script handles this automatically with -o StreamLocalBindUnlink=yes.

If running manually:

waypipe ssh -o StreamLocalBindUnlink=yes user@host ...

Contributing

Contributions welcome! Please open an issue first to discuss major changes.

License

Back to Rust