Guide
Troubleshooting
Fixes for the failures you are most likely to hit, from the hot key to phone pairing.
The hot key does not open the dock
Another app may already own ⌃⌥Space. Open Settings and set a different hot key, then try again. The dock also opens from the glass tab on the right edge of any screen, so you can reach it while you sort the conflict out.
A session will not start
Check that your agent's CLI is on your PATH: claude for Claude Code, codex for OpenAI Codex. Orb runs the CLI you installed and never installs it for you, so if the command is missing from your shell, the session cannot launch. Container profiles also need macOS 26 (Tahoe) on Apple Silicon.
The phone will not pair
Work through these in order:
- On the same network, confirm both devices are on the same Wi-Fi, then re-scan the QR code in the dock header.
- Away from home, run Tailscale on both the Mac and the phone and confirm both are on your tailnet. Orb operates no relay, so the two devices must be able to reach each other directly.
- Your Mac must be awake. It is the device doing the work and the sending, so a sleeping Mac cannot pair or push a notification.
- If a paired device stops connecting, revoke its key in Settings, under Devices, and pair again with a fresh scan.
More on how pairing works is on the mobile pairing page.