Oblivion Desktop on macOS

Choose Intel or Apple silicon

Open Apple menu → About This Mac. A Chip entry identifies Apple silicon; an Intel Processor entry means you need x64. You can check this without installing anything. Apple’s identification guide

Check macOS before downloading. Both 3.11.0 ZIP app bundles declare macOS 12.0 Monterey as their minimum and contain Electron 39.1.1. The release table still says 10.15+, which conflicts with those files and Electron’s macOS requirements. Do not rely on the table for Catalina or Big Sur. macOS 12 is a minimum declared by the bundles, not a guarantee that every feature works on every later version.

Version 3.11.0 was the latest stable Desktop release when we checked on 5 November 2026. The Desktop repository is archived. This guide covers that product, not the separate Oblivion app.

Asked to install Rosetta? Check which copy you opened: select it in Finder and choose File → Get Info → Kind. If it says Intel on an Apple silicon Mac, replace that copy with the arm64 package above. Rosetta runs Intel software; it is not a repair for a damaged download. Apple’s Rosetta guide

Install from DMG or ZIP

DMG is the straightforward choice. Both formats contain the app; ZIP is an alternative archive, not an updater.

1. Download the package matching your processor from the links above. Do not use GitHub’s Source code archives as an installer.
2. For DMG, open the disk image and drag the app into Applications. For ZIP, extract it in Finder, then move the complete .app into Applications.
3. Open the copy in Applications. For DMG, eject the mounted image after copying; do not keep launching a second copy from the image or Downloads.

The ZIP bundles contain oblivion-desktop.app, so the normal destination is:

/Applications/oblivion-desktop.app

Older instructions use different capitalization or spaces. If you renamed or moved the app, use its actual path. A “No such file” error in Terminal means the path does not match; it does not establish a signing problem. To get the path without guessing, drag the app from Finder into a Terminal window without executing a command.

First launch and permissions

The project’s launch guide says its macOS app is not Developer ID signed and notarized. Building it on GitHub does not certify its safety. Match your warning to the next section before changing settings.

For a warning about an unverified developer or an app Apple cannot check, Apple provides an app-specific exception: after trying to launch it, open System Settings → Privacy & Security → Open Anyway, then confirm only if you trust the downloaded app. This is not a general fix for a damaged-file or malware warning. Apple’s explanation of launch warnings

No Open Anyway button? Try opening the Applications copy first, then revisit Privacy & Security. A managed Mac can restrict these settings; contact its administrator. If the warning says the app is damaged, use the damaged-file steps below rather than looking for a global override.

When a connection needs Oblivion-Helper, macOS can request an administrator password. The 3.11.0 helper launcher uses this permission to manage network connections. It is separate from permission to open the app. Approve only a prompt triggered by your own connection attempt. Cancelling can prevent that connection; on a managed Mac, ask the administrator if permission is unavailable.

Before connecting, check that a normal website opens. Then connect, test the site again, disconnect, and retest. Finally quit the app and check once more. A connection label alone does not confirm that browsing works or that settings were restored.

“Is damaged and can’t be opened”

Keep the full warning: damaged, unverified developer and will damage your computer need different responses. A damaged warning is not proof that the file is harmless or merely unsigned. If macOS reports malware or says the app will damage your computer, leave it blocked. What Apple’s alerts mean

For a damaged warning:

1. Confirm the CPU package and macOS version above, then quit any existing copy.
2. Remove the failed app copy and download a fresh package from the linked Desktop release. Keep your saved settings; deleting them does not repair a downloaded bundle.
3. Copy it to Applications and try once more. If it still fails, retain the filename, macOS version and exact message for diagnosis. Do not repeatedly reinstall or disable protection for all apps.

The older report #206 concerned early beta releases. Some users succeeded after removing quarantine attributes; another needed a local re-sign. Those outcomes do not establish a reliable 3.11.0 fix. The wiki’s global Gatekeeper workaround is therefore not part of these installation steps.

