Pairing code rejected or expired
Codes are 6 letters (uppercase, with easily-confused I and O never used) and expire after 5 minutes — generate a fresh one from the Mac's Remote Access settings if it sat around. Both devices must be talking to the same relay: if you self-host, check the Server URL on the Mac before pairing.
Can't connect to a self-hosted relay
First verify the relay itself: curl https://your-domain.com/healthshould return {"status":"ok"}. If that works but the apps don't, your reverse proxy is likely not forwarding WebSocket upgrades — theUpgrade and Connection headers must pass through. Note the iPhone requires WSS (HTTPS); plain HTTP relays are Mac-only.
"Please update" on connect
The relay can enforce a minimum app version. If you see a too-old error, update the Mac or iOS app — the message names the version required.
No push notifications
- Check iOS notification permission for Gallager.
- On the hosted relay, check your trial/subscription state in the Mac's Remote Access settings.
- Self-hosting? Pushes need your APNs key configured — check the relay logs for "APNs client initialized", and make sure
APNS_ENVIRONMENTmatches your build (development for Xcode builds, production for TestFlight/App Store).
License won't activate
"license_key not found" after pasting a key usually means an invisible line break or space came along from the email — embedded whitespace makes it a different string. Re-copy the key carefully, or paste it into a plain-text field first to check.
The Mac went to sleep
While sessions are active, Gallager holds a sleep-prevention assertion so an open-lid Mac stays awake ("Prevent sleep during active sessions" in Settings). Closing the lid on battery still sleeps the machine. Agents live inside tmux, so nothing is lost either way — when the Mac wakes and reconnects, sessions are exactly where they were.
tmux missing
Gallager needs tmux and will walk you through installing it on first launch — it detects Homebrew or MacPorts, shows the right command with a copy button, and continues automatically once tmux appears.
A TUI's keyboard acts differently in Gallager
The mirrored terminal intentionally stays in standard keyboard mode: kitty keyboard-protocol negotiation is stripped so panes render identically on Mac and iPhone. Apps that probe for it will fall back to normal key handling.
Where the logs are
- Relay (self-hosted):
docker compose logs -fon the server. - Agent plugins:
~/.gallager/state/plugins/<id>/logs/on the Mac.