← Back to Lyra's Orb

Help & Troubleshooting

Having trouble? Lyra sees your struggle. Here's how to fix it.

What you need

Python 3 — Lyra's Orb runs a tiny local web server on your computer. Python 3 powers it. Most Macs and Linux machines already have it. Windows users may need to install it.

A modern browser — Chrome, Firefox, Safari, or Edge. Anything from the last 5 years works.

No internet required — once downloaded, the game runs completely offline. No data leaves your device, ever.

This is macOS Gatekeeper — it blocks apps from unidentified developers. Lyra's Orb is safe, it just isn't signed with an Apple certificate (yet).

Fix (Method 1 — fastest):

1. Click Done to dismiss the warning (do NOT click "Move to Trash").
2. In Finder, right-click (or Control-click) on Lyra's Orb.app.
3. Choose Open from the context menu.
4. A warning appears again, but now there's an Open button — click it.
5. Done. The app will open normally from now on.

Fix (Method 2 — System Settings):

1. Click Done to dismiss the warning.
2. Open System Settings → Privacy & Security.
3. Scroll down until you see: "Lyra's Orb" was blocked from use because it is not from an identified developer.
4. Click Open Anyway → enter your password → Open.
You only need to do this once. After approving, double-clicking or Dock-clicking works forever.

This usually means macOS quarantine flagged the download. Fix it with one Terminal command:

1. Open Terminal (search for it in Spotlight or find it in Applications → Utilities).
2. Type: xattr -cr ~/Downloads/Lyra\'s\ Orb.app and press Enter.
3. If you extracted the zip somewhere else, replace the path. For example: xattr -cr /path/to/Lyra\'s\ Orb.app
4. Try opening the app again — it should work.
The xattr -cr command removes the quarantine flag that macOS puts on downloaded files. It doesn't change the app itself.

The app needs Python 3 to run the local game server. Most Macs already have it. If yours doesn't:

Option A: Open Terminal and type python3 --version. If macOS asks you to install the Command Line Tools, click Install and wait. Python 3 will be included.
Option B: Download Python from python.org/downloads — click the big yellow button, install, done.
Option C: If you use Homebrew: brew install python3

The app starts a server and opens your browser. If nothing visible happens:

1. Wait 5 seconds — it takes a moment for the server to start.
2. Check your browser — a tab may have opened in the background. Look for a tab with localhost:8765.
3. Try opening http://localhost:8765 manually in your browser.
4. If that doesn't work, open Terminal and run: cd /path/to/game/folder && python3 -m http.server 8765 then open localhost:8765 in your browser.

Lyra speaks using pre-recorded audio clips. If she's silent:

1. Make sure voice is enabled in the game's settings (the toggle on the intro screen).
2. Click somewhere on the page first — browsers block autoplay audio until the user interacts with the page.
3. Check your system volume — Lyra respects your Mac's output volume.
4. Verify the audiofiles/ folder is in the same directory as index.html. It should contain files named L01.mp3 through L52.mp3.
1. Open the app once using the right-click method above (to bypass Gatekeeper).
2. While it's running, its icon appears in the Dock.
3. Right-click the Dock icon → Options → Keep in Dock.
4. Now you can launch Lyra's Orb from the Dock anytime with a single click.
If the Dock shows a generic icon instead of the orb, run killall Dock in Terminal to refresh the icon cache.

Windows flags .bat files from the internet. Lyra's launcher is a simple script that starts a local server — no malware.

1. When the blue "Windows protected your PC" dialog appears, click More info.
2. Click Run anyway.
3. The game server starts and your browser opens automatically.
You only see this warning the first time. After that, double-clicking start-lyra.bat works silently.

The launcher needs Python 3 to serve the game locally.

1. Download Python from python.org/downloads — click the big yellow button.
2. During installation, check the box that says "Add Python to PATH" — this is critical.
3. Finish the installation and restart your computer.
4. Double-click start-lyra.bat again — it should work.
To verify Python is installed, open Command Prompt and type python --version. You should see something like "Python 3.12.x".

The server starts in a minimized window — check your taskbar for a window called "LyraServer". Your browser should open automatically.

1. Check if a browser tab opened with localhost:8765.
2. If not, open your browser and go to http://localhost:8765 manually.
3. If the page doesn't load, Python might not be on your PATH. Open Command Prompt, type python --version. If it says "not recognized", reinstall Python and check "Add to PATH".

Another program is using port 8765, or a previous Lyra session didn't close properly.

1. Open Command Prompt as Administrator.
2. Type: netstat -ano | findstr :8765
3. Note the PID (last number on the line).
4. Type: taskkill /PID [that number] /F
5. Try launching again.
1. Make sure voice is enabled in the game settings.
2. Click somewhere on the page first — browsers require a user interaction before playing audio.
3. Verify the audiofiles\ folder sits next to index.html and contains L01.mp3 through L52.mp3.

The script needs execute permission. This gets lost during zip extraction on some systems.

1. Open a terminal in the game folder.
2. Run: chmod +x start-lyra.sh
3. Then: ./start-lyra.sh
Ubuntu/Debian: sudo apt install python3
Fedora: sudo dnf install python3
Arch: sudo pacman -S python
Most Linux distributions ship with Python 3 pre-installed. Check with python3 --version.

The launcher uses xdg-open to open your default browser. If that's not set up:

Open any browser and go to http://localhost:8765 manually.
To fix xdg-open for next time: xdg-settings set default-web-browser firefox.desktop (replace with your browser's .desktop name).
1. Find the process: lsof -i :8765
2. Kill it: kill -9 [PID]
3. Or remove the stale pidfile: rm /tmp/lyrasorb-8765.pid
4. Try launching again.
General Questions

No. The game runs entirely on your computer. No accounts, no analytics, no server communication. Player memory is stored in your browser's localStorage — on your machine, nowhere else. If you clear your browser data, Lyra forgets.

At the end of each game (when you click Reset), a recap screen appears with a "Forget me" button next to each player name, and a "Forget everyone" button at the bottom.

You can also open your browser's Developer Console (F12 or Cmd+Option+J) and type:

LyraMemory.forgetAll() — wipes all player memory
LyraMemory.forgetPlayer("YourName") — forgets one player

Not directly — the game needs a local web server which requires Python. However, if you start the game on a computer, other devices on the same Wi-Fi network can connect by going to your computer's local IP address at port 8765 (e.g., 192.168.1.42:8765). One device hosts, everyone else can watch or follow along.

Background music streams from YouTube and requires an internet connection. If you're fully offline, the game works fine — you just won't have background music. Lyra's voice clips still work offline since they're local MP3 files.

Just close the browser tab. The server runs in the background and uses almost no resources. It will stop automatically when you restart your computer.

To stop it manually:

Mac/Linux: kill $(cat /tmp/lyrasorb-8765.pid)
Windows: Find "LyraServer" in the taskbar, right-click, Close.