Skip to content

QuickStart

Jump to bottom
Yannick Comte edited this page May 14, 2026 · 1 revision

Quick Start: Get the OpenXR OSX Runtime Running

This guide starts from a clean Apple Silicon Mac and walks through building the runtime, installing the Quest client, and launching a macOS OpenXR app through OpenXR OSX.

1. Install Dependencies

Install the base macOS tools:

xcode-select --install
brew install cmake ninja gradle adb-enhanced openjdk@17

Install the full Xcode app from the App Store or Apple Developer. The Command Line Tools alone are not enough for every Swift/Xcode target.

After installing or updating Xcode:

sudo xcodebuild -license accept
sudo xcodebuild -runFirstLaunch
xcodebuild -downloadComponent MetalToolchain

For Android, install Android Studio or the Android command-line tools, then install the required SDK and NDK packages:

sdkmanager --install \
  "platform-tools" \
  "platforms;android-34" \
  "platforms;android-35" \
  "build-tools;34.0.0" \
  "ndk;26.3.11579264" \
  "cmake;3.22.1"

The Android client uses Java 17. If Gradle cannot find Java, export JAVA_HOME:

export JAVA_HOME=$(/usr/libexec/java_home -v 17)

2. Build the macOS Runtime with CMake/Ninja

From the repository root:

cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build
ctest --test-dir build --output-on-failure

Important outputs are generated under build/runtime/:

  • build/runtime/libopenxr_osx.dylib
  • build/runtime/openxr_osx.json
  • build/runtime/openxr_osx.toml

openxr_osx.json is the manifest used by the OpenXR loader. openxr_osx.toml is the default runtime configuration copied into the build directory.

3. Configure the Runtime and Companion App

The runtime loads its configuration from:

~/Library/Application Support/OpenXR-OSX/openxr_osx.toml

If that file does not exist yet, it falls back to the build-directory copy:

build/runtime/openxr_osx.toml

The default configuration contains the main startup settings:

[general]
runtime_enabled = true

[streaming]
bitrate_mbps = 50
fov_degrees = 100
resolution_scale = 0.75
keyframe_interval_sec = 2
encoder_preset = "balanced"

[logging]
file_logging = true
quest_logcat = false

For apps launched from a terminal, the simplest setup is:

export XR_RUNTIME_JSON=$(pwd)/build/runtime/openxr_osx.json

For GUI apps launched from Finder, Steam, Unity, or Godot without a shell, register OpenXR OSX as the user OpenXR runtime:

./scripts/openxr_runtime_default.sh set
./scripts/openxr_runtime_default.sh status

To remove that registration:

./scripts/openxr_runtime_default.sh unset

You can also use the native OpenXR OSX Companion app. It edits the TOML configuration and registers or unregisters build/runtime/openxr_osx.json without using terminal commands.

Build the Companion app:

xcodebuild -project "clients/companion/OpenXR OSX Companion.xcodeproj" \
  -scheme "OpenXR OSX Companion" \
  -configuration Debug \
  build

In the Companion app, select the runtime manifest at build/runtime/openxr_osx.json, enable OpenXR registration, then save the configuration.

4. Build the Android Quest Client

Make sure clients/android-openxr/local.properties points to your Android SDK:

sdk.dir=/Users/<you>/Library/Android/sdk

Then build the APK:

cd clients/android-openxr
./gradlew assembleDebug

The debug APK is generated here:

clients/android-openxr/app/build/outputs/apk/debug/app-debug.apk

5. Install the APK on Quest

The Quest must be in Developer Mode. Connect it over USB, accept the ADB authorization prompt inside the headset, then verify the connection:

adb devices

Install with ADB:

cd clients/android-openxr
adb install -r app/build/outputs/apk/debug/app-debug.apk

You can also install the same APK with Meta Developer Hub: connect the Quest, open the device/app management section, and install app-debug.apk.