Why no one-line Terminal repair? Removing quarantine changes the download’s security metadata; ad-hoc signing changes its signature. Neither verifies that the package is authentic. If a fresh official package remains blocked, save the evidence and stop at this point. There is no verified 3.11.0 workaround in this guide for a persistent damaged-app warning on either Intel or Apple silicon.

TUN and DNS on macOS

Do not copy the old manual DNS recipe into a 3.11.0 installation. The project’s macOS DNS guide explicitly says DNS handling became automatic in 2.40. Its older instructions to add 172.19.0.2 and 1.1.1.1 belong to the earlier workaround.

TUN uses the helper to handle network traffic. System Proxy instead configures a system proxy; apps that ignore that proxy may behave differently. Choose the mode you intend to test and keep it unchanged during the before/connect/disconnect/quit checks. See the network-mode overview if only some apps work.

Automatic DNS handling does not prove there are no DNS leaks on your network. Check ordinary name resolution and any privacy requirements separately. DNS changes and restoration by the current helper have not been verified on a Mac for this guide.

No internet after disconnecting or quitting

First try reopening Desktop, disconnecting normally, and quitting again. If browsing still fails, inspect the active Wi-Fi or Ethernet service rather than resetting every network setting.

• After System Proxy: open System Settings → Network → your service → Details → Proxies. Compare the SOCKS proxy with the address and port you used in Desktop. If it is a leftover setting from this app, turn it off and retest. Preserve the previous values so you can restore a required work proxy. The macOS code configures SOCKS; do not remove unrelated HTTP, HTTPS or automatic proxy settings. Apple’s proxy settings
• After TUN or an older manual DNS setup: open the same service’s DNS settings. Record the current list, then restore the values used before your changes. Remove the old 172.19.0.2 entry only if you added it for that workaround. Keep DNS servers required by your network. Apple’s DNS settings

These menu paths use the newer System Settings interface. On Monterey, look under System Preferences → Network → your service → Advanced, then DNS or Proxies.

Retest with Desktop disconnected. If the change does not help, restore the recorded values and use the connection troubleshooting checklist. If you do not know the original configuration on a managed network, get it from its administrator before editing.

Update or remove the app

To update: save any settings you need, disconnect and quit, then replace the Applications copy using a newer matching package from Desktop releases. Check the version after reopening. A release note about Helper or Proxy-Reset is not a guarantee that your particular network problem is fixed.

To remove: disconnect, quit, and verify that browsing works first. Move the app from Applications to Trash. Removing the app bundle is not a full settings reset and does not establish that a leftover proxy or DNS setting has been restored. If browsing already fails, follow the recovery checks above before removing the app.

For a settings backup, a reversible reset or full removal, follow the recovery and removal guide.

The app will not quit or prevents shutdown

Closing the window may leave Desktop running in the menu bar. Disconnect, then use the app’s Quit command. If it is unresponsive, use Apple menu → Force Quit, select Desktop, and force it to quit. Check connectivity afterwards because forced termination can interrupt cleanup. Apple’s quit instructions

A historical shutdown report #869 includes a user’s confirmation that 2.84.1 resolved their case. That does not prove every shutdown problem is fixed in 3.11.0. If it recurs, record whether you used TUN or System Proxy and whether normal disconnection completed before shutdown. If the Mac still cannot restart, follow Apple’s linked recovery instructions after saving other work where possible.

If the problem remains

Keep the Desktop version, package filename, Intel/Apple silicon chip, macOS version, exact warning and the point where it fails: opening, connecting, disconnecting or quitting. If the app opens, save its log before another connection attempt replaces useful details. The default macOS log location is:

~/Library/Logs/oblivion-desktop/main.log

Use Finder → Go → Go to Folder to reach the containing folder. Before sharing a log, remove account keys, tokens, usernames and private network details. If the app never opened, a system warning is more useful than an unavailable app log. Continue with the help hub or review release changes.

Scope: Desktop 3.11.0, reviewed 5 November 2026. Package information is based on the release files. Installation, first-launch warnings and DNS restoration have not been verified on Intel or Apple silicon Macs for this guide.