Troubleshooting

macOS: "Operum is damaged and can't be opened"

This happens because the app isn't signed with an Apple Developer certificate. To fix:

xattr -cr /Applications/Operum.app

Then try opening the app again.

Linux: Package installation fails

For Debian/Ubuntu, install missing dependencies:

sudo apt install -f

For Arch Linux, convert the .deb package:

yay -S debtap && sudo debtap -u
debtap Operum_*.deb
sudo pacman -U operum-*.pkg.tar.zst

Windows: Blocked by Windows Defender

Click "More info" on the warning dialog, then click "Run anyway". The app is safe but not yet recognized by Windows SmartScreen.

Browser doesn't open for login

Try manually opening the login URL. Check the Operum logs for the URL, or go directly to:

https://operum.ai/auth/app-login

Redirect back to app doesn't work

The operum:// deep link might not be registered. Try:

• macOS/Windows: Restart Operum
• Linux: Check that .desktop file is installed

As a workaround, copy the token from the browser and paste it in Operum's manual login option.

Session keeps expiring

On Linux, Operum uses the system keyring to store credentials. Ensure you have a keyring service running:

# For GNOME/KDE
gnome-keyring-daemon --start

# For Hyprland/Sway
# Add to your config:
exec-once = gnome-keyring-daemon --start --components=secrets

Agent won't start

Ensure Claude Code is installed and working:

claude --version

If not installed, follow the Claude Code installation guide.

Agent can't access GitHub

Check GitHub CLI authentication:

gh auth status

If not authenticated, run:

gh auth login

Agent seems confused or gives wrong responses

Try these steps:

1. Check the agent's CLAUDE.md template for errors
2. Clear the shared workspace files in local-agents/shared/workspace/
3. Restart the agent

Update notification appears but update fails

This can happen if the download is interrupted. Try:

1. Restart Operum and try the update again
2. Download the latest version manually from operum.ai/download

App reverted to old version after update

The update may not have completed properly. Download and install the latest version from the website.