How to Use the OPAL Portable Version

OPAL ships as a native installer for each platform — a .dmg for macOS, a .exe for Windows, and an AppImage or .deb for Linux. For most users, that’s the right choice.

But not everyone can install software freely. Enterprise-managed Windows machines often require admin approval for any installer. Some environments block .exe files entirely. On macOS, Gatekeeper may reject an unnotarized app without a straightforward bypass. And on some locked-down Linux setups, AppImages run into sandbox restrictions.

The portable version exists for exactly these situations. It is a self-contained ZIP archive that requires nothing from the operating system. Extract it, run it, done.

What the portable version is

The portable version bundles everything OPAL needs to run:

A Python runtime (the official Python embeddable build, signed by the Python Software Foundation)
All backend dependencies, pre-installed at build time
The compiled frontend static files
A launcher script that finds a free port, starts the backend, and opens OPAL in your browser

Nothing is installed on your system. Nothing is written outside the extracted folder. Your workspace data — workspaces, environments, Oracle credentials — is stored in a data/ subfolder inside the extracted directory. Move the folder and your data moves with it.

When to use the portable version

Use the portable version when:

Your machine requires admin rights to run installers and you don’t have them
Your IT policy blocks .exe or .dmg installers
You want to run OPAL from a USB drive or shared network folder
You’re troubleshooting a broken install and want to test without touching your system

Use the native installer when:

You have a standard personal or work machine with normal install permissions
You want OPAL to appear in your Applications folder (macOS) or Start Menu (Windows)
You prefer automatic updates via the installer

How to download the portable version

Go to the OPAL download page and scroll to the Portable version section. Click Download .zip.

The file is named OPAL-portable.zip.

How to set up and run OPAL portable

Windows

Extract OPAL-portable.zip to any folder — for example, C:\Tools\OPAL-portable\
Inside the extracted folder, double-click start.bat
A terminal window opens briefly while the backend starts
OPAL opens automatically in Chrome or Edge in app mode (no browser toolbar)
If Chrome and Edge are not installed, OPAL opens in your default browser instead

That’s it. No installation. No admin prompt.

macOS

Extract OPAL-portable.zip to any folder
Open Terminal, navigate to the extracted folder
Run: ./start.sh
OPAL opens in Chrome or your default browser

If macOS blocks start.sh, make it executable first:

chmod +x start.sh
./start.sh

Linux

Extract OPAL-portable.zip to any folder
Open a terminal in the extracted folder
Run: ./start.sh
OPAL opens in Chrome or your default browser

Make it executable if needed:

chmod +x start.sh
./start.sh

Where is my data stored?

Your data — workspaces, Oracle environments, credentials, request history — is stored in the data/ folder inside the extracted directory.

OPAL-portable/
  data/          ← your workspace data lives here
  backend/
  frontend/
  python/
  start.bat
  start.sh
  start.py

This means:

Moving the folder moves all your data with it
Deleting the folder deletes all your data — make a copy first if needed
You can run multiple copies of the portable version side-by-side with separate data folders

Troubleshooting

The terminal window opens and immediately closes (Windows)

The backend failed to start. Common causes:

Another process is using the same port. The portable version picks a free port automatically, so this is unlikely — but try restarting your machine and running again.
Antivirus software blocked python.exe inside the portable folder. Add the OPAL portable folder to your antivirus exclusions.

To see the error: right-click start.bat, choose Edit, and run it from an open terminal window instead of double-clicking.

Chrome or Microsoft Edge is not installed on your machine. OPAL falls back to your default browser in this case, which shows the normal browser UI. The app works the same — it just looks more like a website. Install Chrome or Edge if you prefer the cleaner app-mode experience.

”Permission denied” when running start.sh (macOS / Linux)

Make the file executable:

chmod +x start.sh

Then run it again.

I want to move OPAL to a different folder

Close OPAL (Ctrl+C in the terminal or close the terminal window). Move the entire OPAL-portable/ folder to the new location. Run start.bat or start.sh again from the new location.

Differences from the native installer

	Native installer	Portable version
Installation required	Yes	No
Admin rights needed	Sometimes	No
Appears in Start Menu / Applications	Yes	No
Data location	System app data folder	Inside the portable folder
Automatic updates	Via installer	Manual — download new ZIP
Launch	Desktop shortcut or menu	`start.bat` / `start.sh`

Both versions have the same features. The portable version is not limited in any way — Free and Pro licenses work the same in both.

Updating the portable version

The portable version does not auto-update. To update:

Download the new OPAL-portable.zip from the download page
Extract it to a new folder
Copy your data/ folder from the old portable folder into the new one
Run the new version

Your workspaces, environments, and history are all in data/ — copying that folder is all you need.

Still stuck? Email [email protected] — we respond within 24 hours on business days.