GitHub - themartiano/try-omarchy: Run Omarchy on MacOS without any setup.
Run the upstream Omarchy desktop as a native, hardware-accelerated app on an Apple Silicon Mac.
Try Omarchy packages a project-built ARM64 Arch Linux image configured with Omarchy Quattro, a QEMU runtime using Apple Hypervisor Framework, and a small Swift/AppKit launcher into one macOS app. The image is built from pinned Arch Linux ARM packages and a pinned revision of the upstream Omarchy source. Temporary fixes carried ahead of the next upstream release are enumerated with strict hashes in the guest build spec and artifact provenance.
 Try Omarchy is not official or affiliated with Omarchy.
Highlights
[](https://github.com/themartiano/try-omarchy#highlights)
- Hardware-accelerated ARM64 virtualization and VirGL graphics
- Resizable native window with automatic guest resolution and HiDPI scale updates
- Mac audio input/output selection inside Omarchy, with live routing and system-default fallback
- Two-way clipboard sharing for text and PNG images between macOS and Omarchy
- One optional shared Mac folder, available inside Omarchy under the same name (`~/Work` stays `~/Work`)
- Loopback-only TCP and UDP port forwarding from the Mac into Omarchy
> **Current limitation:** Video decoding is CPU-only, so playback can be slow, especially at high resolutions. An improved video path is in development.
Quick start
[](https://github.com/themartiano/try-omarchy#quick-start) 1. Open Releases and download the latest signed and notarized `.dmg`. 2. Open the DMG and drag **Try Omarchy** to **Applications**. 3. Launch **Try Omarchy** from Applications.
Every launch begins at the start menu. **Immersive** is on by default and its caption explains how to leave Full Screen. Turn it off to keep Omarchy full screen while letting the Mac menu bar and Dock appear at the screen edges. Accessibility enables Mac Command-to-guest-Super shortcuts; microphone access is optional. The first launch takes longer while the app prepares Linux and starts Omarchy's account provisioning.
Restarting from inside Omarchy reboots the guest in the same Try Omarchy app. Shutting down Omarchy closes the app and leaves it closed.
Clipboard sharing
[](https://github.com/themartiano/try-omarchy#clipboard-sharing)
Copy and paste work in both directions as soon as you sign in to Omarchy: text and PNG images copied on the Mac appear in the Omarchy clipboard, and content copied in Omarchy lands on the Mac pasteboard. Nothing is transferred until something is copied.
Sharing a folder with the Mac
[](https://github.com/themartiano/try-omarchy#sharing-a-folder-with-the-mac)
Folder sharing is off until you pick a folder. Use **Choose…** next to **Shared folder** on the start menu to select one Mac folder; Omarchy links it into its home under the same name (`~/Work` on the Mac becomes `~/Work` in Omarchy) with full read and write access, so choose a folder you intend Linux software to modify. The whole home folder, `~/Library`, and system directories cannot be shared. **Turn Off** keeps the choice but stops exporting it on the next launch; Omarchy then removes the link and gives back any standard folder such as `~/Documents` that the link had taken over. The share belongs to the first Omarchy account created during provisioning. Additional guest accounts can reach the same share, with each entry's normal Unix permission bits deciding whether they can modify it.
Forwarding ports to Omarchy
[](https://github.com/themartiano/try-omarchy#forwarding-ports-to-omarchy)
Use **Configure…** next to **Port forwarding** on the start menu to map a Mac localhost port to a service port in Omarchy. Each mapping can use TCP or UDP; the same Mac port may be used once for each protocol. Forwarded ports bind only to `127.0.0.1`, so other devices on the network cannot connect to them. The service inside Omarchy must listen on `0.0.0.0` or the guest network interface, not only on the guest's own localhost.
The reverse direction does not need a mapping. From Omarchy, connect to `10.0.2.2:<Mac port>` to reach a service running on the Mac.
Requirements
[](https://github.com/themartiano/try-omarchy#requirements)
- Apple Silicon Mac (`arm64`)
- macOS 15 or newer
- At least 8 GB free initially
Data and updates
[](https://github.com/themartiano/try-omarchy#data-and-updates)
Normal launches keep one persistent VM under `~/Library/Application Support/Try Omarchy/VM/v1`. Removing the app does not remove this data. The start menu can reset it, and requires confirmation before replacing a disk that is incompatible with a new factory guest build.
Development requirements
[](https://github.com/themartiano/try-omarchy#development-requirements)
- Xcode command-line tools with Swift 6
- Python 3
- `pkg-config` (Homebrew is the simplest way to install it)
- A running Docker-compatible engine that supports privileged `linux/arm64` containers
- Roughly 20 GB free for guest, runtime, caches, and assembled output
Install the one Homebrew build tool with:
brew install pkg-config
`make doctor` performs the basic preflight. `make runtime` downloads a checksum-pinned `arm64_sequoia` dependency set, builds QEMU for macOS 15.0, and rejects any runtime image that raises that minimum or strongly imports an API unavailable on the declared platform. Installed Homebrew library versions are never copied into the app.
Build and run
[](https://github.com/themartiano/try-omarchy#build-and-run) For a first full build and launch:
make build run
The first build downloads pinned sources, assembles a multi-gigabyte guest, and compiles QEMU, so it can take a while. `make build` includes the basic toolchain check. Later builds hash the effective inputs and validate the existing outputs, then rebuild only the guest, runtime, or app components that changed. To bypass that cache deliberately, run `make build FORCE=1` (or add `FORCE=1` to an individual component command).
Artifacts created before their `.build/state/` record exists are rebuilt once; the cache never adopts an output whose successful inputs it did not observe.
Launching also ensures that the guest, runtime, and native app are current, so the normal follow-up command is:
make run
Run the complete contract and native test suite with:
make test
Run `make help` for component builds, persistent-storage reset, ephemeral mode, and cleanup commands.
To reclaim development build space, run:
make clean
This removes all repository build output, the native and guest build caches, and Try Omarchy's project-scoped Docker builder image and work volumes. It does not touch a developer's persistent VM.
For a complete local reset, first quit Try Omarchy and then run:
make clean-all
The deep cleanup also permanently deletes the current user's Try Omarchy VM disks and app state, plus stale Try Omarchy build and test directories in the macOS temporary directories. It only selects Docker resources and temporary paths owned by this project; it does not run a global Docker or system prune. To prevent accidental data loss, the command requires an interactive terminal and only proceeds after the developer types `clean-all` at the confirmation prompt.
Packaging and releases
[](https://github.com/themartiano/try-omarchy#packaging-and-releases) All generated output has one predictable home:
``` dist/ ├── Try Omarchy.app ├── TryOmarchy.dmg # after make package or make release └── guest/ # verified guest build artifacts ```
Both DMG targets create distributable artifacts:
- `make package` rebuilds the app, Developer ID-signs the app and DMG, notarizes the DMG with Apple, and staples the notarization tickets. It uses `PACKAGE_SIGN_IDENTITY` and `PACKAGE_NOTARY_PROFILE`, which default to the configured release credentials, and fails instead of producing an unnotarized fallback.
- `make release` performs the same signing and notarization workflow with the release-specific credential variables.
Maintainers should follow `docs/releasing.md` for the full build, test, signing, license, corresponding-source, and verification checklist.
Repository layout
[](https://github.com/themartiano/try-omarchy#repository-layout)
``` . ├── Makefile public build interface ├── macos/ Swift launcher and QEMU/HVF runtime builder ├── guest/ reproducible ARM64 factory-image builder ├── docs/ architecture and release documentation ├── dist/ generated output (ignored) ├── CONTRIBUTING.md ├── SECURITY.md ├── THIRD_PARTY_NOTICES.md └── LICENSE ```
The architecture and trust boundaries are documented in `docs/architecture.md`. Contributors should start with `CONTRIBUTING.md`.
Project status and support
[](https://github.com/themartiano/try-omarchy#project-status-and-support)
Try Omarchy is pre-1.0 and under active development. It is an independent open-source project and is not affiliated with or endorsed by Basecamp. Omarchy and bundled dependencies retain their own licenses; see `THIRD_PARTY_NOTICES.md`.
Report ordinary bugs through GitHub Issues. Report suspected vulnerabilities using the private process in `SECURITY.md`, not a public issue.
Try Omarchy's original code is licensed under the MIT License.
by @martiano