The installed app is named OpenXR OSX and uses this Android package id:

com.openxrosx.client

6. Launch the App on Quest

Inside the Quest:

  1. Open the app library.
  2. Go to Unknown Sources.
  3. Launch OpenXR OSX.

On startup, the app searches for the runtime on the local network. The screen stays blue while it waits for a connection. When a macOS OpenXR app starts and streaming begins, the screen may stay blue during the initial load. Once the first video frames arrive, the OpenXR app content appears in the headset.

The Mac and Quest must be on the same local network. Avoid guest or isolated Wi-Fi networks that block broadcast, multicast, or local device traffic.

7. Launch an OpenXR App: AeroSyncFS.app

Example app: AeroSyncFS.app

https://demonixis.itch.io/aerosyncfs

The app is pay what you want, so it can be downloaded for free by choosing zero as the price.

Workflow:

  1. Launch OpenXR OSX on the Quest and leave it on the blue waiting screen.

  2. On the Mac, make sure the runtime is registered with the Companion app or with:

    ./scripts/openxr_runtime_default.sh set

  3. Launch AeroSyncFS.app normally from Finder.

  4. When the app creates its OpenXR session, the runtime starts streaming to the Quest.

  5. The Quest switches from the blue screen to the rendered AeroSyncFS content.

If you prefer launching from a terminal instead of using global registration:

export XR_RUNTIME_JSON=/path/to/openxr_osx/build/runtime/openxr_osx.json
open /path/to/AeroSyncFS.app

8. Unity

Unity can use the runtime without launching the project from the command line.

The repository provides this Editor helper:

scripts/unity/Editor/OpenXRRuntimeAutoSelector.cs

Copy it into your Unity project:

Assets/Editor/OpenXRRuntimeAutoSelector.cs

The script adds a Tools/OpenXR menu to the Unity Editor. It sets the OpenXR runtime environment variables for the current Unity process:

  • XR_RUNTIME_JSON
  • XR_SELECTED_RUNTIME_JSON
  • OTHER_XR_RUNTIME_JSON

Unity workflow:

  1. Build the runtime so build/runtime/openxr_osx.json exists.
  2. Open the Unity project normally from Unity Hub or Finder.
  3. In Unity, use Tools/OpenXR > Use OpenXR OSX Runtime.
  4. If the script cannot find the manifest automatically, select build/runtime/openxr_osx.json.
  5. Enter Play Mode or run your Unity build as usual.

The important point: with this helper, you do not need to launch Unity from a terminal just to inject XR_RUNTIME_JSON. The runtime selection is applied inside the current Unity Editor session.

9. Godot

Godot also works, but the most reliable workflow during debugging is still to launch it with the OpenXR environment from the command line.

From the OpenXR OSX repository root:

export XR_RUNTIME_JSON=$(pwd)/build/runtime/openxr_osx.json
open -a Godot

Or open a project directly:

export XR_RUNTIME_JSON=/path/to/openxr_osx/build/runtime/openxr_osx.json
/Applications/Godot.app/Contents/MacOS/Godot --path /path/to/your/project

You can also register the runtime globally before launching Godot from Finder:

./scripts/openxr_runtime_default.sh set

But for quick validation that a Godot session is using OpenXR OSX, launching it with an explicit XR_RUNTIME_JSON is the most direct path.

Quick Checklist

  1. cmake --build build passes.
  2. ctest --test-dir build --output-on-failure passes.
  3. build/runtime/openxr_osx.json exists.
  4. The runtime is registered with the Companion app or scripts/openxr_runtime_default.sh set.
  5. clients/android-openxr/local.properties points to the Android SDK.
  6. ./gradlew assembleDebug produces app-debug.apk.
  7. The APK is installed on the Quest.
  8. OpenXR OSX is launched from Unknown Sources.
  9. A macOS OpenXR app is launched: AeroSyncFS, Unity, or Godot.

Clone this wiki locally